サービス保護 API 制限

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

これらの制限は、対話型クライアントの通常のユーザーには影響しません。 影響を受けるのは、大量の API 要求を実行するクライアント アプリケーションのみです。 これらの制限により、Microsoft Dataverse プラットフォームの可用性とパフォーマンス特性を脅かす、要求ボリュームのランダムな急増や予期しない急増からの保護レベルが提供されます。

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

• Web API では、 429 要求が多すぎます というエラーが返されます。
• Dataverse SDK for .NET では、3 つの特定のエラー コードのいずれかで OrganizationServiceFault エラーが発生します。

返されるサービス保護 API の制限エラーについて説明します

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

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

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

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

クライアント アプリケーション開発者は、ユーザーにメッセージを表示するためにエラーをスローしてはいけません。 エラー メッセージはエンド ユーザー向けではありません。 操作を再試行するための特定の戦略について説明します

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

Dataverse にデータを読み込むか、一括更新を実行するように設計されたアプリケーションでは、サービス保護 API の制限エラーを管理する必要があります。 これらのアプリケーションは、最小限の時間で作業を完了できるように、スループットに優先順位を付けます。 そのようなアプリケーションには、操作の再試行に関する戦略が必要です。 最大スループットを取得するために適用できる戦略がいくつかあります。 スループットを最大化する方法について説明します

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

通常、ポータル アプリケーションは、サービス プリンシパル アカウントを通じて匿名ユーザーからの要求を送信します。 サービス保護 API の制限はユーザーごとに基づいているため、ポータル アプリケーションは、ポータルで発生するトラフィックの量に基づいてサービス保護 API の制限に達する可能性があります。 対話型クライアント アプリケーションと同様に、サービス保護 API を表示しないと、ポータルのエンド ユーザーにエラーが制限されます。 ポータルの UI は、それ以上の要求を無効にし、サーバーがビジー状態であることを示すメッセージを表示する必要があります。 メッセージには、エラーで返されたRetry-After 期間を使用して計算された、アプリケーションが新しい要求の受け入れを開始できる時間が含まれている可能性があります。

プラグインとカスタム ワークフロー アクティビティへの影響

プラグインとカスタム ワークフロー アクティビティは、受信要求によってトリガーされるビジネス ロジックを適用します。 サービス保護の制限は、プラグインとカスタム ワークフロー アクティビティに由来するデータ操作には適用されません。 プラグインとカスタム ワークフロー アクティビティがアップロードされ、分離サンドボックス サービス内で実行されます。 サンドボックス サービスで呼び出されたデータバース操作では、パブリック API エンドポイントは使用されません。

アプリケーションがカスタム ロジックをトリガーする操作を実行する場合、プラグインまたはカスタム ワークフロー アクティビティによって送信された要求の数は、サービス保護 API の制限にカウントされません。 ただし、これらの操作が提供する追加の計算時間は、それらをトリガーした最初の要求に追加されます。 この計算時間は、サービス保護 API の制限の一部です。 サービス保護 API の制限が適用される方法について説明します

再試行操作

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

• Web API から 429 エラーが返されると、応答には秒単位の Retry-After ヘッダーが含まれます。
• SDK for .NET では、キーがされた OrganizationServiceFault.ErrorDetails コレクションに Retry-After 値が返されます。

再試行後の待機時間

Retry-After期間は、前の 5 分間に送信された操作の性質によって異なります。 要求が厳しいほど、サーバーの復旧にかかる時間は長くなります。

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

可能であれば、要求の数を減らしてから、サービス保護 API の制限に達するまで徐々に増やして、一貫したレートを実現することをお勧めします。 その後、5 分以内に処理できる要求の数をサーバーに通知します。 この 5 分間に要求の最大数を制限し、徐々に増加することで再試行時間を低く抑え、合計スループットを最適化し、サーバー リソースの急増を最小限に抑えます。

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

クライアントが対話型アプリケーションの場合は、ユーザーが行った要求を再試行するときに、サーバーがビジーであることを示すメッセージを表示する必要があります。 ユーザーが操作を取り消すオプションを指定できます。 送信した前の要求が完了するまで、他の要求の送信をユーザーに許可しないでください。

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

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

再試行する方法

次に、Dataverse SDK for .NET または 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; }
      );
}

Service Protection API の制限の適用方法

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

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

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

• ユーザーが送信した要求の数。
• ユーザーによって送信された要求を処理するために必要な合計実行時間。
• ユーザーが送信した同時要求の数。

ユーザーが送信した要求の数に制限がある場合は、それをバイパスできます。 これらの試みに対抗するために、他のファセットが追加されました。 例えば次が挙げられます。

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

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

次の表では、 Web サーバーごとに適用される既定のサービス保護 API の制限について説明します。

返される Service Protection API の制限エラー

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

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

要求の数

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

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

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

アプリケーションでこの機能が提供される場合は、次の戦略のいくつかを検討する必要があります。

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

実行時間

この制限は、前の 300 秒の期間中の受信要求の合計実行時間を追跡します。

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

この制限は、バッチ操作と同時要求を使用する戦略を使用して要求数の制限を回避する場合に発生する可能性があります。

同時要求数

この制限により、同時要求の数が追跡されます。

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

同時要求の送信は、スループットを最大化するための戦略の重要な部分ですが、制御を維持することが重要です。 .NET で並列プログラミングを使用する場合、並列処理の既定の次数は、コードを実行しているサーバー上の CPU コアの数によって異なります。 制限を超えてはなりません。 ParallelOptions.MaxDegreeOfParallelism プロパティを設定して、同時実行タスクの最大数を定義できます。

並列要求の送信について説明します

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

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

処理できる量をサーバーに通知する

一度に送信する要求の数を計算しないでください。 環境ごとに異なる場合があります。 制限に達し始めるまで要求を送信する速度を徐々に増やし、サービス保護 API の制限 Retry-After 値に依存して、送信するタイミングを示します。 この値により、合計スループットが可能な限り高いレベルで維持されます。

複数のスレッドの使用

同時実行スレッドの数の上限が高いほど、アプリケーションでパフォーマンスが大幅に向上するために使用できます。 これは、個々の操作が比較的迅速な場合に当てはまります。 処理するデータの性質によっては、最適なスループットを得るためにスレッドの数を調整することが必要になる場合があります。 要求を並列で送信する方法について説明します

大量バッチを避ける

バッチ処理 とは、1 つの要求で複数の操作を送信することを指します。

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

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

以前は、 ExecuteMultiple 操作は、パフォーマンスに与える可能性のある影響のため、一度に 2 つだけに制限されていました。 サービス保護の実行時間 API の制限により、その制限が冗長になっているため、これはもはや当たりません。

Web API を使用する場合、個々の要求に対してネットワーク経由で送信される JSON ペイロードが小さいということは、ネットワーク待機時間が問題ではないことを意味します。 Web API を使用したバッチ操作の実行について説明します

Service Protection API の制限を管理するための戦略

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

クライアント アプリケーションを更新する

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

リアルタイム統合への移行

サービス保護 API の主な制限は、要求の厳しい要求が短期間に発生した場合の影響をスムーズにすることです。 現在のビジネス プロセスが、短時間で大量のデータを処理しようとする大規模な夜間、毎週、または毎月のジョブに依存している場合は、リアルタイムのデータ統合戦略を有効にする方法を検討してください。 要求の厳しい操作を必要とするプロセスから離れる場合は、サービス保護の制限に与える影響を軽減できます。

よく寄せられる質問

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

ライセンスを取得した ETL アプリケーションを使用しています。 最適なスループットを得るにはどうすればよいですか?

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

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

No. Dataverse ネイティブ検索は異なる API (api/searchではなくapi/data) であり、規則が異なります。 Dataverse 検索 API を使用する場合、ユーザーごとに 1 秒あたり 1 つの要求の調整制限があります。

Dataverse Search Service Protection の制限について説明します

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

これらの制限は、エンタイトルメントの制限とは関係ありません。 エンタイトルメントの制限について説明します

制限はアプリケーション ユーザーに対して異なる方法で適用されますか?

No. 制限は、すべてのユーザーに同じ方法で適用されます。

こちらも参照ください

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