Orchestrator API 指南
速率限制和大数据字段使用优化
作为行业最佳实践，对大数据字段限制速率和优化可维持最佳性能水平、高度安全的使用和持续的服务可用性。速率限制对您的好处如下：
- They ensure a predictable system: knowing the API call limit helps in better designing and maintaining your applications. It provides a predictable environment, minimizing surprises due to unexpected limit breaches.
- They improve performance: by controlling the traffic on our servers, we ensure optimal performance and quicker responses, significantly improving your product experience.
- They enhance security: the limits outlined below act as an additional layer of security, protecting your system from potential cyber threats.
- They ensure fair usage: our rate limits assure equitable resource allocation to all users, and smooth operation even during peak use periods.
下面列出的限制和大数据字段优化需要您进行一些调整，但我们相信它们将带来长期收益。
速率限制
以下是我们强制执行的限制：
| Endpoint | Limits | 生效时间 | 示例 |
|---|---|---|---|
|
|
| 社区版、Canary 版和企业版租户：2024 年 7 月 |
|
|
|
| 社区版、Canary 版和企业版租户：2024 年 7 月 |
|
|
| 100 个 API 请求/天/租户 | Community 版、Canary 和 Enterprise 版租户：2024 年 10 月 | 不适用 |
|
| 100 个 API 请求/天/租户 | Community 版、Canary 和 Enterprise 版租户：2024 年 10 月 | 不适用 |
|
| 100 个 API 请求/天/租户 | Community 版、Canary 和 Enterprise 版租户：2024 年 10 月 | 不适用 |
|
| 100 个 API 请求/天/租户 | Community 版、Canary 和 Enterprise 版租户：2024 年 10 月 | 不适用 |
1 Non-automation usage refers to API calls originating from API integrations outside of processes, such as PowerShell scripts and third party monitoring tools.
2 Automation usage refers to API calls originating from Get Queue Items, Get Jobs, and Orchestrator Http Request activities.
GET/odata/Jobs(<job_id>) 不受速率限制。
这些限制不适用于添加队列项目和处理作业。因此，添加队列项目、从队列中删除项目、设置其状态或启动和处理任意数量的作业都不会受到影响。
You can check your API usage per month or day on the tenant-level API audit tab in the Monitoring window.
公开标头
| 页眉 | 描述 | 示例 |
|---|---|---|
Retry-After | All requests beyond the aforementioned limits are returned an HTTP 429 response which includes this header. It displays the number of seconds that you need to wait until the endpoint is available to you again. | Retry-After: 10 表示端点上的速率限制将在 10 秒后过期。在这 10 秒内进行任何重试都会导致 429 响应。 |
X-RateLimit-Remaining | 剩余调用次数 | X-RateLimit-Remaining: 30 表示您在当前时间范围内还剩 30 次调用 |
如果每分钟的请求数低于 10，则呈现为 0。
活动影响
以下活动受这些限制的影响：
- 获取作业
- 获取队列项目
- Orchestrator Http Request (when used to call the
GET /odata/JobsorGET /odata/QueueItemsendpoints)
“系统”活动版本 2024.3 或更高版本应用 Retry-after 响应标头，这意味着它们会执行 Orchestrator 操作的自动重试。请确保始终使用最新版本的“系统”活动，以便从中受益。
适应变化
我们建议您执行以下操作，以确保遵守我们的限制，并充分利用这些限制：
- 查看 API 使用模式以及从我们前面提到的
GetAll类型端点检索的信息。 - 必要时调整 API 调用频率和数据提取程序，以符合这些限制。
- Use the Insights real-time data export option for real-time exports.
- See the Exporting jobs and Exporting queue items sections for examples on how to retrieve jobs and queue items data for reporting and archiving purposes only.
重要提示：
- These endpoints are limited to 100 API requests/day/tenant. Once that limit is exceeded, a #4502 error will be displayed, stating that the daily limit per tenant has been reached. The limit resets at 00:00 UTC.
- 不要将这些端点用于实时数据检索。
- Make sure you always use the latest version of System activities.
- 如果您有任何问题或需要进一步说明，请联系您的客户经理或我们的支持团队。
警示
These alerts, available in the API Rate Limits section of your alerting settings, inform you when the limits are exceeded, and provide valuable information about the impacted endpoint.
- Request rate exceeded the limit in the last day - Warn severity:
- 每天都会在应用程序中和通过电子邮件发送。
- 您会默认订阅它。
- 其中包含超出请求数量的端点的名称。
- It includes a link to the tenant-level API audit monitoring window, focused on the daily view. Details...
- It requires the Audit - View permission.
- Request rate exceeded the limit - Error severity:
- 每十分钟在应用程序中和通过电子邮件发送一次。
- 您已默认取消订阅。
- 其中包含超出请求数量的端点的名称。
- It includes a link to the tenant-level API audit monitoring window, focused on the detailed 10-minute view. Details...
备注：
There might be a 10-minute delay between the moment that the limit is exceeded and the time the alert is sent.
- It requires the Audit - View permission.
警示场景
在以下情况下，您会收到警示：
- 当您通过非自动化使用来使用超过 100 个 API 请求/分钟/租户时。
- 当您通过自动化使用来使用超过 1,000 个 API 请求/分钟/租户时。
大数据字段
用于检索作业和队列项目列表的 API 端点在用于实时监控和数据导出时可能会出现问题。例如：
- 请求最多 1000 个项目且每个项目最多为 1MB 的大数据时，对单个 API 调用的响应大小可以是 1GB。有些中介体不允许这种大小的响应，因此请求将失败。
- 当使用复杂筛选条件，然后对包含数百万个队列项目的队列进行分页时，请求可能会在数十页后开始超时。这是由于需要从数据库检索的数据量较大。
作业字段
为提高系统效率并保护数据隐私，系统会在 Jobs - GetAll 端点响应中省略特定数据。受影响的字段如下：
| Endpoint | 省略的字段 | 可使用的替代方案 | 生效时间 |
|---|---|---|---|
|
|
|
| 社区版和 Canary 租户：2024 年 3 月 企业版租户：2024 年 7 月 |
If you are using the GET /odata/Jobs endpoint, either via API or via the Get Jobs, Get Queue Items, or Orchestrator HTTP Request activities, you need to find out whether you use any of the listed fields. If you do, please be aware that the content of these fields will be returned as null.
我们建议您在 Canary 租户中测试流程，以评估影响。
队列项目大数据字段
通过对字段应用以下大小限制来优化 GET/odata/QueueItems 端点的性能：
| 字段 | 上限 | 生效时间 | 如何判断您是否受到了影响 | 如何解决此问题 |
|---|---|---|---|---|
Progress | 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 个字符 |
These limits are calculated based on the UTF-16 encoding style, which is mainly used by SQL Server to store data. Information is stored in SQL Server via data types like NVARCHAR. In these data types, each character, including widely used characters from languages like Chinese, Japanese, and Korean, is stored using 2 bytes. This may be misleading when you check the data payload using Notepad or in UTF-8, since these display 1 byte per character (primarily ASCII 0-127 abc123 etc). For instance, if you were to store a Chinese character like 文 in a text file with UTF-8 encoding, it would be stored as a 3-byte sequence (E6 96 87), thus consuming more storage space. The difference between encoding styles makes the number of characters unreliable as a limit.
出于性能原因，以下筛选器也受到限制：
| 筛选 | 上限 | 生效时间 | 如何判断您是否受到了影响 | 如何解决此问题 |
|---|---|---|---|---|
$top | > If you do not use the $top filter, you receive 100 records by default. > If you use the $top filter, you receive a maximum of 100 records. Anything exceeding 100 triggers a 400 Bad Request error message. | > Community and Canary tenant: June 2024 > Enterprise tenants: September 2024 | Enterprise 版：如果我们检测到有人在 API 调用中使用此筛选器，我们将向管理员发送电子邮件通知。但是，我们也要请您也密切关注相关情况。 | 如果您预计会超过此限制，我们建议您相应地修改流程或 API 使用逻辑。 |
替代方案
您可以使用以下替代方法来检索 Jobs 和 QueueItems 字段：
- See the Exporting jobs and Exporting queue items sections for examples on how to retrieve jobs and queue items data.
- Use the Insights real-time data export option.
- 如果前面的方法不适合您，请联系您的客户经理或我们的支持团队。
从本地部署迁移到云
在本地部署环境中将不会实施速率限制和大型数据字段更改。
If you are using standalone Orchestrator and are thinking of moving to cloud, you can use the IIS request logs to determine the request rate for the impacted endpoints. The analysis depends on how you aggregate the logs, for which you can use, for instance, Microsoft Log Parser.
为了评估对大数据字段的影响，我们建议在 Canary 租户中测试您的流程。