管理 API 工作流

在 Studio Web 中创建和管理 API 工作流解决方案，包括如何在 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 表达式生成器	Located at the bottom of the input panel, the Autopilot expression generator helps you create workflow expressions using natural language, instead of writing JavaScript. Autopilot understands the context of your workflow, and enables you to reference objects and workflow steps by describing your desired outcome.
活动测试输入	To the right-hand side of the code panel, the Activity test input panel lets you review test data generated from previous workflow runs. It provides sample data you can use to build and validate expressions, and it interacts directly with the Expression output panel to ensure your expressions produce the desired results.
表达式输出	The Expression output panel displays the result of your expression based on the data from the Activity test input data. This lets you validate that your expression generates the expected outcome. If your expression has errors, the Expression output section highlights the problematic expression and provides a corresponding error message. The result updates automatically whenever you modify the expression in the input panel.

使用 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 文档相符。
  • 查看错误消息— 检查错误消息，寻找有关身份验证错误、不正确的有效负载或脚本错误的线索。

添加调试配置

You can build and test your API workflow iteratively, validating each step as you add new activities. To run these tests effectively, you can define specific input data using the Debug configuration feature. This lets you set a JSON input once and reuse it across all subsequent test runs. You can access the emulated data through the $workflow.input object during workflow execution.

要添加“调试”配置：

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>")}