Einen Datensatz mit Upsert erstellen oder aktualisieren

Sie können die Komplexität von Datenintegrationsszenarien verringern, indem Sie die Upsert Nachricht verwenden. Wenn Sie Daten aus einem externen System in Microsoft Dataverse laden, z. B. in einem Szenario für die Massendatenintegration, wissen Sie möglicherweise nicht, ob ein Datensatz bereits in Dataverse vorhanden ist. In diesen Fällen können Sie nicht entscheiden, ob Sie die Update-Nachricht oder die Create-Nachricht verwenden sollen. Sie müssen zuerst den Datensatz abrufen, um zu überprüfen, ob er vorhanden ist, bevor Sie den entsprechenden Vorgang ausführen. Sie können diese Komplexität durch Verwendung der Upsert-Nachricht jetzt reduzieren und Daten effizienter in Dataverse laden.

Es gibt Leistungseinbußen, wenn Sie Upsert anstelle von Create verwenden. Wenn Sie sicher sind, dass der Datensatz nicht vorhanden ist, verwenden Sie Create.

Upsert für eine elastische Tabelle

Das Verhalten flexibler Tabellen Upsert unterscheidet sich von dem Verhalten von Standardtabellen. Durch die Verwendung von elastischen Tabellen ruft der Upsert Vorgang die Create oder Update Nachricht nicht auf, je nachdem, ob der Datensatz bereits vorhanden ist. Upsert wendet die Änderungen direkt in der Entität an.

• Wenn der Datensatz vorhanden ist: Der Vorgang überschreibt alle Daten im Datensatz mit den Daten in der Entität. Es gibt kein Update-Ereignis.
• Wenn der Datensatz nicht vorhanden ist: Der Vorgang erstellt einen neuen Datensatz. Es gibt kein Create-Ereignis.

Dieses Verhalten wirkt sich darauf aus, wo Sie Geschäftslogik für Ereignisse anwenden. Sie können einen neuen Datensatz entweder mit Create oder Upsert erstellen. Sie können einen Datensatz entweder mit Update oder Upsert aktualisieren. Wenn Sie Logik konsistent für Create oder Update in elastischen Tabellen anwenden müssen, müssen Sie diese Logik auch in Upsert einschließen. Weitere Informationen finden Sie unter einfügen bzw. aktualisieren eines Datensatzes in einer elastischen Tabelle.

Grundlegendes zum Upsert-Prozess für Standardtabellen

Der Server verarbeitet upsert Nachrichten. Das SDK für .NET-Klassen verwenden dieselben Objekte wie der Server. Daher wird in der folgenden Erläuterung das SDK für .NET-Klassen verwendet, um zu beschreiben, wie der Server eine UpsertRequest-Klasseninstanz verarbeitet und eine UpsertResponse-Klasseninstanz zurückgibt.

Die folgenden Schritte beschreiben die Verarbeitungslogik auf dem Server, wenn sie ein UpsertRequest für eine Standardtabelle empfängt:

1. Die UpsertRequest-Instanz kommt mit der Target-Eigenschaft ein, die auf eine Entitätsinstanz festgelegt ist, die die Daten für einen Create Oder Update Vorgang enthält.
   • Die Entitätsinstanz weist in der Regel die Eigenschaft Entity.KeyAttributes mit Werten auf, die den Datensatz mithilfe alternativer Schlüssel identifizieren.
2. Wenn es vorhanden ist, versucht Dataverse, den Datensatz mithilfe der Entity.Id-Eigenschaft der Entitätsinstanz , die auf die Target-Eigenschaft festgelegt ist, nachzuschlagen. Andernfalls werden die alternativen Schlüsselwerte aus der Entity.KeyAttributes-Eigenschaft verwendet.
3. Wenn der Datensatz vorhanden ist:
   1. Legen Sie die TargetEntity.Id auf den Primärschlüsselwert des gefundenen Datensatzes fest.
   2. Entfernen Sie alle Daten aus der TargetEntity.Attributes-Auflistung , die dieselben Schlüssel wie die TargetEntity.KeyAttributes-Auflistung verwendet.
   3. Rufen Sie Update auf.
   4. Legen Sie die UpsertResponse.RecordCreated-Eigenschaft auf false fest.
   5. Erstellen Sie eine EntityReference aus der Target Entität als Wert für UpsertResponse.Target.
   6. Gibt "UpsertResponse" zurück.
4. Wenn der Datensatz nicht vorhanden ist:
   1. Kopieren Sie alle Daten von TargetEntity.KeyAttributes, das Target noch nicht in seiner Entity.Attributes-Sammlung hat, in TargetEntity.Attributes.
   2. Rufen Sie Create auf.
   3. Legen Sie UpsertResponse.RecordCreated auf true fest.
   4. Erstellen Sie eine EntityReference aus der Target Entität und das id Ergebnis des Create Vorgangs als Wert für UpsertResponse.Target.
   5. Gibt "UpsertResponse" zurück.

Das folgende Diagramm zeigt den Prozess auf dem Server, wenn er ein UpsertRequest empfängt.

Anleitung zum Verfassen von Anfragen

Wenn Sie alternative Schlüssel zum Identifizieren eines Datensatzes verwenden, schließen Sie die alternativen Schlüsseldaten nicht in den Teil der Anforderung ein, der die zu speichernden Daten darstellt.

Web-API verwenden

Mithilfe der Web-API können Sie die Upsert Und-Nachrichten Update initiieren, indem Sie eine HTTP-Anforderung PATCH an eine angegebene EntitySet Ressource senden. Die Schlüssel in der URL identifizieren die Ressource.

Der Unterschied zwischen Upsert und Update hängt davon ab, ob Sie den Anforderungsheader If-Match: * einschließen. Wenn Sie den Anforderungsheader If-Match: * einschließen und keine Ressource den Schlüsselwerten in der URL entspricht, gibt die Anforderung einen 404 Not Found Statuscode zurück. Der If-Match: *-Anforderungsheader stellt sicher, dass die PATCH-Anfrage einUpdate-Vorgang ist.

Wenn Sie den If-Match: * Anforderungsheader nicht einschließen, wird die PATCH Anforderung wie eine Upsertbehandelt. Die Anforderung erstellt einen neuen Datensatz, wenn keine Datensätze gefunden werden, die den Schlüsseln in der URL entsprechen. Im Gegensatz zum SDK teilt ihnen die Antwort jedoch nicht mit, ob ein Datensatz erstellt wurde. Die Statusantwort ist 204 No Content in jedem Fall.

Wenn Sie einen Anforderungsheader Prefer: return=representation einschließen, gibt das System einen 201 Created Status für Create und einen 200 OK Status für Update. Durch Hinzufügen dieses Headers wird ein zusätzlicher Retrieve Vorgang hinzugefügt, sodass er sich auf die Leistung auswirkt. Wenn Sie diese Option verwenden, stellen Sie sicher, dass die $select-Abfrageoption, die Sie hinzufügen, nur den Primärschlüsselwert enthält. Weitere Informationen findest du unter:

• Erstellen mit den zurückgegebenen Daten
• Aktualisieren mit den zurückgegebenen Daten

Mithilfe einer PATCH-Anforderung können Sie auch den If-None-Match: *-Anforderungsheader einfügen, um ein Update zu blockieren, wenn Sie nur Datensätze erstellen möchten. Für weitere Informationen siehe upsert-Vorgänge begrenzen.

Web-API-Beispielcode

Die folgenden Beispiele zeigen Upsert Vorgänge mithilfe einer Tabelle mit zwei alternativen Schlüsselspalten:

Erstellen mit Upsert

Diese Anfrage erstellt einen Datensatz.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/example_records(example_key1=2,example_key2=2) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json

{ "example_name": "2:2" }

Antwort:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/example_records(example_key1=2,example_key2=2)

Aktualisieren mit Upsert

Diese Anforderung aktualisiert den Datensatz, der von der vorherigen Anforderung erstellt wurde.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/example_records(example_key1=2,example_key2=2) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json

{ "example_name": "2:2 Updated" }

Antwort:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/example_records(example_key1=2,example_key2=2)

Erstellen mit der Upsert- und der return=representation-Präferenz

Wenn Sie den Prefer: return=representation-Header verwenden, können Sie einen anderen Statuscode in der Antwort erhalten, um anzugeben, ob der Datensatz erstellt oder aktualisiert wurde.

Die folgende Anforderung erstellt einen neuen Datensatz und gibt den Status 201 Created zurück.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/example_records(example_key1=3,example_key2=3)?$select=example_recordid HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Prefer: return=representation
Content-Type: application/json

{ "example_name": "3:3" }

Antwort:

HTTP/1.1 201 Created
Content-Type: application/json; odata.metadata=minimal
ETag: W/"71004878"
Preference-Applied: return=representation
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#example_records(example_recordid)/$entity",
  "@odata.etag": "W/\"71004878\"",
  "example_recordid": "ef0d112e-d70e-ed11-82e5-00224822577b"
}

Aktualisieren Sie mit Upsert und der Präferenz return=representation.

Diese Anforderung aktualisiert den datensatz, der von der vorherigen Anforderung erstellt wurde, und gibt den Status 200 OK zurück, um anzuzeigen, dass es sich um einen Aktualisierungsvorgang handelt.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/example_records(example_key1=3,example_key2=3)?$select=example_recordid HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Prefer: return=representation
Content-Type: application/json

{ "example_name": "3:3 Updated" }

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"71004880"
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#example_records(example_recordid)/$entity",
  "@odata.etag": "W/\"71004880\"",
  "example_recordid": "ef0d112e-d70e-ed11-82e5-00224822577b"
}

Verwenden des SDK für .NET

Ihre Clientanwendung verwendet die IOrganizationService.Execute-Methode mit einer UpsertRequest-Instanz , die die Target-Eigenschaft mit einer Entitätsinstanz festgelegt hat, die die Daten für einen Create Vorgang Update enthält. In der Regel legen Sie die Entity.KeyAttributes-Eigenschaft für die Entitätsinstanz mit Werten fest, die zum Identifizieren des Datensatzes mithilfe von alternativen Schlüsseln verwendet werden.

Die UpsertResponse.RecordCreated-Eigenschaft teilt Ihnen mit, ob der Datensatz erstellt wurde, und das UpsertResponse.Target enthält einen Verweis auf den Datensatz, der erstellt oder aktualisiert wurde.

SDK für .NET-Beispielcode

Die Datei SampleMethod.cs im Beispiel Insert record using Upsert enthält die folgende ProcessUpsert Methode. Diese Methode wendet die UpsertRequest Nachricht auf den Inhalt einer XML-Datei an, um neue Datensätze zu erstellen oder vorhandene zu aktualisieren.

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 Dataverse throws.
        catch (FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault>)
        {
            throw;
        }
    }
}

Siehe auch

Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung
Definieren Sie alternative Schlüssel für eine Tabelle
Verwenden Sie einen Alternativschlüssel, um auf einen Datensatz zu verweisen