Orchestrator API 指南

适用平台：

Automation Cloud Automation Cloud Public Sector Automation Suite Standalone

上次更新日期 2024年11月20日

速率限制和大数据字段使用优化

作为行业最佳实践，对大数据字段限制速率和优化可维持最佳性能水平、高度安全的使用和持续的服务可用性。速率限制对您的好处如下：

这些限制可确保系统的可预测性：了解 API 调用限制有助于更好地设计和维护应用程序。提供了一个可预测的环境，充分减少了由于意外超出限制而导致的意外情况。
提升了性能：通过控制服务器上的流量，我们可确保实现最佳性能和更快的响应，从而显着改善您的产品体验。
增强安全性：下面列出的限制可充当额外的安全层，保护您的系统免受潜在的网络威胁。
确保合理使用：我们的速率限制可确保将资源公平地分配给所有用户，即使在使用高峰期，也能确保平稳运行。

下面列出的限制和大数据字段优化需要您进行一些调整，但我们相信它们将带来长期收益。

速率限制

以下是我们强制执行的限制：

Endpoint	Limits	生效时间	示例
`GET/odata/Jobs/?<filters>`	每个租户每分钟可发出 100 个 API 请求，适用于费自动化使用情况¹ 每个租户每分钟可发出 1,000 个 API 请求，适用于自动化使用情况²	社区版、Canary 版和企业版租户：2024 年 7 月	`GET/odata/Jobs` `GET/odata/Jobs?$top=100` `GET/odata/Jobs?$top=20&$filter=Robot/Id eq 123L` `GET/odata/Jobs?$filter=((CreationTime ge 2024-04-04T12:00:47.264Z) and (ProcessType eq 'Process'))&$expand=Robot,Machine,Release&$orderby=CreationTime desc`
`GET/odata/QueueItems/?<filters>`	每个租户每分钟可发出 100 个 API 请求，适用于费自动化使用情况¹ 每个租户每分钟可发出 1,000 个 API 请求，适用于自动化使用情况²	社区版、Canary 版和企业版租户：2024 年 7 月	`GET/odata/QueueItems` `GET/odata/QueueItems/?$top=20` `GET/odata/QueueItems?$filter=((Status eq '0'))` `GET/odata/QueueItems?$filter=((QueueDefinitionId eq 102135))&$expand=Robot,ReviewerUser&$orderby=Id desc`
`POST/odata/AuditLogs/UiPath.Server.Configuration.OData.Export`	100 个 API 请求/天/租户	Community 版、Canary 和 Enterprise 版租户：2024 年 10 月	不适用
`POST/odata/QueueDefinitions({key})/UiPathODataSvc.Export`	100 个 API 请求/天/租户	Community 版、Canary 和 Enterprise 版租户：2024 年 10 月	不适用
`POST/odata/RobotLogs/UiPath.Server.Configuration.OData.Export`	100 个 API 请求/天/租户	Community 版、Canary 和 Enterprise 版租户：2024 年 10 月	不适用
`POST/odata/Jobs/UiPath.Server.Configuration.OData.Export`	100 个 API 请求/天/租户	Community 版、Canary 和 Enterprise 版租户：2024 年 10 月	不适用

¹非自动化使用情况是指源自流程外部 API 集成的 API 调用，例如 PowerShell 脚本和第三方监控工具。

²自动化使用情况是指源自“获取队列项目”、“获取作业”和“Orchestrator Http 请求”活动的 API 调用。

重要提示： GET/odata/Jobs(<job_id>) 不受速率限制。

这些限制不适用于添加队列项目和处理作业。因此，添加队列项目、从队列中删除项目、设置其状态或启动和处理任意数量的作业都不会受到影响。

您可以在“监控”窗口的租户级别“API 审核”选项卡中查看每月或每天的 API 使用情况。

公开标头

页眉	描述	示例
`Retry-After`	系统将向所有超出上述限制的请求返回包含此标头的 HTTP 429 响应。它会显示端点再次可用之前需要等待的秒数。	`Retry-After: 10` 表示端点的速率限制将在 10 秒后过期。在这 10 秒内进行任何重试都会导致 429 响应。
`X-RateLimit-Remaining`	剩余调用次数	`X-RateLimit-Remaining: 30` 表示在当前时间范围内还剩 30 次调用

备注：

如果每分钟的请求数低于 10，则呈现为 0。

活动影响

以下活动受这些限制的影响：

获取作业
获取队列项目
Orchestrator Http 请求（当用于调用 GET /odata/Jobs 或 GET /odata/QueueItems 端点时）

“系统”活动版本 2024.3 或更高版本应用 Retry-after 响应标头，这意味着它们会执行 Orchestrator 操作的自动重试。请确保始终使用最新版本的“系统”活动，以便从中受益。

适应变化

我们建议您执行以下操作，以确保遵守我们的限制，并充分利用这些限制：

查看 API 使用模式以及从我们前面提到的 GetAll 类型端点检索的信息。
必要时调整 API 调用频率和数据提取程序，以符合这些限制。
使用“Insights 实时数据导出”选项进行实时导出。
有关如何仅出于报告和存档目的检索作业和队列项目数据的示例，请参见“导出作业”和“导出队列项目”一节。
重要提示：
- 这些端点限制为每个租户每天 100 个 API 请求。
  一旦超过该限制，系统将显示 #4502 错误，指出已达到每个租户的每日限制。此限制将在 00:00 UTC 重置。
- 不要将这些端点用于实时数据检索。
确保始终使用最新版本的“系统”活动。
如果您有任何问题或需要进一步说明，请联系您的客户经理或我们的支持团队。

警示

这些警示可在警示设置的“API 速率限制”部分中找到，它们会在超出限制时通知您，并提供有关受影响端点的重要信息。

过去一天的请求率超出限制 - “警告”严重性：
- 每天都会在应用程序中和通过电子邮件发送。
- 您会默认订阅它。
- 其中包含超出请求数量的端点的名称。
- 其中包含指向租户级别“API 审核”监控窗口的链接，重点显示每日视图。详细信息…
- 这需要“审核” - “查看”权限。
请求率超出限制 - “错误”严重性：
- 每十分钟在应用程序中和通过电子邮件发送一次。
- 您已默认取消订阅。
- 其中包含超出请求数量的端点的名称。
- 其中包含指向租户级别“API 审核”监控窗口的链接，重点关注 10 分钟的详细视图。详细信息…
  注意：超出限制与发送警示之间可能会有 10 分钟的延迟。
- 这需要“审核” - “查看”权限。

警示场景

在以下情况下，您会收到警示：

当您通过非自动化使用来使用超过 100 个 API 请求/分钟/租户时。
当您通过自动化使用来使用超过 1,000 个 API 请求/分钟/租户时。

大数据字段

用于检索作业和队列项目列表的 API 端点在用于实时监控和数据导出时可能会出现问题。例如：

请求最多 1000 个项目且每个项目最多为 1MB 的大数据时，对单个 API 调用的响应大小可以是 1GB。有些中介体不允许这种大小的响应，因此请求将失败。
当使用复杂筛选条件，然后对包含数百万个队列项目的队列进行分页时，请求可能会在数十页后开始超时。这是由于需要从数据库检索的数据量较大。

作业字段

为提高系统效率并保护数据隐私，系统会在 Jobs - GetAll 端点响应中省略特定数据。受影响的字段如下：

Endpoint	省略的字段	可使用的替代方案	生效时间
`GET/odata/Jobs`	`InputArguments` `OutputArguments`	`GET/odata/Jobs({key})`	社区版和 Canary 租户：2024 年 3 月企业版租户：2024 年 7 月

如果您通过 API 或者通过“获取作业”、“获取队列项目”或“Orchestrator HTTP 请求”活动使用 GET /odata/Jobs 端点，则需要确定是否使用了所列的任何字段。请注意，如果这样做，这些字段的内容将返回为 Null。

我们建议您在 Canary 租户中测试流程，以评估影响。

队列项目大数据字段

通过对字段应用以下大小限制来优化 GET/odata/QueueItems 端点的性能：

字段	上限	生效时间	如何判断您是否受到了影响	如何解决此问题
`进度`	1,048,576 个字符	> Community 版和 Canary 租户：2024 年 4 月 > Enterprise 版租户：2024 年 5 月	如果您尝试上传的数据超过这些限制，系统将返回特定的错误消息。	如果您需要存储更多数据，我们建议您使用存储桶和/或 Data Service Blob 存储。
`进度`	104,857 个字符	所有租户：2024 年 9 月
`AnalyticsData/Analytics`	5,120 个字符	> Community 版和 Canary 租户：2024 年 6 月 > Enterprise 版租户：2024 年 9 月
`OutputData/Output`	51,200 个字符
`SpecificContent/SpecificData`	256,000 个字符
`ProcessingException` - `Reason`	102,400 个字符
`ProcessingException` - `Details`	102,400 个字符

重要提示：

这些限制是根据 UTF-16 编码样式计算得出的，SQL Server 主要使用该样式来存储数据。

信息通过 NVARCHAR 等数据类型存储在 SQL Server 中。在这些数据类型中，每个字符（包括中文、日语和韩语等语言中广泛使用的字符）使用 2 个字节存储。当您使用记事本或 UTF-8 编码文件检查数据有效负载时，这可能会产生误导，因为这些文件每个字符显示 1 个字节（主要是 ASCII 0-127 abc123 等）。

例如，如果要在使用 UTF-8 编码的文本文件中存储一个中文字符（如“文”），则该字符将存储为一个 3 字节的序列 (E6 96 87)，从而会消耗更多存储空间。编码样式之间的差异使得字符数限制不可靠。

出于性能原因，以下筛选器也受到限制：

筛选	上限	生效时间	如何判断您是否受到了影响	如何解决此问题
`$top`	> 如果您不使用 `$top` 筛选条件，默认情况下您会收到 100 条记录。 > 如果使用 `$top` 筛选条件，您最多会收到 100 条记录。任何超过 100 的值都会触发 `400 Bad Request` 错误消息。	> Community 版和 Canary 租户：2024 年 6 月 > Enterprise 版租户：2024 年 9 月	Enterprise 版：如果我们检测到有人在 API 调用中使用此筛选器，我们将向管理员发送电子邮件通知。但是，我们也要请您也密切关注相关情况。	如果您预计会超过此限制，我们建议您相应地修改流程或 API 使用逻辑。