Orchestrator API 指南
速率限制和大数据字段使用优化
作为行业最佳实践，对大数据字段限制速率和优化可维持最佳性能水平、高度安全的使用和持续的服务可用性。速率限制对您的好处如下：
- 这些限制可确保系统的可预测性：了解 API 调用限制有助于更好地设计和维护应用程序。提供了一个可预测的环境，充分减少了由于意外超出限制而导致的意外情况。
- 提升了性能：通过控制服务器上的流量，我们可确保实现最佳性能和更快的响应，从而显着改善您的产品体验。
- 增强安全性：下面列出的限制可充当额外的安全层，保护您的系统免受潜在的网络威胁。
- 确保合理使用：我们的速率限制可确保将资源公平地分配给所有用户，即使在使用高峰期，也能确保平稳运行。
下面列出的限制和大数据字段优化需要您进行一些调整，但我们相信它们将带来长期收益。
速率限制
以下是我们强制执行的限制：
| 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自动化使用情况是指源自“获取队列项目”、“获取作业”和“Orchestrator Http 请求”活动的 API 调用。
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 | 系统将向所有超出上述限制的请求返回包含此标头的 HTTP 429 响应。 它会显示端点再次可用之前需要等待的秒数。 | 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 调用频率和数据提取程序，以符合这些限制。
- 使用“Insights 实时数据导出”选项进行实时导出。
- 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.
重要提示：
- 这些端点限制为每个租户每天 100 个 API 请求。 一旦超过该限制，系统将显示 #4502 错误，指出已达到每个租户的每日限制。此限制将在 00:00 UTC 重置。
- 不要将这些端点用于实时数据检索。
- 确保始终使用最新版本的“系统”活动。
- 如果您有任何问题或需要进一步说明，请联系您的客户经理或我们的支持团队。
警示
这些警示可在警示设置的“API 速率限制”部分中找到，它们会在超出限制时通知您，并提供有关受影响端点的重要信息。
- 过去一天的请求率超出限制 - “警告”严重性：
- 每天都会在应用程序中和通过电子邮件发送。
- 您会默认订阅它。
- 其中包含超出请求数量的端点的名称。
- It includes a link to the tenant-level API audit monitoring window, focused on the daily view. Details...
- 这需要“审核” - “查看”权限。
- 请求率超出限制 - “错误”严重性：
- 每十分钟在应用程序中和通过电子邮件发送一次。
- 您已默认取消订阅。
- 其中包含超出请求数量的端点的名称。
- It includes a link to the tenant-level API audit monitoring window, focused on the detailed 10-minute view. Details...
备注：
超出限制与发送警示的时间之间可能会有 10 分钟的延迟。
- 这需要“审核” - “查看”权限。
警示场景
在以下情况下，您会收到警示：
- 当您通过非自动化使用来使用超过 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 版和 Canary 租户：2024 年 6 月 > Enterprise 版租户：2024 年 9 月 | Enterprise 版：如果我们检测到有人在 API 调用中使用此筛选器，我们将向管理员发送电子邮件通知。但是，我们也要请您也密切关注相关情况。 | 如果您预计会超过此限制，我们建议您相应地修改流程或 API 使用逻辑。 |
替代方案
您可以使用以下替代方法来检索 Jobs 和 QueueItems 字段：
- 有关如何检索作业和队列项目数据的示例，请参见导出作业和导出队列项目一节。
- 使用“Insights 实时数据导出”选项。
- 如果前面的方法不适合您，请联系您的客户经理或我们的支持团队。
从本地部署迁移到云
在本地部署环境中将不会实施速率限制和大型数据字段更改。
如果您使用的是独立版 Orchestrator，并考虑迁移到云，则可以使用 IIS 请求日志来确定受影响端点的请求率。分析取决于您聚合日志的方式，您可以为此使用 Microsoft Log Parser。
为了评估对大数据字段的影响，我们建议在 Canary 租户中测试您的流程。