- 基本情報
- OData と参照について
- 列挙型
- 認証
- API リクエストを構築する
- エンドポイントごとの権限
- 応答コード
- レート制限と大きなデータ フィールドの使用の最適化
- Swagger の定義
- Orchestrator API
Orchestrator API ガイド
レート制限と大きなデータ フィールドの使用の最適化
- 予測可能なシステムを確保: API 呼び出しの制限を知ることで、アプリケーションの設計と保守を改善できます。 予測可能な環境を提供し、予期しない制限違反による想定外の事態を最小限に抑えます。
- パフォーマンスの向上: サーバー上のトラフィックを制御することにより、最適なパフォーマンスと迅速な応答を保証し、製品エクスペリエンスを大幅に向上させます。
- セキュリティの強化: 以下に概説する制限は、セキュリティの追加レイヤーとして機能し、潜在的なサイバー脅威からシステムを保護します。
- 公正な使用を保証: レート制限により、すべてのユーザーに公平なリソース割り当てが保証され、使用のピーク時でもスムーズな運用が保証されます。
以下に概説する制限および大きなデータ フィールドの最適化は、お客様側でいくつかの調整をしていただく必要がありますが、長期的にはメリットをもたらすことになるものです。
適用される制限は次のとおりです。
|
エンドポイント |
上限量 |
発効日 | 例 |
|---|---|---|---|
|
|
|
Community、カナリア、および Enterprise のテナント: 2024 年 7 月 |
|
|
|
|
Community、カナリア、および Enterprise のテナント: 2024 年 7 月 |
|
|
|
100 API 要求/日/テナント |
Community、カナリア、および Enterprise のテナント: 2024 年 10 月 |
N/A |
|
| 100 API 要求/日/テナント |
Community、カナリア、および Enterprise のテナント: 2024 年 10 月 |
N/A |
|
|
100 API 要求/日/テナント |
Community、カナリア、および Enterprise のテナント: 2024 年 10 月 |
N/A |
|
|
100 API 要求/日/テナント |
Community、カナリア、および Enterprise のテナント: 2024 年 10 月 |
N/A |
1 オートメーション以外の使用とは、PowerShell スクリプトやサードパーティの監視ツールなど、プロセス外部の API 連携から発生する API 呼び出しを指します。
2 オートメーションの使用とは、[キュー アイテムを取得]、[ジョブを取得]、および [Orchestrator への HTTP 要求] のアクティビティから発生する API 呼び出しを指します。
GET/odata/Jobs(<job_id>) にレート制限はありません。
これらの制限は、キュー アイテムの追加やジョブの処理には適用されません。したがって、キュー アイテムの追加、キューからのアイテムの削除、ステータスの設定、任意の数のジョブの開始/処理には影響しません。
月または日ごとの API 使用状況は、テナント レベルの [監視] ウィンドウのテナント レベルの [API 監査] タブで確認できます。
|
ヘッダー |
説明 |
例 |
|---|---|---|
|
|
前述の制限を超えるすべての要求は、このヘッダーを含む HTTP 429 応答を返します。 エンドポイントが再び利用可能になるまで待機する必要のある秒数が表示されます。 |
Retry-After: 10 は、エンドポイントのレート制限が 10 秒で期限切れになることを意味します。10 秒以内に行われるリトライの結果はすべて、429 の応答になります。
|
|
|
残りの呼び出し数 |
X-RateLimit-Remaining: 30 は、現在の時間範囲に 30 件の呼び出しが残っていることを意味します。
|
1 分あたりの要求数が 10 未満の場合は、0 としてレンダリングされます。
この制限により、以下のアクティビティが影響を受けます。
- ジョブを取得
- キュー アイテムを取得
- Orchestrator への HTTP 要求 (
GET /odata/JobsまたはGET /odata/QueueItemsエンドポイントの呼び出しに使用される場合)
Retry-after 応答ヘッダーが適用されます。つまり、Orchestrator の操作が自動的にリトライされます。この方法を活用するには、常に最新バージョンのシステム アクティビティを使用してください。
以下は、制限を遵守すると同時に、制限を最大限に活用していただくための推奨事項です。
- API の使用パターンと、前述の
GetAllタイプのエンドポイントから取得した情報を確認します。 - 必要に応じて、API 呼び出しの頻度とデータ抽出手順を調整して、これらの制限に合わせてください。
- リアルタイムでエクスポートするには、Insights のリアルタイムのデータ エクスポート オプションを使用します。
- レポートおよびアーカイブのみを目的としてジョブおよびキュー アイテムのデータを取得する方法の例については、「ジョブをエクスポートする」および「キュー アイテムをエクスポートする」をご覧ください。
重要:
- エンドポイントは、各テナントで 1 日あたり 100 件の API 要求に制限されます。
この制限を超えると、テナントごとの 1 日あたりの制限に達したことを示す #4502 エラーが表示されます。 制限は 00:00 UTC にリセットされます。
- これらのエンドポイントは、リアルタイムのデータ取得には使用しないでください。
- エンドポイントは、各テナントで 1 日あたり 100 件の API 要求に制限されます。
- 常に最新バージョンのシステム アクティビティを使用してください。
- 質問がある場合、またはさらに説明が必要な場合は、アカウント マネージャーまたはサポートチームにお問い合わせください。
これらのアラートは、アラート設定の [API のレート制限] セクションで利用可能であり、制限を超過した場合にユーザーに通知し、影響を受けたエンドポイントについて貴重な情報を提供します。
- 過去 1 日の要求レートが制限を超過しました - 重要度 Warn:
- アプリケーション内とメールで毎日送信されます。
- 既定で配信されます。
- 要求の数を超過したエンドポイントの名前が含まれます。
- 日次のビューにフォーカスした、テナント レベルの [API 監査] 監視ウィンドウへのリンクが含まれています。詳細
- このためには、[監査] - [表示] 権限が必要です。
- 要求レートが制限を超過しました - 重要度 Error:
- アプリケーション内とメールで 10 分間隔で送信されます。
- 既定では購読が解除されています。
- 要求の数を超過したエンドポイントの名前が含まれます。
- 10 分間のビューにフォーカスした、テナント レベルの [API 監査] 監視ウィンドウへのリンクが含まれています。詳細注: 制限を超過してからアラートが送信されるまでに 10 分の遅延が生じる場合があります。
- このためには、[監査] - [表示] 権限が必要です。
アラートのシナリオ
アラートは次のシナリオで発生します。
- オートメーション以外の使用により 100 API 要求/分/テナントを超えた場合。
- オートメーションの使用により 1,000 API 要求/分/テナントを超えた場合。
ジョブやキュー アイテムのリストの取得に使用される API エンドポイントを、リアルタイムの監視やデータのエクスポートに使用すると、問題が発生する可能性があります。以下に例を示します。
-
最大 1,000 個のアイテムを要求し、各アイテムが最大 1 MB の大きなデータに相当する場合、1 回の API 呼び出しに対する応答のサイズが 1 GB 程度になる可能性があります。このサイズの応答を許可しない中継点があるため、要求は失敗します。
-
複雑なフィルターを使用し、数百万個のキュー アイテムを含むキューにページネーションを行うと、数十ページを処理した後に要求がタイムアウトし始める場合があります。これは、データベースから取得する必要があるデータの量が原因です。
Jobs - GetAll エンドポイントの応答から特定のデータが省略されています。影響を受けるフィールドは次のとおりです。
|
エンドポイント |
省略されたフィールド |
代わりに使用できるもの |
発効日 |
|---|---|---|---|
|
|
|
|
Community およびカナリア テナント: 2024 年 3 月 Enterprise テナント: 2024 年 7 月 |
GET /odata/Jobs エンドポイントを使用している場合は、上記のフィールドのいずれかを使用しているかどうかを確認する必要があります。その場合、該当するフィールドの中身は null として返されますのでご注意ください。
カナリア テナントでプロセスをテストして、影響を評価することをお勧めします。
GET/odata/QueueItems エンドポイントのパフォーマンスは、次のサイズ制限をフィールドに適用することで最適化されます。
|
フィールド |
上限量 | 発効日 |
影響の通知方法 |
対処方法 |
|---|---|---|---|---|
進行状況 |
1,048,576 文字 |
> Community およびカナリア テナント: 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 文字 |
これらの制限は、SQL Server がデータを格納するために主に使用する UTF-16 エンコード スタイルに基づいて計算されます。
情報は、NVARCHAR などのデータ型で SQL Server に格納されます。これらのデータ型では、中国語、日本語、韓国語などの言語で広く使用されている文字を含む各文字が 2 バイトを使用して格納されます。メモ帳や UTF-8 でデータ ペイロードを確認すると、主に ASCII 0-127 や abc123 などの文字は 1 文字あたり 1 バイトで表示されるため、誤解を招く可能性があります。
たとえば、「文」などの漢字を UTF-8 エンコードのテキスト ファイルに格納する場合、3 バイトのシーケンス (E6 96 87) として格納されるため、より多くのストレージ領域が消費されます。エンコード スタイルが異なるため、文字数は制限値として信頼できません。
次のフィルターもパフォーマンス目的のために制限されています。
|
フィルター |
上限量 |
発効日 |
影響の通知方法 |
対処方法 |
|---|---|---|---|---|
|
|
>
$top フィルターを使用しない場合、既定で 100 件のレコードを受け取ります。
>
$top フィルターを使用する場合、最大 100 件のレコードを受け取ります。100 トリガーを超えると、400 Bad Request エラー メッセージが表示されます。
|
> Community および Canary テナント: 2024 年 6 月 > Enterprise テナント: 2024 年 9 月 |
Enterprise: API 呼び出しでこのフィルターの使用を検出した場合、管理者にメール通知を送信することを目指しています。ただし、ユーザー側でも目を離さないようにしてください。 |
この制限を超えることが予想される場合は、プロセスまたは API の使用ロジックを適宜変更することをお勧めします。 |
Jobs フィールドおよび QueueItems フィールドを取得するには、次の代替方法があります。
- ジョブおよびキュー アイテムのデータを取得する例については、「ジョブをエクスポートする」および「キュー アイテムをエクスポートする」をご覧ください。
- Insights のリアルタイムのデータ エクスポート オプションを使用します。
- 前述の方法がうまくいかない場合は、アカウントマネージャーまたはサポート チームにご連絡ください。
レート制限と大きなデータ フィールドの変更は、オンプレミス環境では実装されません。
スタンドアロンの Orchestrator を使用しておりクラウドへの移行を検討している場合は、IIS 要求ログを使用して、影響を受けるエンドポイントに対する要求レートを確認できます。分析はログの集計方法によって異なります。たとえば Microsoft Log Parser などを使用できます。
大きなデータ フィールドへの影響を評価するには、カナリア テナントでプロセスをテストすることをお勧めします。
