使用 Upsert 插入或更新记录

  • 项目

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

可以使用 UpsertRequest 消息减少数据集成方案的复杂性。 在将数据从外部系统加载 Microsoft Dynamics 365 时，例如，在批量数据集成方案中，您可能不知道记录是否已存在于 Dynamics 365 中。 在这些情况下不知道是否应调用 UpdateRequest 还是 CreateRequest 操作。 这样就需要在执行相应操作之前首先查询记录以确定它是否存在。 您可以使用新的 UpsertRequest（更新或插入）消息减少此复杂性，将数据更高效地加载到 Dynamics 365。

本主题内容

使用 Upsert

了解 Upsert 流程

示例代码

使用 Upsert

最好在只有当您不能确定记录是否存在时再使用 UpsertRequest。 即，在不确定是否应该调用 CreateRequest 或 UpdateRequest 操作时。 但在使用 UpsertRequest 时会影响性能（对比使用 CreateRequest）。 如果您确定记录不存在，则使用 CreateRequest。

UpsertRequest 包含一个名为 Target 的属性。 此属性包含将在 UpdateRequest 或 CreateRequest 操作中使用的实体定义。 它还包括目标实体类型的 CreateRequest 所需的所有属性，以便在记录不存在时可以创建记录。

您可以检查 RecordCreated 以确定记录是否已创建。 如果记录不存在并已创建，则 RecordCreated 为 true。 如果记录已存在并已更新，它将为 false。Target 将是对已发现存在或已创建的记录的 EntityReference。

若要了解 UpsertRequest 如何工作，请参阅以下部分。

了解 Upsert 流程

以下步骤介绍收到 UpsertRequest 时的处理逻辑：

  1. 发送包含足够数据的 UpsertRequest 用于创建或插入操作。

  2. Microsoft Dynamics 365 将查找目标实体定位的记录。

  3. 如果记录已存在：

    1. 设置带有找到记录的 ID 的目标实体的 ID 属性。

    2. 调用更新。

    3. 将 RecordCreated 设置为 false。

    4. 从更新的目标实体作为 Target 的值创建 EntityReference。

    5. 返回 UpsertResponse。

  4. 如果记录不存在：

    1. 将所有备用键复制到目标实体属性。

    2. 调用 Create。

    3. 将 RecordCreated 设置为 true。

    4. 从 Create 请求的目标实体类型和 ID 结果作为 Target 的值创建 EntityReference。

    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

© 2017 Microsoft。 保留所有权利。 版权