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

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

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 には Fault に値が設定されています。

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

ランタイムの制限

次の一覧では、 ExecuteMultipleRequestの使用に関連する制約について説明します。

  • 再帰なしExecuteMultipleRequestは別のExecuteMultipleRequestを呼び出すことはできません。 要求コレクションに ExecuteMultipleRequestが含まれている場合、その要求項目のエラーが生成されます。
  • 最大バッチ サイズ 要求コレクションに追加できる要求の数は限られています。 この制限を超えると、システムは最初のリクエストを実行する前にフォールトを発生させます。 通常、要求数は 1,000 個に制限されますが、Dataverse デプロイに対してこの最大量を設定できます。

注

以前は、同時実行 ExecuteMultiple 要求の数に制限がありました。 その制限は 2 でした。 Microsoftサービス保護の制限によって不要になるため、この制限は削除されました。 詳細については、「 Service Protection 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 を使用する

  • 最終更新: