Freigeben über

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

Vorgänge zum Ändern von Daten 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. Eine Antwort mit einem Status von 204 No Content wird zurückgegeben, wenn das Update erfolgreich ist.

Die If-Match: * Kopfzeile stellt sicher, dass Sie keinen neuen Datensatz erstellen, indem Sie versehentlich einen Upsert-Vorgang ausführen. Weitere Informationen: Erstellung bei Upsert verhindern.

Von Bedeutung

Schließen Sie beim Aktualisieren einer Entität nur die Eigenschaften ein, die Sie im Anforderungstext ändern. Durch einfaches Aktualisieren der Eigenschaften einer zuvor abgerufenen Entität und das Einfügen dieses JSON in Ihre Anforderung wird jede Eigenschaft aktualisiert, auch wenn der Wert derselbe ist. Dies kann zu Systemereignissen führen, die Geschäftslogik auslösen können, die erwartet, dass sich die Werte geändert haben. Dies kann dazu führen, dass Eigenschaften in Überwachungsdaten aktualisiert wurden, wenn sie tatsächlich nicht geändert wurden.

Wenn Sie die statecode Eigenschaft aktualisieren, ist es wichtig, immer die gewünschte statuscodeEigenschaft festzulegen. statecode und statuscode abhängige Werte aufweisen. Es kann mehrere gültige statuscode Werte für einen bestimmten statecode Wert geben, aber jede statecode Spalte hat einen einzelnen DefaultStatus-Wert konfiguriert. Wenn Sie statecode aktualisieren, ohne ein statuscode anzugeben, wird der Standardwert vom System festgelegt. Wenn die Überwachung für die Tabelle und die statuscode Spalte aktiviert ist, wird der geänderte Wert für die statuscode Spalte nicht in den Überwachungsdaten erfasst, es sei denn, sie wird im Aktualisierungsvorgang angegeben.

Hinweis

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

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 Einzelwertnavigationseigenschaften.

Aktualisieren mit zurückgegebenen Daten

Zum Abrufen von Daten aus einer Entität, die Sie aktualisieren, können Sie Ihre PATCH Anforderung erstellen, sodass Daten aus dem erstellten Datensatz mit dem Status 200 (OK) zurückgegeben werden. Um dieses Ergebnis zu erhalten, müssen Sie den Anforderungsheader Prefer: return=representation verwenden.

Um die zurückgegebenen Eigenschaften zu steuern, hängen Sie die $select-Abfrageoption für die URL im 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. Zum Zeitpunkt dieses Schreibens handelt es sich um die UpdateMultiple-Aktion. Nicht alle Standardtabellen unterstützen diese Aktion, alle elastischen Tabellen jedoch.

Weitere Informationen:

Einen einzelnen Eigenschaftswert aktualisieren

Wenn Sie nur einen einzelnen Eigenschaftswert aktualisieren möchten, verwenden Sie eine PUT Anforderung mit dem Eigenschaftsnamen, der an den URI der Entität angefügt ist.

Im folgenden Beispiel wird die name Eigenschaft einer vorhandenen account Zeile mit dem accountid Wert 0000000-0000-0000-0000-0000-000000001 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

Verwenden Sie zum Löschen des Werts einer einzelnen Eigenschaft eine DELETE Anforderung mit dem Eigenschaftsnamen, der an den URI der Entität angefügt wurde.

Im folgenden Beispiel wird der Wert der description Eigenschaft einer Kontoentität mit dem accountid Wert 0000000-0000-0000-0000-0000-000000001 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

Dies kann nicht bei einer Navigationseigenschaft mit einem einzelnen Wert verwendet werden, um zwei Entitäten zu distanzieren. Für einen alternativen Ansatz vergleichen Sie Die Zuordnung mit einer einzelwertigen Navigationseigenschaft aufheben.

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 mithilfe von Werten aus dem externen System konfigurieren können, 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"
}

Für sowohl Erstellungs- als auch Aktualisierungsvorgänge 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. Mit diesem Header 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, sollten Sie die alternativen Schlüsselwerte nicht im Textkörper der Anforderung einschließen.

  • 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

Normalerweise können Sie beim Erstellen eines neuen Datensatzes dem System einen GUID-Wert für den Primärschlüssel zuweisen. Dies ist eine bewährte Methode, da das System Schlüssel generiert, die für den Index optimiert sind und dies 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 gibt es Situationen, in denen Sie eine upsertAktion ausführen möchten, aber Sie möchten einen der potenziellen Vorgänge verhindern: entweder erstellen oder aktualisieren. Dazu können Sie die Header 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. Diese Beispielnachricht löscht eine Kontoentität mit dem Primärschlüsselwert accountid 00000000-0000-0000-0000-00000000001.

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

Die schnellste Möglichkeit zum Löschen mehrerer Datensätze desselben Typs in einer einzigen Anforderung besteht darin, die DeleteMultiple Aktion zu verwenden. Zum Zeitpunkt dieses Verfassens ist die DeleteMultiple Aktion eine Vorschaufunktion. Standardtabellen unterstützen diese Aktion nicht, aber alle elastischen Tabellen unterstützen sie.

Hinweis

Für Standardtabellen empfehlen wir die Verwendung der BulkDelete-Aktion, die das asynchrone Löschen von Datensätzen ermöglicht, die einer Abfrage entsprechen. Weitere Informationen: Massenlöschen von Daten

Weitere Informationen:

Aktualisieren und Löschen von Dokumenten in Speicherpartitionen

Wenn Sie Daten aus elastischen Tabellen, die in Partitionen gespeichert sind, aktualisieren oder löschen, geben Sie beim Zugriff auf diese Daten unbedingt den Partitionsschlüssel an.

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