サービス保護の API 制限

すべてのユーザーに一貫した可用性とパフォーマンスを確実に提供するために、API の使用方法にいくつかの制限を適用します。 これらの制限は、クライアント アプリケーションがサーバー リソースに対して異常な要求を行っていることを検出するように設計されています。

これらの制限が対話型クライアントの標準ユーザーに影響しないようにします。 異常な API 要求を実行するクライアント アプリケーションのみが影響を受けます。 この制限は、Microsoft Dataverse プラットフォームの可用性とパフォーマンス特性に対する脅威となる、ランダムに発生する予期しない要求数の急増に備えて一定レベルの保護を提供します。

クライアント アプリケーションが非常に厳しい要求を行う場合、Dataverse はオンラインサービスの一般的なパターンに従います。 要求が多すぎることを示すエラーを返します。

• Web API を使用して、429 要求が多すぎますエラーを返します。
• .NET 用 Dataverse SDK を使用すると、3 つの特定のエラー コードの 1 つを含む、OrganizationServiceFault エラーが表示されます。 詳細: 返されたサービス保護 API の制限エラーについて

クライアント アプリケーションへの影響

サービス保護 API の制限エラーを管理するのはクライアント アプリケーションの責任です。 このエラーを正確に管理する方法は、アプリケーションの性質によって異なります。

対話型クライアント アプリケーション

サービス保護制限は十分に高いため、通常の使用中に、対話型クライアント アプリケーションを使用している個人に発生することはめったにありません。 ただし、クライアント アプリケーションで一括操作が許可されている場合は可能です。 クライアント アプリケーションの開発者は、サービス保護 API の制限がどのように適用されるかを認識し、ユーザーが非常に負荷の高い要求をサーバーに送信する可能性を減らすように UI を設計する必要があります。 ただし、サービス保護 API の制限エラーが発生する可能性があり、処理できるように準備しておく必要があります。

クライアント アプリケーションの開発者は、ユーザーにメッセージを表示するために単にエラーをスローするべきではありません。 エラー メッセージはエンド ユーザーを対象としたものではありません。 特定の方法については、「操作の再試行」を参照してください。

データ統合アプリケーション

Dataverse にデータをロードしたり、一括更新を実行するように設計されたアプリケーションは、サービス保護 API の制限エラーも管理できる必要もあります。 これらのアプリケーションはスループットを優先するので、最短時間で作業を完了できます。 これらのアプリケーションには、操作を再試行する方法が必要です。 最大のスループットを得るために適用できる方法はいくつかあります。 詳細: スループットを最大化する方法。

ポータル アプリケーション

ポータル アプリケーションは通常、匿名ユーザーからサービス プリンシパル アカウントを介して要求を送信します。 サービス保護 API の制限はユーザー単位のため、ポータル アプリケーションは、ポータルで発生するトラフィック量に基づいてサービス保護 API の制限に達する可能性があります。 対話型クライアント アプリケーションと同様に、サービス保護 API の制限エラーがポータル エンド ユーザーに表示されることは想定されていません。 UI が、それ以上の要求を無効にし、サーバーがビジーであるというメッセージを表示するようにします。 メッセージには、アプリケーションが新しい要求の受け入れを開始できる時間が含まれる場合があります。

プラグインおよびユーザー定義ワークフロー活動の影響

プラグインとユーザー定義ワークフロー活動は、受信要求によってトリガーされるビジネス ロジックを適用します。 サービス保護制限は、プラグインおよびユーザー定義ワークフロー活動には適用されません。 プラグインとユーザー定義ワークフロー活動がアップロードされ、分離されたサンドボックス サービス内で実行されます。 サンドボックス サービスで呼び出される Dataverse 操作は、パブリック API エンドポイントを使用しません。

アプリケーションがユーザー定義ロジックをトリガーする操作を実行する場合、プラグインまたはユーザー定義ワークフロー活動によって送信された要求の数は、サービス保護 API の制限にカウントされません。 ただし、これらの操作がもたらす追加の計算時間は、それらをトリガーした最初の要求に追加されます。 この計算時間は、サービス保護の API 制限に含まれます。 詳細: サービス保護のAPI制限の実施について

再試行操作

サービス保護 API の制限エラーが発生すると、ユーザーからの新しい要求が処理されるまでの期間を示す値が提供されます。

• 429 エラーが Web API から返された場合、応答には後に試行の秒数が含まれます。
• .NET 用 SDK を使うと、TimeSpan 値が OrganizationServiceFault.ErrorDetails で返されます Retry-After キーを使用するコレクション。

Retry-After 期間

Retry-After 期間は、直前の 5 分間に送信された操作の性質によって異なります。 要求の負荷が高いほど、サーバーの回復に時間がかかります。

現在、制限の評価方法により、サービス保護 API の制限が有効になるまでに、要求数と実行時間の制限が 5 分間超えることが予想されます。 ただし、同時実行要求の数を超えるとすぐにエラーが返されます。 アプリケーションがこのように負荷の高い要求を送信し続ける場合、共有リソースへの影響を最小限に抑えるために期間が延長されます。 これにより、個々の Retry-After 期間が長くなるため、アプリケーションが待機している間、非アクティブ状態の期間が長くなります。 この動作は将来変更される可能性があります。

可能であれば、要求の数を減らし、サービス保護 API の制限に達するまで徐々に増やして、一定のレートを達成することをお勧めします。 その後、5 分以内に処理できる要求の数をサーバーに通知します。 要求の最大数をこの 5 分の期間内に制限し、徐々に増やしていくと、Retry-After 期間を低く抑え、合計スループットを最適化し、サーバー リソースのスパイクを最小限に抑えられます。

対話型アプリケーションの再試行

クライアントが対話型アプリケーションの場合、ユーザーが行った要求を再試行する間、サーバーがビジーであることを示すメッセージを表示する必要があります。 ユーザーが操作をキャンセルするためのオプションを提供することができます。 送信した前の要求が完了するまで、ユーザーがそれ以上要求を送信できないようにします。

非対話型アプリケーションの再試行

クライアントが対話型でない場合、一般的には、要求が再度送信される前に、期間が経過するのを待つだけです。 これは、Task.Delay または同等のメソッドを使用して、現在のタスクの実行を一時停止することで行われます。

再施行方法

以下では、.NET 用 Dataverse SDK または Web API を使用して .NET アプリケーションを再試行する方法について説明します。

/// <summary>
/// Specifies the Retry policies
/// </summary>
/// <param name="config">Configuration data for the service</param>
/// <returns></returns>
static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy(Config config)
{
    return HttpPolicyExtensions
      .HandleTransientHttpError()
      .OrResult(httpResponseMessage => httpResponseMessage.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
      .WaitAndRetryAsync(
         retryCount: config.MaxRetries,
         sleepDurationProvider: (count, response, context) =>
         {
            int seconds;
            HttpResponseHeaders headers = response.Result.Headers;

            if (headers.Contains("Retry-After"))
            {
               seconds = int.Parse(headers.GetValues("Retry-After").FirstOrDefault());
            }
            else
            {
               seconds = (int)Math.Pow(2, count);
            }
            return TimeSpan.FromSeconds(seconds);
         },
         onRetryAsync: (_, _, _, _) => { return Task.CompletedTask; }
      );
}

サービス保護 API の制限の適用方法

サービス保護 API の制限のうち 2 つは、5 分 (300 秒) のスライディング ウィンドウ内で評価されます。 過去 300 秒以内にいずれかの制限を超えた場合、[後に試行] 期間が終了するまで、サービスを保護するための後続の要求でサービス保護 API 制限エラーが返されます。

サービス保護 API の制限は、ユーザーごとに評価されます。 認証された各ユーザーは個別に制限されます。 特別な要求をしているユーザー アカウントのみが制限されます。 他のユーザーは影響を受けません。

サービス保護 API の制限は、次の 3 つのファセットに基づいて実施されます。

• ユーザーが送信したリクエストの数。
• ユーザーから送られてきたリクエストの処理に必要な実行時間の合計。
• ユーザーが送信した同時実行要求の数。

ユーザーが送信する要求の数に制限がある場合は、それをバイパスすることができます。 これらの試行に対して他のファセットが追加されました。 たとえば、次のようなものです。

• バッチ操作でバンドルすることにより、送信する要求を減らすことができます。
  • 合計実行時間制限はこれに対するものです。
• 要求を個別に連続して送信するのではなく、サービス保護 API の制限が適用される前に、多数のリクエストを同時に送信できます。
  • 同時実行要求制限はこれに対するものです。

環境で利用可能な各 Web サーバーは、これらの制限を個別に適用します。 ほとんどの環境には、複数の Web サーバーがあります。 試用環境には、単一の Web サーバーのみが割り当てられます。 ご使用の環境で使用できる Web サーバーの実際の数は、提供する管理されたサービスの一部である複数の要因によって異なります。 要因の 1 つは、購入したユーザー ライセンスの数です。

次の表は、Web サーバー 1 台あたりで実施されるサービス保護 API のデフォルトの制限値です。

返されたサービス保護 API の制限エラー

このセクションでは、返される可能性のある 3 種類のサービス保護 API の制限エラーと、これらのエラーの原因となる可能性のある軽減策について説明します。

• エラー コード は、.NET 用 SDK OrganizationServiceFault.ErrorDetails によって返される数値のエラー値です。
• 16 進コードは、Web API から返される 16 進数のエラー値です。

要求の数

この制限は、前の 300 秒間の要求の総数をカウントします。

アプリケーションでユーザーが一括操作を実行できる場合以外、対話型アプリケーションの一般的なユーザーが、この制限を超える 1 分あたり 1,200 の要求を送信することはできません。

たとえば、リスト ビューで一度に 250 レコードの選択が可能で、ユーザーがこれらすべてのレコードに対して何らかの操作を実行できる場合、ユーザーはこの操作を 300 秒間に 24 回実行する必要があります。 ユーザーは各リストの操作を 12.5 秒以内に完了する必要があります。

アプリケーションがこの機能を提供する場合、以下の方法のいくつかを検討する必要があります。

• リストで選択できるレコードの総数を減らします。 リストに表示されるアイテムの数を 50 に減らすと、ユーザーはこの操作を 300 秒以内に 120 回実行する必要があります。 ユーザーは各リストの操作を 2.5 秒以内に完了する必要があります。
• 選択した操作をバッチに結合します。 バッチには最大 1000 個の操作を含めることができ、要求数の制限を回避できます。 ただし、実行時間の制限に備える必要があります。

実行時間

この制限は、先行する 300 秒間に受信した要求の合計実行時間を追跡します。

一部の操作では、他の操作よりも多くのリソースが必要です。 バッチ操作、インポート ソリューション、および非常に複雑なクエリでは、負荷が非常に高くなる場合があります。 これらの操作は、同時実行要求で同時に実行することもできます。 したがって、5 分のウィンドウ内で、合計で 20 分を超える合計計算時間を必要とする操作を要求することができます。

この制限は、要求数の制限を回避するためにバッチ操作と同時実行要求を使用する方法が使用されている場合に発生する可能性があります。

同時実行要求

この制限は、同時実行要求の数を追跡します。

クライアント アプリケーションは、個々の要求を順番に送信するだけではありません。 クライアントは、並列プログラミング パターンやさまざまなメソッドを適用して、複数の要求を同時に送信できます。 サーバーは、同じユーザーからの複数の要求に同時に応答していることを検出できます。 この同時実行要求数を超えると、このエラーがスローされます。 場合によっては、制限が 52 を超えることがあります。

同時実行要求を送信することは、スループットを最大化するための方法の重要な部分ですが、制御下に置いておくことが重要です。 .NET における並列プログラミングを使用する場合、デフォルトの並列度は、コードを実行しているサーバーの CPU コアの数によって異なります。 制限を超えないようにしてください。 ParallelOptions.MaxDegreeOfParallelism プロパティを同時実行タスクの最大数を定義するように設定できます。

詳細: 並行リクエストを送信する

スループットを最大化する方法

最短期間でほとんどのデータを移動するため、スループットを優先する必要があるアプリケーションの場合に適用できる方法がいくつかあります。

サーバーがどれだけ処理できるかを通知するようにします

一度に送信する要求の数を計算しようとしないでください。 それぞれの環境は異なる場合があります。 制限に達し始めるまで要求を送信するレートを徐々に上げて、サービス保護 API の制限の Retry-After 値に応じて、いつさらに送信すべきかを通知します。 この値は、スループット総数を可能な限り高いレベルに保ちます。

複数のスレッドの使用

同時スレッド数の上限を、アプリケーションでパフォーマンスを大幅に向上させるために使用できます。 これは、個々の操作が比較的速い場合に当てはまります。 処理するデータの性質によっては、最適なスループットを得るためにスレッド数を調整する必要があります。 詳細: 並行リクエストを送信する

規模の大きなバッチは避ける

バッチ処理 とは、1 回のリクエストで複数の操作を送信することです。

ほとんどのシナリオでは、高度な並列処理で単一の要求を送信するのが最も高速です。 バッチ サイズによってパフォーマンスが向上する可能性がある場合は、10 の小さなバッチサイズから始めて、再試行するサービス保護 API の制限エラーが発生し始めるまで、同時実行数を増やすことをお勧めします。

ExecuteMultipleRequest を使用した .NET 用 SDK は、通常 1 件の要求で最大 1,000 の操作を送信できます。 主な利点は、ネットワーク経由で送信する必要のある XML ペイロードの総量が削減されることです。 これにより、ネットワーク遅延が問題となる場合にパフォーマンスを向上できます。 サービス保護制限の場合、要求ごとの合計実行時間が増加します。 バッチのサイズが大きいほど、要求数の制限ではなく、実行時間の制限が発生する可能性が高くなります。

以前は、パフォーマンスに影響を与える可能性があるため、ExecuteMultiple 操作が 2 件に限られていました。 しかし、サービス保護の実行時間 API の制限が不要になったため、操作の制限はなくなりました。

Web API を使用する場合、個々の要求に対してネットワーク経由で送信される JSON ペイロードが小さいため、ネットワーク遅延は問題ではありません。 詳細: Web API を使用してバッチ操作を実行する

サービス保護 API の制限の管理方法

このセクションでは、サービス保護 API の制限エラーを回避するようにクライアントとシステムを設計する方法について説明します。 影響を減らすために、ライセンス管理の方法を考慮することもできます。

クライアント アプリケーションの更新

サービス保護 API の制限は 2018 年から Dataverse に適用されていますが、これらの制限が存在する前に作成されたクライアント アプリケーションが多く存在します。 これらのクライアントは、これらのエラーを予期していないため、エラーを正しく処理できません。 これらのアプリケーションを更新し、パターンを上記の 再試行操作 に適用する必要があります。

リアルタイム統合に向けて

サービス保護 API の制限の主なポイントは、短期間に発生する負荷の高い要求の影響を取り除くことです。 現在のビジネス プロセスが、大量のデータを短期間に処理しようとする夜間、毎週、または毎月の大規模で定期的なジョブに依存している場合は、リアルタイム データ統合方法を有効にする方法を検討してください。 負荷の高い操作を必要とするプロセスを避けられる場合は、サービス保護の制限による影響を軽減できます。

よく寄せられる質問

このセクションには、よく寄せられる質問が含まれています。 回答されていない質問がある場合は、このページの下部にあるフィードバックボタンを使用して、このページに関するフィードバックを送信してください。

ライセンスを取得した ETL アプリケーションを使用しています。 最適なスループットを得る方法を教えてください。

ETL アプリケーション ベンダーと協力して、適用する設定を確認します。 Retry-After 動作をサポートするバージョンの製品を使用していることを確認してください。

これらの制限は Dataverse 検索に適用されますか?

いいえ。 Dataverse ネイティブ検索は別の API (api/data ではなく api/search) で、異なるルールがあります。 Dataverse 検索 API を使用する場合、ユーザーごとに 1 秒あたり 1 リクエストの制限があります。

詳細: Dataverse 検索サービス保護の制限

これらの制限は、ユーザーが 1 日に受け取る資格がある要求の数にどのように適用されますか?

これらの制限は、資格制限とは関係ありません。 詳細: 権利制限

アプリケーション ユーザーごとに異なる制限が適用されますか?

いいえ。 制限は、すべてのユーザーに同様に適用されます。

参照

Power Platform の管理 / ライセンスとライセンス管理 / 要求の制限と割り当て
Dataverse API の制限の概要
Dataverse Web API を使用する
.NET 用 Dataverse SDK を使用する