Einen Datensatz mit Upsert erstellen oder aktualisieren

Artikel
08/03/2023

Sie können die Komplexität verringern, die in Datenintegrationsszenarien involviert ist, indem Sie die Nachricht Upsert verwenden. Wenn Sie Daten von einem externen System in Microsoft Dataverse laden, beispielsweise in einem Massendaten-Integrationsszenario, wissen Sie möglicherweise nicht, ob ein Datensatz bereits in Dataverse vorhanden ist. In solchen Fällen können Sie nicht wissen, ob Sie die Update- oder Create-Nachricht verwenden sollten. Sie müssen den Datensatzes zuerst abrufen, um zu bestimmen, ob er vorhanden ist, bevor der entsprechende Vorgang ausgeführt wird. Sie können diese Komplexität durch Verwendung der Upsert-Nachricht jetzt reduzieren und Daten effizienter in Dataverse laden.

Es gibt Leistungseinbußen beim Verwenden von Upsert im Vergleich zum Verwenden von Create. Wenn Sie sicher sind, dass der Datensatz nicht vorhanden ist, verwenden Sie Create.

Hinweis

Während Sie Primärschlüsselwerte mit Upsert verwenden können, wird im Allgemeinen erwartet, dass Sie alternative Schlüssel verwenden, da der übliche Anwendungsfall Datenintegrationsszenarien sind. Weitere Informationen: Einen lternativschlüssel verwenden, um auf einen Datensatz zu verweisen

Upsert für eine elastische Tabelle

Das Verhalten elastischer Tabellen für Upsert unterscheidet sich von Standardtabellen. Bei elastischen Tabellen ruft der Upsert-Vorgang nicht die Create- oder Update-Nachricht auf, je nachdem, ob der Datensatz bereits vorhanden ist oder nicht. Upsert wendet die Änderungen direkt in der Entität an.

Wenn der Datensatz vorhanden ist: Alle Daten im Datensatz werden durch die Daten in der Entität überschrieben. Es gibt kein Update-Ereignis.
Wenn der Datensatz nicht vorhanden ist: Es wird ein neuer Datensatz erstellt. Es gibt kein Create-Ereignis.

Dies hat Auswirkungen darauf, wo Sie Geschäftslogik für Ereignisse anwenden. Ein neuer Datensatz kann entweder mit Create oder Upsert erstellt werden. Ein Datensatz kann entweder mit Update oder Upsert aktualisiert werden. 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: Upsert-Prozess für einen Datensatz in einer elastischen Tabelle

Den Upsert-Prozess für Standardtabellen verstehen

Upsert-Nachrichten werden auf dem Server verarbeitet. Das SDK für .NET-Klassen verwendet dieselben Objekte, die auf dem Server verwendet werden. Daher wird in der folgenden Erklärung das SDK für .NET-Klassen verwendet, um zu beschreiben, wie eine UpsertRequest-Instanz verarbeitet und die UpsertResponse-Instanz zurückgegeben wird.

In den folgenden Schritten wird die Verarbeitungslogik auf dem Server bei Erhalt von UpsertRequest für eine Standardtabelle beschrieben:

Die UpsertRequest-Instanz kommt mit der Target Property gesetzt mit einer Entity-Instanz mit den Daten für einen Create‑ Update-Vorgang.
- Die Entity-Instanz hat normalerweise den Entity.KeyAttributes Property-Satz mit Werten, die verwendet werden, um den Datensatz mit alternativen Schlüsseln zu identifizieren.
Wenn es existiert, wird Dataverse versuchen, den Datensatz mithilfe von der Eigenschaft Entity.Id auf der Entity-Instanz zu suchen, die auf die Eigenschaft Target festgelegt ist. Andernfalls werden die Alternativschlüssel-Werte aus Entity.KeyAttributes Property verwendet.
Wenn der Datensatz vorhanden ist:
1. Stellen Sie die TargetEntity.Id mit dem Primärschlüsselwert des gefundenen Datensatzes ein.
2. Entfernen Sie alle Daten aus der Sammlung Target Entity.Attributes, die dieselben Schlüssel verwenden, die in der Sammlung Target Entity.KeyAttributes verwendet werden.
3. Rufen Sie Update auf.
4. Setzen Sie die Eigenschaft UpsertResponse.RecordCreated auf false.
5. Erstellen Sie eine EntityReference von der Target-Entität als Wert für UpsertResponse.Target.
6. Geben Sie den UpsertResponse zurück.
Wenn der Datensatz nicht vorhanden ist:
1. Kopieren Sie alle Daten aus Target Entity.KeyAttributes, über die Target nicht bereits verfügt in ihrer Entity.Attributes-Sammlung, in Target Entity.Attributes.
2. Rufen Sie Create auf.
3. Legen Sie den UpsertResponse.RecordCreated auf true fest.
4. Erstellen Sie eine EntityReference von der Target-Entität und das id-Ergebnis für den Vorgang Create als Wert für UpsertResponse.Target.
5. Geben Sie den UpsertResponse zurück.

Das folgende Diagramm zeigt den Prozess auf dem Server wenn ein UpsertRequest empfangen wird.

Upsert-Prozessfluss

Anleitung zum Verfassen von Anfragen

Bei der Verwendung von Alternativschlüsseln zum Identifizieren eines Datensatzes wird die Einbeziehung der Alternativschlüssel-Daten in den Teil der Anforderung, der die zu speichernden Daten darstellt, nicht empfohlen oder ist nicht erforderlich.

Web-API
SDK für .NET

Wenn Sie die Web-API verwenden und mit dem SDK für .NET nicht vertraut sind, ist der oben beschriebene serverseitige Prozess möglicherweise schwer nachvollziehbar. Die Web-API hat nicht das gleiche Objektmodell wie die SDK-Objekte, die in der obigen Beschreibung und dem Diagramm genutzt werden, aber die Daten können wie in der folgenden Tabelle gezeigt zugeordnet werden.

Internet-API	SDK	Beschreibung des Dataflows
Schlüsselwerte in URL	Entity.KeyAttributes Property	Enthält die Alternativschlüssel-Daten zur Identifizierung des Datensatzes.
Text der Anforderung	Die Entity festgelegt auf UpsertRequest.Target Property	Enthält die zu verwendenden Daten für `Create` oder `Update`.

Obwohl diese Anfragen wie oben beschrieben auf dem Server verarbeitet werden, kann man sich das so vorstellen:

Wenn der Datensatz vorhanden ist: Die im Hauptteil der Anforderung festgelegten Daten für diese Alternativschlüssel-Werte in der URL werden entfernt, es ergibt also keinen Sinn, sie einzubeziehen. Durch diese Vorgehensweise wird sichergestellt, dass Sie die Alternativschlüssel-Werte eines Datensatzes nicht aktualisieren können, wenn Sie diese Alternativschlüssel-Werte zur Identifizierung verwenden. Sie können Alternativschlüssel-Werte mit dem Primärschlüssel oder einem anderen Satz von Alternativschlüsseln ändern.
Wenn der Datensatz nicht vorhanden ist: Alle im Hauptteil der Anforderung festgelegten Alternativschlüssel-Werte werden zum Erstellen des neuen Datensatzes verwendet, auch wenn die Daten anders sind als die durch die Alternativschlüssel in der URL angegebenen Werte. Wenn im Hauptteil der Anforderung keine Alternativschlüssel-Daten vorhanden sind, werden die Alternativschlüssel-Daten aus der URL in den Hauptteil der Anfrage kopiert. Um eine Situation zu vermeiden, in der die Schlüsselwerte in der URL und die entsprechenden Schlüsselwerte im Textkörper nicht übereinstimmen, ist es am besten, sie überhaupt nicht in den Textkörper aufzunehmen.

Verwenden von Web-API

Bei der Web-API werden die Upsert- und Update-Nachrichten beide mit http PATCH initiiert gegen eine bestimmte EntitySet-Ressource, die durch die Schlüssel in der URL identifiziert wird.

Der Unterschied zwischen Upsert und Update wird dadurch definiert, ob die If-Match: * Anforderungsheader enthalten ist. Wenn der If-Match: *-Anforderungsheader enthalten ist und keine Ressource mit den Schlüsselwerten in der URL übereinstimmt, gibt die Anforderung einen 404 Not Found-Statuscode zurück. Der If-Match: *-Anforderungsheader stellt sicher, dass die PATCH-Anfrage einUpdate-Vorgang ist.

Wenn der If-Match: *-Anforderungsheader nicht enthalten isst, wird die PATCH-Anforderung wie eine Upsert behandelt und ein neuer Datensatz wird erstellt, wenn keine Datensätze gefunden werden, die den Schlüsseln in der URL entsprechen. Im Gegensatz zum SDK erfahren Sie in der Antwort jedoch nicht, ob ein Datensatz erstellt wurde. Die Statusantwort ist 204 No Content in jedem Fall.

Wenn Sie einen Prefer: return=representation-Anforderungsheader einschließen, gibt das System einen 201 Created-Status für Create und einen 200 OK-Status für Update zurück. Durch das Hinzufügen dieses Headers wird ein zusätzlicher Retrieve-Vorgang hinzugefügt, es wirkt sich also auf die Leistung aus. 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:

Mit einer PATCH-Anforderung können Sie auch den If-None-Match: *-Anforderungsheader zum Blockieren eines Update erfassen, wenn Sie nur Datensätze erstellen möchten. Weitere Informationen: upsert-Vorgänge begrenzen.

Web-API-Beispielcode

Die folgenden Beispiele zeigen Upsert-Vorgänge, die eine Tabelle mit zwei Alternativschlüssel-Spalten verwenden:

Erstellen Sie 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 Sie mit Upsert

Diese Anforderung aktualisiert den durch die obige Anforderung erstellten 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 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)

Hinweis

Die Antwort ist für Create- oder Update-Vorgänge identisch.

Mit „Upsert“ und der Einstellung „return=representation“ erstellen

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 Präferenz return=representation

Diese Anforderung aktualisiert den durch die obige Anforderung erstellten Datensatz und gibt den Status 200 OK zurück, um zu zeigen, dass es sich um einen Aktualisierungsvorgang handelte.

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 Method mit einer UpsertRequest-Instanz, bei der die Target Property mit einer Entity-Instanz festgelegt ist, die die Daten für einen Create- oder Update-Vorgang enthält. Die Entity-Instanz hat normalerweise den Entity.KeyAttributes Property-Satz mit Werten, die verwendet werden, um den Datensatz mit alternativen Schlüsseln zu identifizieren.

Die UpsertResponse.RecordCreated Property sagt Ihnen, ob der Datensatz erstellt wurde, und die 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 Einen Datensatz mit Upsert einfügen oder aktualisieren enthält die folgende ProcessUpsert-Methode, um die UpsertRequest-Meldung auf den Inhalt einer XML-Datei anzuwenden, 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
Definierter alternative Schlüssel für eine Tabelle
Verwenden Sie einen Alternativschlüssel, um auf einen Datensatz zu verweisen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über

Einen Datensatz mit Upsert erstellen oder aktualisieren

Upsert für eine elastische Tabelle

Den Upsert-Prozess für Standardtabellen verstehen

Anleitung zum Verfassen von Anfragen

Verwenden von Web-API

Web-API-Beispielcode

Erstellen Sie mit Upsert

Aktualisieren Sie mit Upsert

Mit „Upsert“ und der Einstellung „return=representation“ erstellen

Aktualisieren Sie mit Upsert und Präferenz return=representation

Verwenden des SDK für .NET

SDK für .NET-Beispielcode

Siehe auch

Zusätzliche Ressourcen