使用 Upsert 插入或更新記錄

發行項
03/04/2017

發行︰ 2017年1月

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

您可以使用 UpsertRequest 訊息降低資料整合案例的複雜性。例如在大量資料整合案例中，從外部系統將資料載入 Microsoft Dynamics 365 時，您可能不清楚記錄是否已存在 Dynamics 365 中。在這種情況下，您不會知道應該呼叫 UpdateRequest 或 CreateRequest 作業。這會導致您先查詢記錄，以判斷記錄是否存在，然後才執行適當的作業。現在您可以免除這種複雜性，以更有效率的方式將資料載入 Dynamics 365 中，也就是使用新的 UpsertRequest (更新或插入) 訊息。

本主題內容

使用 Upsert

了解 Upsert 程序

範例指令碼

使用 Upsert

如果您不確定記錄是否存在，最好使用 UpsertRequest。也就是說，如果您不確定要呼叫 CreateRequest 或 UpdateRequest 作業。使用 UpsertRequest 與使用 CreateRequest 相較之下，會造成效能降低。如果您確定記錄不存在，請使用 CreateRequest。

UpsertRequest 包括名為 Target 的屬性。此屬性包含將在 UpdateRequest 或 CreateRequest 作業中使用的實體定義。它也包括 CreateRequest 需要用於目標實體類型的所有屬性，以便在記錄不存在時建立該記錄。

您可以檢查 RecordCreated，判斷記錄是否已建立。如果記錄不存在且已建立，RecordCreated 會是 True。如果記錄已存在且已更新，則會是 false。Target 會是發現存在的記錄或已建立記錄的 EntityReference。

如要了解 UpsertRequest 如何運作，請參閱後續章節。

了解 Upsert 程序

下列步驟說明收到 UpsertRequest 時的處理邏輯：

傳送足夠的資料給 UpsertRequest 以執行建立或插入作業。
Microsoft Dynamics 365 將查詢目標實體的目標記錄。
如果記錄已存在：
1. 將目標實體的 ID 屬性設定為所找到記錄的 ID。
2. 呼叫更新。
3. 將 RecordCreated 設定為 false。
4. 從更新的目標實體建立 EntityReference 做為 Target 的值。
5. 傳回 UpsertResponse。
如果記錄不存在：
1. 將任何其他索引鍵值複製到目標實體屬性內。
2. 呼叫 Create。
3. 將 RecordCreated 設定為 true。
4. 從目標實體類型和 Create 要求的 ID 結果建立 EntityReference，做為 Target 的值。
5. 傳回 UpsertResponse。

下圖顯示收到 UpsertRequest 時展開的程序。

upsert process flow

範例指令碼

使用 Upsert 插入或更新記錄範例 ProductUpsertSample.cs 檔案包含下列 ProcessUpsert 方法，可在 XML 檔案的內容上套用 UpsertRequest 訊息，以建立新記錄或更新現有記錄。


public void ProcessUpsert(String Filename)
{
    Console.WriteLine("Executing upsert operation.....");
    XmlTextReader tr = new XmlTextReader(Filename);
    XmlDocument xdoc = new XmlDocument();
    xdoc.Load(tr);
    XmlNodeList xnlNodes = xdoc.DocumentElement.SelectNodes("/products/product");

    foreach (XmlNode xndNode in xnlNodes)
    {
        String productCode = xndNode.SelectSingleNode("Code").InnerText;
        String productName = xndNode.SelectSingleNode("Name").InnerText;
        String productCategory = xndNode.SelectSingleNode("Category").InnerText;
        String productMake = xndNode.SelectSingleNode("Make").InnerText;

        //use alternate key for product
        Entity productToCreate = new Entity("sample_product", "sample_productcode", productCode);

        productToCreate["sample_name"] = productName;
        productToCreate["sample_category"] = productCategory;
        productToCreate["sample_make"] = productMake;
        UpsertRequest request = new UpsertRequest()
        {
            Target = productToCreate
        };

        try
        {
            // Execute UpsertRequest and obtain UpsertResponse. 
            UpsertResponse response = (UpsertResponse)_serviceProxy.Execute(request);
            if (response.RecordCreated)
                Console.WriteLine("New record {0} is created!", productName);
            else
                Console.WriteLine("Existing record {0} is updated!", productName);
        }

        // Catch any service fault exceptions that Microsoft Dynamics CRM throws.
        catch (FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault>)
        {
            throw;
        }

    }
    // Prompts to view the sample_product entity records.
    // If you choose "y", IE will be launched to display the new or updated records.
    if (PromptForView())
    {
        ViewEntityListInBrowser();
    }

}

另請參閱

使用變更追蹤，同步處理資料與外部系統
 定義實體的其他索引鍵
 使用其他索引鍵建立記錄

Microsoft Dynamics 365

共用方式為

使用 Upsert 插入或更新記錄

本主題內容

使用 Upsert

了解 Upsert 程序

範例指令碼

另請參閱

其他資源