.NET 用 SDK を使用して複数の要求を実行する

  • [アーティクル]

複数の要求を実行する主な目的は、ネットワークを介して送信されるデータの総量を減らすことによって、長い待ち時間の環境でのパフォーマンスを向上させることです。

Microsoft Dataverse でより高いスループットの一括メッセージ渡しシナリオをサポートするために、ExecuteMultipleRequest メッセージを使用することができます。 ExecuteMultipleRequest はメッセージの Requests 入力コレクションを受け入れ、入力コレクションに表示される受注でメッセージ要求のサンプルのそれぞれを実行し、必要に応じて、各メッセージの応答または発生したエラーを含む Responses のコレクションを戻します。 入力コレクションの各メッセージ要求が別のデータベース トランザクションで処理されます。 ExecuteMultipleRequest は IOrganizationService.Execute メソッドを使用して実行されます。

一般に、ExecuteMultipleRequest は、より優れたパフォーマンスの場合を除き、入力要求コレクションの各メッセージ要求を実行する場合とほぼ同じように動作します。 サービス プロキシの CallerId パラメーターの使用は受け入れられ、入力要求コレクションの各メッセージの実行に適用されます。 処理されるメッセージごとに見込まれるため、プラグインとワークフロー活動が実行されます。

プラグインとカスタム ワークフロー アクティビティの使用は ExecuteMultipleRequest の使用からブロックされません。 ただし、これは推奨されません。 同期ステップで障害が発生した場合は、データの整合性を維持するためにすべてのデータ操作をロールバックする必要があります。 ExecuteMultiple 内で実行される各操作はロールバックする必要があります。 また、ExecuteMultiple は操作がプラグインの最大タイムアウト期間を超えた場合にも問題が発生します。

詳細: プラグインとワークフロー活動でバッチ要求タイプを使用しないでください

例

次のサンプル コードは、複数の作成操作を実行する単一の ExecuteMultipleRequest を示します。 設定と呼ばれるランタイム実行オプションは、要求処理と返された結果をコントロールするために使用されます。 これらのランタイム オプションは、次のセクションで説明します。


// Create an ExecuteMultipleRequest object.
ExecuteMultipleRequest requestWithResults = new ExecuteMultipleRequest()
{
    // Assign settings that define execution behavior: continue on error, return responses. 
    Settings = new ExecuteMultipleSettings()
    {
        ContinueOnError = false,
        ReturnResponses = true
    },
    // Create an empty organization request collection.
    Requests = new OrganizationRequestCollection()
};

// Create several (local, in memory) entities in a collection. 
EntityCollection input = GetCollectionOfEntitiesToCreate();

// Add a CreateRequest for each entity to the request collection.
foreach (var entity in input.Entities)
{
    CreateRequest createRequest = new CreateRequest { Target = entity };
    requestWithResults.Requests.Add(createRequest);
}

// Execute all the requests in the request collection using a single web method call.
ExecuteMultipleResponse responseWithResults =
    (ExecuteMultipleResponse)service.Execute(requestWithResults);

// Display the results returned in the responses.
foreach (var responseItem in responseWithResults.Responses)
{
    // A valid response.
    if (responseItem.Response != null)
        DisplayResponse(requestWithResults.Requests[responseItem.RequestIndex], responseItem.Response);

    // An error has occurred.
    else if (responseItem.Fault != null)
        DisplayFault(requestWithResults.Requests[responseItem.RequestIndex], 
            responseItem.RequestIndex, responseItem.Fault);
}

詳細: サンプル: 複数の要求を実行する

ランタイム実行方法を指定する

ExecuteMultipleRequest の Settings パラメーターは、実行動作と返されたをコントロールする要求コレクションの要求のすべてに適用されます。 これらのオプションをより詳細に参照することにします。

ExecuteMultipleSettings のメンバー 説明
ContinueOnError trueの場合、コレクションの次の要求の処理を続けます。フォールトがコレクションの現在の要求の処理から戻されている場合でもそうです。 false場合、次の要求は処理し続けません。
ReturnResponses trueの場合、処理された各メッセージ要求から応答を戻します。 falseの場合、応答は返されません。

trueに設定され、要求が応答を戻さない場合、そのような設計なので、その要求の ExecuteMultipleResponseItem は nullに設定されます。

しかし、エラーが返された場合、false、Responses のコレクションは空ではなくなります。 エラーが返された場合、フォールトを返した処理された各要求のコレクションに1つの応答アイテムがあり、Faultは発生した実際のフォールトに設定されます。

たとえば、6つの要求を含み、その3番目と5番目の要求がフォールトを返す要求コレクションの場合、次の表にはResponses のコレクションの内容を示します。

設定 応答コレクションの内容
ContinueOnError=true、ReturnResponses=true 6 種類の応答アイテム: 2 種類には1つの値に設定した Fault があります。
ContinueOnError=false、ReturnResponses=true 3 種類の応答アイテム: 1 種類には1つの値に設定した Fault があります。
ContinueOnError=true、ReturnResponses=false 2 種類の応答アイテム: 2 種類には1つの値に設定した Fault があります。
ContinueOnError=false、ReturnResponses=false 1 種類の応答アイテム: 1 種類には1つの値に設定した Fault があります。

応答アイテムの RequestIndex パラメーターは、応答が関連付けられている要求の、先頭がゼロで始まるシーケンス番号を示します。 前の例では、3 番目の要求には 2 の要求インデックスがあります。

ランタイムの制限

以下のリストで示すように、ExecuteMultipleRequest の使用に関する、いくつかの制限があります。

  • 再帰は許可されません ExecuteMultipleRequest は ExecuteMultipleRequestを起動できません。 要求コレクションで見つかる ExecuteMultipleRequest は、その要求アイテムに関するエラーを生成します。
  • 最大バッチ サイズ 要求コレクションに追加できる要求の数には制限があります。 この制限を超えると、最初の要求が実行される前にフォールトがスローされます。 Dataverse の展開に最大数を設定できますが、1000 個の制限が一般的です。

注意

以前は、同時実行 ExecuteMultiple 要求の数に制限がありました。 その制限は 2 でした。 サービス保護の制限により不要になったため、これは削除されました。 詳細情報: サービス保護 API の制限 を参照してください。

バッチ サイズのフォールトの処理

入力要求コレクションが最大サイズ バッチを超えた場合に何をすればよいですか。 コードでは、展開管理者ロールを持つアカウントで実行されていない限り、展開 web サービスを通して、最大サイズ バッチを直接を問い合わせることができません。

幸いにも、使用できる別の方法があります。 入力 Requests コレクションの要求の数が組織で許可されるバッチの最大サイズを超えている場合、フォールトが ExecuteMultipleRequest 呼び出しから返されます。 最大バッチ サイズがフォールトで返されます。 コードでは、その値のチェック、入力要求コレクションの指示制限内へのサイズ変更、および ExecuteMultipleRequestの再送信ができます。 次のコード スニペットはこのロジックの一部を示します。

catch (FaultException<OrganizationServiceFault> fault)
{
    // Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if
    // the input request collection count exceeds the maximum batch size.
    if (fault.Detail.ErrorDetails.Contains("MaxBatchSize"))
    {
        int maxBatchSize = Convert.ToInt32(fault.Detail.ErrorDetails["MaxBatchSize"]);
        if (maxBatchSize < requestWithResults.Requests.Count)
        {
            // Here you could reduce the size of your request collection and re-submit the ExecuteMultiple request.
            // For this sample, that only issues a few requests per batch, we will just print out some info. However,
            // this code will never be executed because the default max batch size is 1000.
            Console.WriteLine("The input request collection contains %0 requests, which exceeds the maximum allowed (%1)",
                requestWithResults.Requests.Count, maxBatchSize);
        }
    }
    // Re-throw so Main() can process the fault.
    throw;
}

参照

.NET 用 SDK でメッセージを使用する
ExecuteAsync を使用する
ExecuteTransaction を使用する

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。