构建 API 请求

所有 Orchestrator API 调用均使用 HTTP 方法对 Orchestrator URL 进行。Orchestrator URL 的语法如下：{AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_。建议使用 HTTPS 协议加密通过 API 调用发送的数据。

重要提示：

要访问文件夹中的资源，每个请求的 HTTP 标头中必须包含FolderId 、 FolderPath或FolderKey 。此标头可以进行编码（使用 Base64 UTF-16LE 编码）或纯文本。例如：

• X-UIPATH-OrganizationUnitId "FolderId",
• X-UIPATH-FolderPath-Encoded "{Encoded FolderPath value}",
• X-UIPATH-FolderPath "PlainText FolderPath value"或
• X-UIPATH-FolderKey "FolderKey". The FolderId can be obtained by performing a GET request to the /odata/Folders endpoint and copying the "Id" value, or from the Orchestrator URL - https://your-domain-server.com/? fid=2032 &tid=8. FolderId is of type Int 64. The FolderKey can be obtained by performing a GET request to the /odata/Folders endpoint and copying the "Key" value. FolderKey is of type Unique Id/String. If you change the licensing plan for your Orchestrator account (for example, from Enterprise Trial to Enterprise), the FolderId value also changes, whereas the FolderKey value remains the same. Relative folder paths are supported in an X-UIPATH-FolderPath-Encoded header, as follows:
• 以 / 开头的路径 - 从环境文件夹所在的树的 root 文件夹开始。
• 以 . 开头的路径 - 从环境文件夹开始。
• 以..开头的路径 - 路径中的每个..在环境文件夹的层次结构中向上启动一个级别（例如../表示上一级， ../../表示上两级）。请注意，不应包含尾随斜杠。

重要提示：

将 Orchestrator API 与 MSXML 结合使用时，204 No Content 响应可能会导致 1223 状态代码并导致错误。

备注：

The @odata.count parameter is not output by default in API results originating from workflow activities and API integrations outside of processes. To include it, you must manually add $count=true to the desired endpoint.

GET 请求

GET 请求通常是最简单的请求。 它们可帮助您检索数据并使用通用 OData 子句：

• $顶部
• $filter
• $展开
• $选择
• $orderby
• $skip

$顶部

此子句可帮助您限制检索的数据量。 它的上限取决于您要调用的端点以及 Orchestrator 实例上存在的此类资源的数量。

例如，此请求 {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$top=10 返回 Orchestrator Community Edition 中可用的前 10 个环境。 但是，如果仅存在 5 个环境，则仅检索这些环境。

$filter

此 OData 子句用于根据特定资源的属性筛选特定资源。

例如，可以根据以下条件进行筛选：

• 数字属性:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$filter=Id%20eq%2015
    • requests a specific environment based on its Id
• 文本属性:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Environments?$filter=contains(Name,'N')&$top=10
    • returns the first 10 environments whose name contains the letter "N"
• 布尔值属性:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true
    • returns all processes that contain the word "test" and represent the latest version
• 可枚举属性:
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/QueueItems?$filter=Priority%20eq%20'High'
    • returns all queue items that have a High priority
• 属性的属性：
  • {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation'
    • returns the first 10 jobs that were executed by any Robot that exists on the "Documentation" machine

筛选参数可以使用逻辑运算符 "and"、"or" 和/或 "not" 进行组合，并可使用括号 "()" 进行分组，例如以下请求：

• {AutomationCloudURL}/{organizationName}/{tenantName}/orchestrator_/odata/odata/Jobs?$top=10&$filter=Robot/MachineName eq 'LAVINIA-PC' and (not(Source eq 'Manual') or StartTime gt 2017-10-28T12:13:00.07Z) - 显示部署在“LAVINIA-PC”计算机上的机器人手动执行或在“2017-10-28T12:13:00.07Z”之后执行的前 10 个作业。

已知问题

包含将嵌套复杂对象与 null 进行比较的表达式的 OData $filter 查询不起作用。例如，使用 Release ne null 表达式将返回错误，因为 Release 是一个复杂对象，包含其自己的嵌套属性。

在这种情况下，我们建议将复杂对象替换为简单对象。

示例:

• 您可以将 Release ne null 替换为 ReleaseName ne null，因为 ReleaseName 是现有的简单对象。
  备注：

  您不能将Machine ne null替换为MachineName ne null ，因为MachineName不存在。

• 您可以对复杂对象使用嵌套属性进行比较。例如，Release/Name ne null 可以替换 Release ne null，而 Machine/Name ne null 可以替换 Machine ne null。

$展开

此子句用于完全加载所请求资源的导航属性。

$选择

使用此 OData 子句，您可以指定要返回的资源属性的子集。 如果要提取多个资源，可以使用逗号将其分隔。

$orderby

$orderby 子句用于对检索到的资源进行排序。 与 $select 子句一样，要排序的资源用逗号分隔，并且可以按升序 (asc) 或降序 (desc) 进行排序。 如果未指定这两个运算符，则系统将自动按升序对资源进行排序。

$skip

此子句使您可以跳过指定筛选器中的前 n 个项目。

POST 请求

POST HTTP 动词可帮助您创建从属于其他资源的新项目。 创建新资源时，将 POST 发送到父资源，并且 Orchestrator 负责将新资源与父资源相关联、分配 ID 以及其他必需信息。 数据通过请求正文添加，响应是整个创建的对象。

您可以向队列添加新项目，创建新资产、环境或流程，为一个或多个失败的事务分配审核人，等等。

备注：

无法在 POST 请求正文中对特殊字符进行转义。要使用特殊字符，您需要首先使用以下格式 "[e-mail]": "#String" 将其所属参数声明为字符串。为了便于理解，请参阅以下示例中 Specific Content 参数的填充方式。

PUT 请求

当您要更新资源的内容时，通常需要 PUT。 通常，通过在 URL 中添加特定实体的 Id 来向特定实体发出请求。 请注意，PUT 调用会将现有实体替换为请求的内容，或者，如果指定位置不存在任何实体，则尝试创建该实体。

可以更新队列、环境、组织单位、事务注释、流程和其他资源的详细信息。

PATCH 请求

PATCH 用于更新现有实体的内容，通过在 URL 中添加 Id 来指定所需实体。请求正文仅包含您要更改的内容。这与 PUT 调用不同，PUT 调用会将当前实体替换为后续请求的内容。

可以使用 PATCH 请求来更新计算机、流程、机器人、租户、用户（组织单位和角色除外）和 Webhook 实体。

DELETE 请求

使用此 HTTP 动词，您可以将数据库中的指定项目标记为已删除。 资源通常在调用的 URL 中通过其 ID 来指示。 204 响应应告知您请求已成功。

可以删除资产、环境、队列项目注释、流程、角色、租户、用户等。