构建 API 请求

所有 Orchestrator API 调用均使用 HTTP 方法对 Orchestrator URL 进行。Orchestrator URL 的语法如下： https://{yourDomain} 。建议使用 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"。

可以通过对 /odata/Folders 端点执行 GET 请求并复制“Id”值来获取 FolderId，也可以从 Orchestrator URL - https://your-domain-server.com/? fid=2032 &tid=8 中获取。FolderId 的类型为 Int 64。

可以通过对 /odata/Folders 端点执行 GET 请求并复制“密钥”值来获取 FolderKey 。 FolderKey 的类型为唯一 ID/字符串。

如果您更改 Orchestrator 帐户的许可计划（例如，从 Enterprise Trial 更改为 Enterprise），则 FolderId 值也会更改，而 FolderKey 值将保持不变。

X-UIPATH-FolderPath-Encoded 参数支持相对文件夹路径，如下所示：

• 以 / 开头的路径 - 从环境文件夹所在的树的 root 文件夹开始。
• 以 . 开头的路径 - 从环境文件夹开始。
• 以 .. 开头的路径 - 路径中的每个 .. 表示在环境文件夹的层次结构中向上一层（例如 ../ 表示向上一层，../../ 表示向上两层）。

请注意，不应包含尾随斜杠。

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

GET 请求

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

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

$顶部

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

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

$filter

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

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

• 数字属性:
  • https://{yourDomain}/odata/Environments?$filter=Id%20eq%2015 - 根据 ID 请求特定环境
• 文本属性:
  • https://{yourDomain}/odata/Environments?$filter=contains(Name,'N')&$top=10 - 返回名称中包含字母“N”的前 10 个环境
• 布尔值属性:
  • https://{yourDomain}/odata/Processes?$filter=Title%20eq%20'test'%20%26%20IsLatestVersion%20eq%20true - 返回包含单词“test”并表示最新版本的所有流程
• 可枚举属性:
  • https://{yourDomain}/odata/QueueItems?$filter=Priority%20eq%20'High' - 返回具有高优先级的所有队列项目
• 属性的属性：
  • https://{yourDomain}/odata/Jobs?$top=10$filter=Robot/MachineName%20eq%20'Documentation' - 返回“文档”计算机上存在的任何机器人执行的前 10 个作业

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

• https://{yourDomain}/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 调用不同，后者将当前实体 替换 为后续请求的内容。

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

删除请求

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

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