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

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.

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

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  
  

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

• Massenvorgang für Nachrichten
• Beispiel: Web API für Massenvorgänge nutzen
• Verwenden Sie UpdateMultiple mit elastischen Tabellen

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

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

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

Weitere Informationen:

• Massenvorgang für Nachrichten
• Beispielcode für elastische Tabellen
• DeleteMultiple mit elastischen Tabellen verwenden

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
Abfragen von Daten mithilfe der 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