管理 API 工作流

创建 API 工作流

要创建 API 工作流解决方案：

1. 在您的 Automation Cloud™ 组织中，打开 Studio Web。
2. 选择“新建” > “API 工作流” 。系统将打开一个新的解决方案，并显示API 工作流设计器画布。

定义输入模式

API 工作流通常需要来自调用方的输入。这可以通过为输入和输出定义 JSON 对象来处理，每个对象都遵循一个 JSON 架构。这些架构为您的对象建立数据类型和结构。定义的对象可以包括嵌套对象、多个属性和数组，使您可以根据需要对复杂的数据结构进行建模。

输入架构指定触发工作流时外部服务必须提供的数据结构。

您可以通过上传 JSON 有效负载或手动定义输入参数来配置输入架构。

1. 在 API 工作流项目中，打开“数据管理器”面板。
2. 选择“输入”选项卡。要上传 JSON 架构，请按照第 3 步执行。要手动定义输入参数，请按照第 4 步执行。
3. 要上传已定义输入参数的 JSON 架构，请选择“从有效负载生成” 。
   1. 提供具有预期输入的 JSON。
   2. 选择“生成架构” 。
   3. 查看生成的架构，并在必要时向属性添加说明。
4. 要手动定义输入参数，请选择“添加属性” 。
   1. 配置属性详细信息：
      • 名称— 定义属性键
      • “类型” — 从“字符串”、“数字”、“整数”、“布尔值”、“对象”、“数组”、“日期时间”、“日期”、“时间”中选择。
        重要提示：

        如果您使用的是对象或数组，请定义嵌套项目的属性。

      • “必需” — 选中此框可将属性标记为“必填”。
   2. 重复该步骤，直到定义了所有输入参数。

定义输出模式

输出架构定义了 API 工作流返回的数据的结构，以确保调用工作流的任何服务提前理解输出格式。当工作流包含“响应”活动时，它也是必需的，因为它决定了发送回调用方的确切数据。

备注：

目前，系统不强制执行架构验证，因此，如果“响应”活动中返回的数据包含的属性更多或少于输出架构中定义的属性，工作流不会失败。

输出架构包含在架构本身中显式定义的字段（例如 ID 或用户提供的值），以及从工作流步骤动态生成的输出，例如 API 响应或计算的值。

您可以通过上传 JSON 有效负载或手动定义输出参数来配置输出架构。

1. 在 API 工作流项目中，打开“数据管理器”面板。
2. 选择“输出”选项卡。要上传 JSON 架构，请按照第 3 步执行。要手动定义输出参数，请按照第 4 步执行。
3. 要上传具有已定义的输出参数的 JSON 架构，请选择“从有效负载生成” 。
   1. 提供包含预期输出的 JSON。
   2. 选择“生成架构” 。
   3. 查看生成的架构，并在必要时向属性添加说明。
4. 要手动定义输出参数，请选择“添加属性” 。
   1. 配置属性详细信息：
      • 名称— 定义属性键
      • “类型” — 从“字符串”、“数字”、“整数”、“布尔值”、“对象”、“数组”、“日期时间”、“日期”、“时间”中选择。
        重要提示：

        如果您使用的是对象或数组，请定义嵌套项目的属性。

      • “必需” — 选中此框可将属性标记为“必填”。
   2. 重复该步骤，直到定义了所有输出参数。

使用表达式编辑器

表达式编辑器可帮助您访问、评估和操作 API 工作流中的数据。使用它来创建条件逻辑、配置活动字段或编写 JavaScript 活动。

表达式编辑器布局

表达式编辑器的布局包含以下面板：

面板	描述
输入	主面板是输入面板，您可以在其中编写 JavaScript 或 JQ 表达式。此面板包含一个内置的语法检查器，可识别并突出显示表达式语法中的错误。
Autopilot 表达式生成器	Autopilot 表达式生成器位于输入面板的底部，可帮助您使用自然语言创建工作流表达式，而不是编写 JavaScript。Autopilot 可以理解工作流的上下文，使您能够通过描述预期结果来引用对象和工作流步骤。
活动测试输入	在代码面板的右侧，您可以通过“活动测试输入”面板查看从先前的工作流运行生成的测试数据。它提供可用于构建和验证表达式的示例数据，并直接与“表达式输出”面板交互，以确保表达式产生所需的结果。
表达式输出	“表达式输出”面板根据来自活动测试输入数据的数据显示表达式的结果。这使您可以验证表达式是否生成了预期结果。如果表达式有错误，表达式输出部分会高亮显示有问题的表达式，并提供相应的错误消息。每当您修改输入面板中的表达式时，结果都会自动更新。

使用 JavaScript 访问数据

工作流数据有几个访问点：

• $workflow — 指的是工作流级别的配置。
• $context — 指的是活动级别的配置。
• $input — 引用先前执行的活动配置。
• $context.variables — 指的是变量级别配置。
  重要提示：

  在构建表达式时，使用“表达式编辑器”中的“测试输入”屏幕引用步骤属性。

接入点	描述	如何使用
$workflow.input	存储请求架构以及测试配置中定义的任何值。	要在表达式编辑器中访问测试配置数据，请输入以下语法，然后将{property_name}替换为要引用的特定属性： $workflow.input.{property_name}
$context	存储每个活动的输入和输出数据。要在表达式中引用这些属性，请先运行和调试工作流 。这将生成在“测试输入”屏幕中可见的步骤级别的输入和输出。	要访问特定步骤的输出响应数据，请在“表达式编辑器”中使用以下语法模式 ，并分别将{step_name}和{property_name}替换为您的步骤名称和属性名称： $context.outputs.{step_name}.content.{property_name}
$input	存储从上一步直接传递到当前步骤的数据。使用$input引用上一步中的属性，而无需浏览整个$context 。	要访问上一步中的属性，请使用以下语法，并将{property_name}替换为您要引用的属性： $input.{property_name}

测试 API 工作流

为了成功实现 API 工作流集成，请尽早频繁测试您的工作流。定期测试有助于快速识别并解决错误。IntelliSense、自动完成、Autopilot 和活动测试输入屏幕等功能取决于测试数据。使用“测试”按钮定期执行工作流以生成此数据。

测试可确保：

• 工作流步骤之间的数据映射正确无误，可防止意外行为。
• 已正确配置 API 请求，确保可靠的响应。
• 您的工作流将按预期执行，从而降低生产中出现意外错误的风险。

了解运行输出信息

“运行输出”面板提供有关工作流执行的详细信息。

活动输入和输出数据

此数据根据选定的活动可用，并提供：

• 输入数据— 步骤从上一个活动接收的信息。
• 输出数据— 当前步骤产生的、传递到下一个活动的信息。

审核输入/输出数据以确认映射和数据转换准确无误。

API 请求信息

当工作流与 API 交互时，请验证以下请求详细信息：

• 请求 URL — 确认正确解析动态 URL 参数。
• 标头— 确保正确设置身份验证标头和内容类型标头。
• 查询参数— 检查筛选条件和参数的格式是否正确。
• 正文内容— 验证 JSON 结构是否符合 API 要求。

成功的 API 请求

对于成功的 API 请求，请展开每个步骤进行审核：

• **请求详细信息 — **URL、标头、查询参数和正文内容。
• **响应详细信息—**状态代码、标头和响应内容。
• **输出数据—**由 API 调用生成的用于后续工作流步骤的信息。

调试

要高效识别和调试工作流错误，请遵循以下准则：

• 错误指示器
  • 遇到错误的步骤将显示错误图标。
  • 选择步骤以查看详细的错误消息和输出。
• 常见调试步骤
  • 验证 API 请求— 确保 URL、标头、参数和正文内容等请求详细信息与 API 文档相符。
  • 查看错误消息— 检查错误消息，寻找有关身份验证错误、不正确的有效负载或脚本错误的线索。

添加调试配置

您可以以迭代方式构建和测试 API 工作流，在添加新活动时验证每个步骤。要有效运行这些测试，您可以使用调试配置功能定义特定的输入数据。这使您设置了一次 JSON 输入并在所有后续测试运行中重复使用。在工作流执行期间，您可以通过$workflow.input对象访问模拟的数据。

要添加“调试”配置：

1. 在 API 工作流设计器画布顶部，打开“调试”下拉列表，然后选择“调试配置” 。
2. 在打开的窗口中，在可用字段中提供测试输入数据，或上传 JSON 格式的有效负载。
3. 保存测试配置。
4. 保存后，您可以使用引用$workflow.input.{propertyname}在“表达式编辑器”中访问测试配置。此外，调试配置也会显示在表达式编辑器的活动测试输入面板中。

调试 API 工作流

要调试 API 工作流，请执行以下操作：

1. 打开 API 工作流。确保您的工作流已完全配置并准备运行。
2. 如果您的工作流依赖于输入数据（例如来自外部系统的数据），请在测试前定义调试配置。这可确保每个步骤都收到必要的数据。
3. 调试您的工作流。“调试”按钮位于页面顶部。选择它以执行工作流并查看实时结果。
4. 调试开始后， “运行输出”面板将显示在屏幕右侧。在这里，您可以看到清楚标记为successful 、失败或待处理 的每个步骤执行状态。

发布 API 工作流

重要提示：

在发布之前，请使用成功场景和失败场景测试 API 工作流，以确认每个场景都能正确执行。

要发布 API 工作流解决方案，请执行以下操作：

1. 在 API 工作流设计器画布上，选择“发布” 。

2. 选择应发布 API 工作流的位置:

   • 您的 Orchestrator 个人工作区订阅源
   • 您的 Orchestrator 租户订阅源

3. 提供对 API 工作流重要的其他详细信息，例如“更改日志”和“版本” 。

4. 选择“发布” 。系统会显示一条通知，通知您已成功发布 API 工作流。

   如果您发布到个人工作区订阅源，则该工作流将显示在 Orchestrator 中的“我的工作区”>“自动化”>“流程”下。API 工作流可按类型API标识。

   如果已发布到租户订阅源，则该工作流将显示在 Orchestrator 中的“租户” > “解决方案”下。API 工作流可按类型API标识。

部署 API 工作流

将 API 工作流发布到首选项的订阅源后，您需要部署解决方案。

从个人工作区订阅源部署 API 工作流

发布到您的个人工作区时，系统会将 API 工作流准备为“Orchestrator”>“我的工作区”>“您的 API 工作流名称”子文件夹 >“自动化”>“流程”中的流程。

重要提示：

系统将在您的个人工作区文件夹中自动创建一个专用子文件夹。

从租户订阅源部署 API 工作流

发布到 Orchestrator 租户会将 API 工作流包上传到Orchestrator >“租户”>“解决方案” 。

要将其部署为流程：

1. 转到“Orchestrator” >“租户” >“解决方案” 。
2. 对于您先前发布到租户订阅源的 API 工作流包，选择三点菜单，然后选择“部署包” 。
3. 在“部署解决方案版本”向导上，配置以下详细信息：
   1. 部署名称— 添加要在所有提及、列出或监控流程的页面上显示的名称。如果留空，则使用包的名称。
   2. 目标文件夹— 指定要用作解决方案根目录父文件夹的文件夹。解决方案未部署在选定的文件夹中，但系统已创建一个新的子文件夹。
   3. “在租户下作为新的根文件夹安装” — 选中此复选框可将解决方案安装为当前租户下的新根文件夹。
   4. 解决方案根文件夹名称— 更改根文件夹名称。
4. 选择“审核”。您现在可以将解决方案另存为草稿，或对其进行验证并继续。
5. 选择“部署” 。现在，您可以在步骤 3 >自动化>流程中指定的文件夹中找到作为流程的工作流。您可以按类型API标识 API 工作流。
6. 选择激活部署，以完成 API 工作流的部署。

最佳实践

• 定义清晰的输入和输出架构，以便其他 UiPath 产品可以理解您的工作流并与之交互。

• API 工作流执行速度快，可在设计期间测试输入和输出有效负载。

• 使用 Autopilot 生成上下文感知表达式和 JavaScript 代码。

• 在“表达式编辑器”输出面板中验证表达式，以在运行之前捕获语法或逻辑问题。

• 通过展开、折叠值或将值复制到剪贴板，与“运行输出”面板中的输入和输出数据进行交互。

• 通过配置 “响应”活动（“成功”或“失败”）提前退出工作流。

• 在“循环”活动中，即“遍历循环”和“Do While循环”活动，使用$input而不是$context来访问上一个对象输出。

• 当连接器未提供所需功能时，使用HTTP活动直接调用 API。在原生HTTP活动或特定于连接器的HTTP 请求活动之间进行选择。

• 您现在可以使用UiPath Orchestrator连接器访问资产和凭据，然后可以在请求标头中安全地使用这些资产和凭据。

• 在HTTP活动的“标头”属性中提供身份验证令牌：

  { 
      Authorization: "<my_token>",
      "Content-Type": "application/json"
  }
  

  对于基本身份验证，请使用：

  { Authorization: "Basic " + btoa("<username>:<pass>")}