使用 ExecuteMultiple 提升大量資料載入的效能

 

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

您可以使用 ExecuteMultipleRequest 訊息在 Microsoft Dynamics 365 (線上和內部部署) 中支援更高傳輸量的大量訊息傳遞案例，尤其是 Microsoft Dynamics 365 (線上)，其中網路延遲可能是最大的限制因素。ExecuteMultipleRequest 會接受訊息 Requests 的輸入集合，執行每一個訊息要求，依它們出現在輸入集合中的順序，以及選擇性地傳回 Responses 集合，其中包含每個訊息的回覆或發生的錯誤。 輸入集合中的每個訊息要求都會分別以不同的資料庫交易處理。ExecuteMultipleRequest 是使用 IOrganizationService.Execute 方法執行。

一般來說，ExecuteMultipleRequest 的行為與您在輸入要求集合中分別執行每個訊息要求的行為相同，但是效能更佳。 您可以使用服務 Proxy 的 CallerId 參數，而且適用於執行輸入要求集合中的每個訊息。 外掛程式和工作流程活動的執行方式會如同處理每個訊息一般。

外掛程式形式的自訂程式碼和自訂工作流程活動甚至可以執行 ExecuteMultipleRequest。 不過，有幾個重點必須記住。 已註冊的同步外掛程式擲回的例外狀況會在回覆集合項目 Fault 參數中傳回。 如果外掛程式是在資料庫交易中執行，則外掛程式會執行 ExecuteMultipleRequest，而且會啟始交易回復，回復中包括 ExecuteMultipleRequest 所執行要求產生的所有資料變更。

本主題內容

範例

指定執行階段執行選項

執行階段限制

處理批次大小錯誤

範例

下列範例程式碼將示範執行多個建立作業的單一 ExecuteMultipleRequest。 稱為「設定」(Setting) 的執行階段執行選項可用來控制要求處理和傳回的結果。 這些執行階段選項將在下一節中討論。

// Get a reference to the organization service.
using (_serviceProxy = new OrganizationServiceProxy(serverConfig.OrganizationUri, serverConfig.HomeRealmUri,serverConfig.Credentials, serverConfig.DeviceCredentials))
{
    // Enable early-bound type support to add/update entity records required for this sample.
    _serviceProxy.EnableProxyTypes();

    #region Execute Multiple with Results
    // Create an ExecuteMultipleRequest object.
    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)_serviceProxy.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);
    }

' Get a reference to the organization service.
_serviceProxy = ServerConnection.GetOrganizationProxy(serverConfig)

Using _serviceProxy
    ' Enable early-bound type support to add/update entity records required for this sample.
    _serviceProxy.EnableProxyTypes()

    '#Region "Execute Multiple with Results"
    ' Create an ExecuteMultipleRequest object.
    ' Assign settings that define execution behavior: continue on error, return responses.
    ' Create an empty organization request collection.
    requestWithResults = New ExecuteMultipleRequest() With
        {
            .Settings = New ExecuteMultipleSettings() With
                        {
                            .ContinueOnError = False,
                            .ReturnResponses = True
                        },
            .Requests = New OrganizationRequestCollection()
        }

    ' Create several (local, in memory) entities in a collection. 
    Dim input As EntityCollection = GetCollectionOfEntitiesToCreate()

    ' Add a CreateRequest for each entity to the request collection.
    For Each entity In input.Entities
        Dim createRequest_Renamed As CreateRequest = New CreateRequest With {.Target = entity}
        requestWithResults.Requests.Add(createRequest_Renamed)
    Next entity

    ' Execute all the requests in the request collection using a single web method call.
    Dim responseWithResults As ExecuteMultipleResponse =
        CType(_serviceProxy.Execute(requestWithResults), ExecuteMultipleResponse)

    ' Display the results returned in the responses.
    For Each responseItem In responseWithResults.Responses

        If responseItem.Response IsNot Nothing Then
            ' A valid response.
            DisplayResponse(requestWithResults.Requests(responseItem.RequestIndex),
                            responseItem.Response)

        ElseIf responseItem.Fault IsNot Nothing Then
            ' An error has occurred.
            DisplayFault(requestWithResults.Requests(responseItem.RequestIndex),
                         responseItem.RequestIndex, responseItem.Fault)
        End If
    Next responseItem

若要檢視完整的範例，請參閱範例：執行多個請求。

指定執行階段執行選項

ExecuteMultipleRequest 的 Settings 參數會套用至控制執行行為和傳回結果的要求集合中的所有要求。 讓我們深入了解這些選項。

ExecuteMultipleSettings 成員	描述
ContinueOnError	若為 true，則繼續處理集合中的下一個要求，即使處理集合中的目前要求已傳回錯誤。 若為 false，則不繼續處理下一個要求。
ReturnResponses	若為 true，則傳回來自所處理的每個訊息要求的回覆。 若為 false，則不傳回回覆。 如果設為 true 且要求的原始設計為不傳回回覆，則該要求的 ExecuteMultipleResponseItem 會設定為 null。 不過，即使為 false，如果傳回錯誤，Responses 集合將不會是空的。 如果傳回錯誤，集合中每個傳回錯誤的已處理要求都會有一個回覆項目，而且 Fault 將設定為發生的實際錯誤。

例如，在包含六個要求的要求集合中，第三個和第五個要求傳回錯誤，下表將指出 Responses 集合中會包函的內容。

設定	回覆集合內容
ContinueOnError=true, ReturnResponses=true	6 個回覆項目：其中 2 個的 Fault 設定為值。
ContinueOnError=false, ReturnResponses=true	3 個回覆項目：其中 1 個的 Fault 設定為值。
ContinueOnError=true, ReturnResponses=false	2 個回覆項目：其中 2 個的 Fault 設定為值。
ContinueOnError=false, ReturnResponses=false	1 個回覆項目：其中 1 個的 Fault 設定為值。

回覆項目中的 RequestIndex 參數表示與回覆相關聯的要求的序號，以零起始。 在前面的範例中，第三個要求的要求索引為 2。

執行階段限制

使用 ExecuteMultipleRequest 有數項相關限制，如下列清單中所述。

• 不允許遞迴 - ExecuteMultipleRequest 無法叫用 ExecuteMultipleRequest。 存在要求集合中的 ExecuteMultipleRequest 將會對該要求項目產生錯誤。

• 最大批次大小 – 能夠新增至要求集合中的要求數目有所限制。 如果超過該限制，則會在第一個要求尚未執行之前就擲回錯誤。 1000 要求數目上限是一般，雖然可對 Microsoft Dynamics 365 部署設定此最大數量。 此限制的部署設定為 BatchSize。

• 同時呼叫的節流 – 對於 Microsoft Dynamics 365 (線上)，每個組織最多只能有 2 個同時執行的 ExecuteMultipleRequest。 如果超過該限制，則會在第一個要求尚未執行之前就擲回「伺服器忙碌中」錯誤。 對於內部部署的部署，預設不會啟用節流。 此限制的部署設定為 ExecuteAsyncPerOrgMaxConnectionsPerServer。

  提示

  部署管理員可對任何 Dynamics 365 部設定或變更節流限制。

處理批次大小錯誤

當您的輸入要求集合超過最大批次大小時，該怎麼做？ 您的程式碼無法透過部署 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 it
    // 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;
}

Catch fault As FaultException(Of OrganizationServiceFault)

    ' Check if the maximum batch size has been exceeded. The maximum batch size is only included in the fault if it
    ' the input request collection count exceeds the maximum batch size.
    If fault.Detail.ErrorDetails.Contains("MaxBatchSize") Then

        Dim maxBatchSize As Integer = Convert.ToInt32(fault.Detail.ErrorDetails("MaxBatchSize"))
        If maxBatchSize < requestWithResults.Requests.Count Then
            ' 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)
        End If
    End If
    ' Re-throw so Main() can process the fault.
    Throw
End Try

另請參閱

Execute
OrganizationRequest
OrganizationResponse
使用組織服務讀取和寫入資料或中繼資料
組織服務中的 xRM 訊息
探索服務的訊息
組織服務中的 Dynamics 365 訊息
匯入資料

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權