Freigeben über

Aktualisieren und Löschen von Tabellenzeilen mithilfe der Web-API

Vorgänge, die Daten ändern, sind ein zentraler Bestandteil der Web-API. Zusätzlich zu einfachen Aktualisierungs- und Löschvorgängen können Sie Vorgänge für einzelne Tabellenspalten (Entitätsattribute) ausführen und Upsertanforderungen verfassen, die Daten aktualisieren oder einfügen, je nachdem, ob sie vorhanden ist.

Grundlegende Aktualisierung

Aktualisierungsvorgänge verwenden das HTTP-Verb PATCH . Übergeben Sie ein JSON-Objekt, das die Eigenschaften enthält, die Sie an den URI aktualisieren möchten, der den Datensatz darstellt. Wenn die Aktualisierung erfolgreich ist, gibt die Antwort einen Status von 204 No Content.

Die If-Match: * Kopfzeile stellt sicher, dass Sie keinen neuen Datensatz erstellen, indem Sie versehentlich einen Upsert-Vorgang ausführen. Weitere Informationen finden Sie unter „Erstellen in upsert verhindern“.

Von Bedeutung

Schließen Sie beim Aktualisieren einer Entität nur die Eigenschaften ein, die Sie im Anforderungstext ändern. Wenn Sie eine Entität aktualisieren, indem Sie alle Eigenschaften einer Entität einschließen, die Sie zuvor abgerufen haben, aktualisiert der Vorgang jede Eigenschaft, auch wenn der Wert gleich ist. Dieses Update kann zu Systemereignissen führen, die Geschäftslogik auslösen, die erwartet, dass sich die Werte geändert haben. Es kann dazu führen, dass Eigenschaften in Überwachungsdaten aktualisiert werden, wenn sie sich nicht tatsächlich geändert haben.

Wenn Sie die statecode Eigenschaft aktualisieren, legen Sie immer den gewünschten statuscodeWert fest. Die Werte statecode und statuscode hängen voneinander ab. Bei einem bestimmten statecode Wert kann es mehrere gültige statuscode Werte geben. Jede statecode Spalte hat jedoch einen einzelnen DefaultStatus-Wert konfiguriert. Wenn Sie statecode aktualisieren, ohne ein statuscode anzugeben, legt das System den Standardwert für den Status fest. Wenn Sie die Überwachung für die Tabelle und die statuscode Spalte aktivieren, wird der geänderte Wert für die statuscode Spalte nicht in den Überwachungsdaten erfasst, es sei denn, Sie geben sie im Aktualisierungsvorgang an.

Hinweis

Die Definition für Attribute enthält eine RequiredLevel Eigenschaft. Wenn diese Eigenschaft auf SystemRequired festgelegt ist, können Sie diese Attribute nicht auf einen Nullwert festlegen. Weitere Informationen finden Sie unter Attributanforderungsebene.

In diesem Beispiel wird ein vorhandener Kontodatensatz mit dem accountid Wert 0000000-0000-0000-0000-0000000001 aktualisiert.

Anforderung:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-Match: *  
  
{  
    "name": "Updated Sample Account ",  
    "creditonhold": true,  
    "address1_latitude": 47.639583,  
    "description": "This is the updated description of the sample account",  
    "revenue": 6000000,  
    "accountcategorycode": 2  
}

Antwort:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Hinweis

Informationen zum Zuordnen und Aufheben der Zuordnung von Entitäten bei der Aktualisierung finden Sie unter Verwenden von Einzelwert-Navigationseigenschaften.

Aktualisieren mit zurückgegebenen Daten

Um Daten aus einer Entität abzurufen, die Sie aktualisieren, verfassen Sie Ihre PATCH Anforderung, sodass sie Daten aus dem aktualisierten Datensatz mit dem Status 200 (OK) zurückgibt. Verwenden Sie zur Erzielung dieses Ergebnisses den Anforderungsheader Prefer: return=representation.

Um zu steuern, welche Eigenschaften zurückgegeben werden, fügen Sie die $select Abfrageoption an die URL für den Entitätssatz an. Die $expand Abfrageoption wird bei Verwendung ignoriert.

In diesem Beispiel wird eine Kontoentität aktualisiert und die angeforderten Daten in der Antwort zurückgegeben.

Anforderung:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
Prefer: return=representation
If-Match: * 
  
{"name":"Updated Sample Account"}

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
Preference-Applied: return=representation  
OData-Version: 4.0  
  
{  
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",  
    "@odata.etag": "W/\"536537\"",  
    "accountid": "00000000-0000-0000-0000-000000000001",  
    "accountcategorycode": 1,  
    "description": "This is the description of the sample account",  
    "address1_latitude": 47.63958,  
    "creditonhold": false,  
    "name": "Updated Sample Account",  
    "createdon": "2016-09-28T23:14:00Z",  
    "revenue": 5000000.0000,  
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"  
}

Aktualisieren mehrerer Datensätze in einer einzelnen Anforderung

Die schnellste Möglichkeit zum Aktualisieren mehrerer Datensätze desselben Typs in einer einzigen Anforderung besteht darin, die UpdateMultiple-Aktion zu verwenden. Nicht alle Standardtabellen unterstützen diese Aktion, alle elastischen Tabellen jedoch.

Weitere Informationen:

Einen einzelnen Eigenschaftswert aktualisieren

Verwenden Sie zum Aktualisieren eines einzelnen Eigenschaftswerts eine PUT Anforderung, und fügen Sie den Eigenschaftsnamen dem URI der Entität hinzu.

Im folgenden Beispiel wird die name-Eigenschaft der vorhandenen account-Zeile auf den accountid-Wert von 00000000-0000-0000-0000-000000000001 aktualisiert.

Anforderung:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0  
  
{"value": "Updated Sample Account Name"}

Antwort:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Löschen eines einzelnen Eigenschaftswerts

Um den Wert einer einzelnen Eigenschaft zu löschen, verwenden Sie eine DELETE Anforderung mit dem Eigenschaftsnamen, der an den URI der Entität angefügt ist.

Im folgenden Beispiel wird der Wert der description-Eigenschaft einer Kontoentität, bei dem accountid auf 00000000-0000-0000-0000-000000000001 gesetzt ist, gelöscht.

Anforderung:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 204 No Content  
OData-Version: 4.0

Hinweis

Sie können diesen Ansatz nicht mit einer einzelwertigen Navigationseigenschaft verwenden, um die Verknüpfung zwischen zwei Entitäten aufzuheben. Eine alternative Methode finden Sie unter „Disassociate by using a single-valued navigation property“.

Upsert einer Tabellenzeile

Ein Upsert-Vorgang ähnelt einem Update. Es verwendet eine PATCH Anforderung und verwendet einen URI, um auf einen bestimmten Datensatz zu verweisen. Der Unterschied ist, dass der Datensatz nicht existiert, er wird erstellt. Wenn sie bereits vorhanden ist, wird sie aktualisiert.

Upsert ist nützlich, wenn Daten zwischen externen Systemen synchronisiert werden. Das externe System enthält möglicherweise keinen Verweis auf den Primärschlüssel der Dataverse-Tabelle, sodass Sie alternative Schlüssel für die Dataverse-Tabelle konfigurieren können, indem Sie Werte aus dem externen System verwenden, die den Datensatz auf beiden Systemen eindeutig identifizieren. Weitere Informationen: Alternativschlüssel für Referenzzeilen definieren

Sie können alle alternativen Schlüssel sehen, die für eine Tabelle in den Anmerkungen für den Entitätstyp im $metadata-Dienstdokument definiert sind. Weitere Informationen: Alternative Schlüssel.

Im folgenden Beispiel gibt es eine Tabelle mit dem Namen sample_thing mit einem alternativen Schlüssel, der sich auf zwei Spalten bezieht: sample_key1 und sample_key2, die beide zum Speichern ganzzahliger Werte definiert sind.

Anforderung:

PATCH [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1) HTTP/1.1
Accept: application/json 
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Content-Type: application/json

{
    "sample_name": "1:1"
}

Bei Erstellungs- oder Aktualisierungsvorgängen erhalten Sie die gleiche Antwort. Beachten Sie, dass der OData-EntityId Antwortheader die Schlüsselwerte anstelle des GUID-Primärschlüsselbezeichners für den Datensatz verwendet.

Antwort:

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.2/sample_things(sample_key1=1,sample_key2=1)

Da die Antwort identisch ist, können Sie nicht wissen, ob der Vorgang einen Create Oder Update Vorgang darstellt.

Wenn Sie wissen müssen, können Sie den Anforderungsheader Prefer: return=representation verwenden. Mithilfe dieses Headers erhalten Sie eine 201 Created Antwort, wenn ein Datensatz erstellt wird, und eine 200 OK Antwort, wenn der Datensatz aktualisiert wird. Diese Option fügt einen Retrieve Vorgang hinzu, der auswirkungen auf die Leistung hat. Wenn Sie den Anforderungsheader Prefer: return=representation verwenden, stellen Sie sicher, dass Ihre $select die minimale Datenmenge enthält, vorzugsweise nur die Primärschlüsselspalte. Weitere Informationen: Aktualisieren mit zurückgegebenen Daten und Erstellen mit zurückgegebenen Daten.

Wenn Sie alternative Schlüssel verwenden, schließen Sie die alternativen Schlüsselwerte nicht in den Textkörper der Anforderung ein.

  • Wenn ein Upsert einen UpdateWert darstellt, werden diese alternativen Schlüsselwerte ignoriert. Sie können alternative Schlüsselwerte nicht aktualisieren, während Sie sie verwenden, um den Datensatz zu identifizieren.
  • Wenn ein Upsert einen Create darstellt, werden die Schlüsselwerte in der URL für den Datensatz festgelegt, wenn sie nicht im Hauptteil vorhanden sind. Daher ist es nicht erforderlich, sie in den Textkörper der Anforderung aufzunehmen.

Weitere Informationen: Verwenden von Upsert zum Erstellen oder Aktualisieren eines Datensatzes

Hinweis

Beim Erstellen eines neuen Datensatzes können Sie dem System normalerweise einen GUID-Wert für den Primärschlüssel zuweisen. Diese Methode ist am besten geeignet, da das System Schlüssel generiert, die für den Index optimiert sind und diese Auswahl die Leistung verbessert. Wenn Sie jedoch einen Datensatz mit einem bestimmten Primärschlüsselwert erstellen müssen, z. B. wenn der Schlüssel-GUID-Wert von einem externen System generiert wird, bietet der upsert Vorgang hierfür eine Möglichkeit.

Verhindern Sie das Erstellen oder Aktualisieren mit Upsert

Manchmal möchten Sie einen upsert ausführen, aber einen der potenziellen Vorgänge verhindern: entweder erstellen oder aktualisieren. Sie können diese Vorgänge verhindern, indem Sie die Kopfzeilen If-Match oder If-None-Match verwenden. Für weitere Informationen siehe upsert-Vorgänge begrenzen.

Grundlegende Löschung

Ein Löschvorgang ist einfach. Verwenden Sie das DELETE Verb mit dem URI der Entität, die Sie löschen möchten. In dieser Beispielmeldung wird eine Kontoentität mit dem Primärschlüsselwert accountid gelöscht, der gleich ist 00000000-0000-0000-0000-000000000001.

Anforderung:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
Content-Type: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

Wenn die Entität vorhanden ist, erhalten Sie eine normale Antwort mit dem Status 204, um anzugeben, dass der Löschvorgang erfolgreich war. Wenn die Entität nicht gefunden wird, erhalten Sie eine Antwort mit dem Status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nach doppelten Datensätzen suchen

Weitere Informationen zum Überprüfen auf doppelte Datensätze während eines Aktualisierungsvorgangs finden Sie unter Erkennen von Duplikaten während des Aktualisierungsvorgangs mithilfe der Web-API.

Löschen mehrerer Datensätze in einer einzigen Anforderung

Verwenden Sie die DeleteMultiple Aktion, um mehrere Datensätze desselben Typs in einer einzigen Anforderung zu löschen. Standardtabellen unterstützen diese DeleteMultiple Aktion nicht, aber alle elastischen Tabellen tun dies.

Hinweis

Verwenden Sie für Standardtabellen die Aktion "BulkDelete". Diese Aktion ermöglicht das asynchrone Löschen von Datensätzen, die einer Abfrage entsprechen. Weitere Informationen finden Sie unter "Massenlöschen von Daten".

Weitere Informationen:

Aktualisieren und Löschen von Dokumenten in Speicherpartitionen

Wenn Sie in Partitionen gespeicherte elastische Tabellendaten aktualisieren oder löschen, geben Sie den Partitionsschlüssel an, wenn Sie auf diese Daten zugreifen.

Weitere Informationen: Auswählen eines PartitionId-Werts

Siehe auch

Beispiel grundlegender Web-API-Operationen (C#)
Beispiel grundlegender Web API-Operationen (clientseitiges JavaScript)
Ausführen von Vorgängen mithilfe der Web-API
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Erstellen einer Tabellenzeile mithilfe der Web-API
Abrufen einer Tabellenzeile über die Web-API
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die Web-API
Web-API-Funktionen verwenden
Nutzen von Web-API-Aktionen
Ausführen von Batchvorgängen mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit der Web-API
Bedingte Vorgänge mithilfe der Web-API ausführen

  • Last updated on