Upsert を使用してレコードを挿入または更新

[アーティクル]
04/22/2022

UpsertRequest メッセージを使用して、データ統合のシナリオに含まれる複雑さを減らすことができます。データを外部システムから Microsoft Dataverse に読み込むとき、大量データの統合の場合など、レコードが Dataverse に既に存在するかが分からない場合があります。このような場合、UpdateRequest または CreateRequest 操作を呼び出す必要があるかどうかが分かりません。この結果、適切な操作を実行する前に、そのレコードが存在するかどうかを決定するために、最初にそのレコードをクエリすることになります。現在は、新しい UpsertRequest (更新または送信) メッセージを使用して、この複雑さを減らしてデータを Dataverse により効率よく読み込むことができます。

Upsert の使用

レコードが存在するかどうかが確かでない場合にのみ、UpsertRequest を使用することをお勧めします。つまり、CreateRequest または UpdateRequest 操作を呼び出す必要があるかどうか確かでない場合です。 UpsertRequest の使用は、CreateRequest の使用に比べて、パフォーマンスの低下があります。レコードが存在しないことが確実な場合は、CreateRequest を使用します。

UpsertRequest には、Target という名前のプロパティが含まれています。このプロパティには、UpdateRequest または CreateRequest 操作で使用されるエンティティインスタンスが含まれています。これには、また、レコードが存在しない場合にそのレコードを作成できるように、CreateRequest によって要求される、対象のエンティティに対するすべての列も含まれています。

RecordCreated を確認して、レコードが作成されたかどうか判断することができます。 RecordCreated は、レコードが存在せず作成された場合に true になります。レコードが既に存在し、更新された場合は false です。 Target は、存在することが判明したレコード、または作成されたレコードに対する EntityReference となります。

UpsertRequest の動作の詳細については、次のセクションを参照してください。

Upsert プロセスの詳細

次の手順では、UpsertRequest を受け取ったときの、処理ロジックについて説明します。

作成または挿入の操作ために十分なデータう付けて、UpsertRequest を送信します。
Dataverse は、ターゲットエンティティの対象となるレコードを検索します。
レコードが存在する場合は、次の手順を実行します。
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 でレコードを挿入するサンプルの SampleMethod.cs ファイルは、次の ProcessUpsert メソッドを含み、XML ファイルのコンテンツに UpsertRequest メッセージを適用して、新しいレコードの作成や既存レコードの更新を実行します。

public static void ProcessUpsert(CrmServiceClient service, 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;
        var request = new UpsertRequest()
        {
            Target = productToCreate
        };

        try
        {
            // Execute UpsertRequest and obtain UpsertResponse. 
            var response = (UpsertResponse)service.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;
        }
    }
}

Upsert を使用してレコードを挿入または更新

Upsert の使用

Upsert プロセスの詳細

サンプルコード

関連項目

フィードバック

Upsert を使用してレコードを挿入または更新

Upsert の使用

Upsert プロセスの詳細

サンプル コード

関連項目

フィードバック

サンプルコード