Aktualisieren und Löschen von Tabellenzeilen über die Web-API

  • Artikel

Die Operationen, um Daten zu ändern, sind ein Kernteil der Web API. Zusätzlich zum einfachen Aktualisieren und Löschen können Sie Vorgänge auf einzelnen Tabellenspalten (Entity-Attributen) durchführen und Upsert-Anfragen zusammenstellen, die Daten entweder aktualisieren oder einfügen, je nachdem, ob sie vorhanden sind.

Grundlegende Aktualisierung

Aktualisierungsoperationen verwenden das HTTP PATCH-Verb. Übergeben Sie ein JSON-Objekt, das die Eigenschaften enthält, die Sie auf den URI aktualisieren möchten, der den Datensatz darstellt. Eine Antwort mit einem Status von 204 No Content wird zurückgebracht, wenn die Aktualisierung erfolgreich ist.

Der If-Match: *-Header stellt sicher, dass Sie keinen neuen Datensatz erstellen, indem Sie versehentlich einen Upsert-Vorgang ausführen. Weitere Informationen: Verhindern das Erstellen von Upsert.

Wichtig

Wenn Sie eine Entität aktualisieren, schließen Sie im Anfragebody nur die Eigenschaften ein, die Sie ändern. Wenn Sie die Eigenschaften einer Entität einfach aktualisieren, die Sie vorher abgerufen hatten, und das JSON in Ihrer Anfrage einschließen, aktualisieren Sie damit jede Eigenschaft, obwohl der Wert derselbe ist. Dies kann Systemereignisse verursachen, die Geschäftslogik starten können, da angenommen wird, dass die Werte geändert haben. Dieses kann bewirken, dass Eigenschaften so aussehen, als seien sie beim Daten-Bearbeiten aktualisiert worden, wenn tatsächlich sie sich nicht wirklich geändert haben.

Wenn Sie die Eigenschaft statecode aktualisieren, ist es wichtig, dass Sie immer den gewünschten statuscode festlegen. statecode und statuscode haben abhängige Werte. Es kann mehrere gültige statuscode-Werte für einen bestimmten statecode-Wert geben, aber für jede statecode-Spalte ist ein einziger DefaultStatus-Wert konfiguriert. Wenn Sie statecode aktualisieren, ohne einen statuscode anzugeben, wird der Standardstatuswert 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, er wird im Aktualisierungsvorgang angegeben.

Hinweis

Die Definition für Attribute enthält eine RequiredLevel-Eigenschaft. Falls das auf SystemRequired festgelegt ist, können Sie dieser Attribute auf einen NULL-Wert nicht festlegen. Weitere Informationen: Attributerforderlichkeitsstufe

Dieses Beispiel aktualisiert einen vorhandenen Firmendatensatz mit dem accountid-Wert von 00000000-0000-0000-0000-000000000001.

Anforderung:

PATCH [Organization URI]/api/data/v9.0/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

Weitere Informationen zum Zuordnen und Trennen von Entitäten bei Aktualisierung finden Sie unter Verwenden von einzelwertigen Navigationseigenschaften.

Aktualisieren mit den zurückgegebenen Daten

Um Daten von einer Entität zu erhalten, die Sie aktualisieren, können Sie die PATCH-Anfrage so verfassen, dass die Daten des erstellten Datensatzes mit dem Status 200 (OK) zurückgegeben werden. Um dieses Ergebnis zu erzielen, müssen Sie den Prefer: return=representation-Anforderungsheader verwenden.

Um die zurückgegebenen Eigenschaften zu steuern, hängen Sie die $select-Abfrageoption für die URL im Entitätssatz an. Wenn sie verwendet wird, wird die $expand Abfrageoption ignoriert.

In diesem Beispiel wird eine Firmaenentität aktualisiert und gibt die angeforderten Daten in der Antwort zurück.

Anforderung:

PATCH [Organization URI]/api/data/v9.0/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.0/$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 Sie mehrere Datensätze in einer einzigen Anfrage

Der schnellste Weg, mehrere Datensätze desselben Typs in einer einzigen Anfrage zu aktualisieren, ist die Verwendung der UpdateMultiple-Aktion. Zum Zeitpunkt des Verfassens dieses Artikels die UpdateMultiple-Aktion. Nicht alle Standardtabellen unterstützen diese Aktion, alle elastischen Tabellen jedoch.

Weitere Informationen:

Aktualisieren Sie einen einzelnen Eigenschaftswert

Wenn Sie nur einen einzelnen Eigenschaftswert aktualisieren möchten, verwenden Sie eine PUT-Anfrage, bei der der Eigenschaftsname an den Uri der Entität angefügt wird.

Das folgende Beispiel aktualisiert die name-Eigenschaft einer vorhandenen account-Zeile mit dem accountid-Wert von 00000000-0000-0000-0000-000000000001.

Anforderung:

PUT [Organization URI]/api/data/v9.0/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 Sie einen einzelnen Eigenschaftswert

Wenn Sie den Wert einer einzelnen Eigenschaft löschen möchten, verwenden Sie eine DELETE-Anfrage, bei der der Eigenschaftsname an den Uri der Entität angefügt wird.

Das folgende Beispiel löscht den Wert der description-Eigenschaft einer Firmenentität mit dem accountid-Wert von 00000000-0000-0000-0000-000000000001.

Anforderung:

DELETE [Organization URI]/api/data/v9.0/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

Eine upsert Operation ist ähnlich wie eine Aktualisierung. Sie verwendet eine PATCH-Anfrage und verwendet einen URI, um sich auf einen spezifischen Datensatz zu beziehen. Der Unterschied ist, dass der Datensatz nicht nicht existiert, er wird erstellt. Wenn er bereits existiert, wird er aktualisiert.

Upsert ist wertvoll, wenn Daten zwischen externen Systemen synchronisiert werden. Das externe System darf keinen Verweis auf den Primärschlüssel der Dataverse-Tabelle enthalten, sodass Sie alternative Schlüssel für die Dataverse- Tabelle mit 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 des $metadata-Dienstdokuments definiert sind. Weitere Informationen: Alternativschlüssel.

Im folgenden Beispiel gibt es eine Tabelle mit dem Namen sample_thing , die über einen Alternativschlüssel verfügt, der auf zwei Spalten verweist: sample_key1 und sample_key2, die beide definiert sind ganzzahlige Werte zu speichern.

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 beide Erstellungs- und Aktualisierungsvorgänge erhalten Sie die gleiche Antwort. Beachten Sie, wie der OData-EntityId-Antwortheader die Schlüsselwerte anstelle der GUID-Primärschlüsselkennung 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 dieselbe ist, können Sie nicht wissen, ob es sich beim Vorgang um einen Create oder Update Vorgang handelte.

Wenn Sie das wissen müssen, können Sie den Prefer: return=representation-Anforderungsheader verwenden. Mit diesem Header erhalten Sie eine 201 Created Antwort, wenn ein Datensatz erstellt wird, und eine 200 OK Antwort, wenn der Datensatz aktualisiert wurde. Diese Option fügt einen Retrieve Vorgang hinzu, der sich auf die Leistung auswirkt. Wenn Sie den Prefer: return=representation-Anforderungsheader verwenden, stellen Sie sicher, dass Ihre $select die minimale Datenmenge enthält, vorzugsweise nur die Primärschlüsselspalte. Mehr Informationen: Mit den zurückgegebenen Daten aktualisieren und Mit zurückgegebenen Daten erstellen.

Wenn Sie Alternativschlüssel verwenden, sollten Sie die Alternativschlüssel-Werte nicht in den Hauptteil der Anfrage aufnehmen.

  • Wenn ein Upsert ein Update darstellt, werden diese Alternativschlüsselwerte ignoriert. Sie können Alternativschlüsselwerte nicht aktualisieren, während Sie sie zur Identifizierung des Datensatzes verwenden.
  • 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 Hauptteil der Anfrage aufzunehmen.

Weitere Informationen: Upsert verwenden, um einen Datensatz zu erstellen oder zu aktualisieren

Hinweis

Beim Erstellen eines neuen Datensatzes lassen Sie vom System normalerweise 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 Vorgang upsert eine Möglichkeit, dies zu tun.

Verhindern Sie das Erstellen oder Aktualisieren mit upsert

Jedoch gibt es manchmal Situationen, in denen Sie ein upsert ausführen möchten, aber Sie möchten eine der potenziellen Vorgänge verhindern: entweder Erstellen oder Update. Sie können dies mit den Headern If-Match oder If-None-Match tun. Für weitere Informationen siehe upsert-Vorgänge begrenzen.

Grundlegende Löschung

Ein Löschungsvorgang ist sehr direkt. Verwenden Sie das DELETE-Verb mit dem URI der Entität, die Sie löschen möchten. Diese Beispielmitteilung löscht eine Firmenentität mit dem accountid-Primärschlüsselwert gleich 00000000-0000-0000-0000-000000000001.

Anforderung:

DELETE [Organization URI]/api/data/v9.0/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 existiert, erhalten Sie eine normale Antwort mit Status 204, um anzuzeigen, dass die Löschung erfolgreich war. Wenn die Entität nicht gefunden wird, erhalten Sie eine Antwort mit Status 404.

HTTP/1.1 204 No Content  
OData-Version: 4.0

Nach doppelten Datensätzen suchen

Weitere Informationen zur Überprüfung von duplizierten Datensäten während einem Aktualisierungsvorgang finden Sie unter Erkennen von Duplikaten beim Aktualisierungsvorgang mithilfe von WEB-API.

Löschen Sie mehrere Datensätze in einer einzigen Anfrage

Der schnellste Weg, mehrere Datensätze desselben Typs in einer einzigen Anfrage zu löschen, ist die Verwendung der DeleteMultiple-Aktion. Zum Zeitpunkt des Schreibens ist DeleteMultiple-Aktion eine Vorschaufunktion. Nicht alle Standardtabellen unterstützen diese Aktion, hingegen alle elastischen Tabellen.

Hinweis

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

Weitere Informationen:

Aktualisieren und löschen Sie Dokumente 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: Wählen eines Partitionid-Wertes

Siehe auch

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

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