Entitäten aktualisieren und löschen mithilfe der Web API

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Die Operationen, um Daten zu ändern, sind ein Kernteil der Web API. Zusätzlich zu einer einfachen Aktualisierung und zu einer Löschung können Sie Operationen auf einzelnen Attributen durchführen und upsert-Anfragen verfassen, die entweder eine Entität aktualisieren oder einfügen abhängig davon, ob sie existiert.

Hinweis

Die Metadaten, die Entitäten definieren, werden auf andere Weise aktualisiert.Weitere Informationen:Erstellen und Aktualisieren von Entitätsdefinitionen mit der Web-API

In diesem Thema

Grundlegende Aktualisierung

Aktualisieren mit den zurückgegebenen Daten

Aktualisieren Sie einen einzelnen Eigenschaftswert

Löschen Sie einen einzelnen Eigenschaftswert

Upsert einer Entität

Grundlegende Löschung

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 die Entität darstellt. Eine Antwort mit einem Status von 204 wird zurückgebracht, wenn die Aktualisierung erfolgreich ist.

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

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 Objekt in Ihrer Anfrage einschließen, aktualisieren Sie damit jede Eigenschaft, obwohl der Wert derselbe ist. 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.

  • Anforderung

    PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "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 Zuweisen von Entitäten beim Update finden Sie unter Entitäten beim Update zuordnen.

Aktualisieren mit den zurückgegebenen Daten

Hinweis

Diese Funktion wurde mit Update für Dynamics 365 (online und lokal), Dezember 2016 hinzugefügt.

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 die return=representation-Einstellung in den Anforderungsheadern 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 cc_WebAPI_ServiceURI/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

{"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": "cc_WebAPI_ServiceURI/$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 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 Firmenentität mit demaccountid-Wert von 00000000-0000-0000-0000-000000000001.

  • Anforderung

    PUT cc_WebAPI_ServiceURI/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 demaccountid-Wert von 00000000-0000-0000-0000-000000000001.

  • Anforderung

    DELETE cc_WebAPI_ServiceURI/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 sehen Sie Entfernen Sie eine Referenz auf eine Entität.

Upsert einer Entität

Eine upsert Operation ist genau wie eine Aktualisierung. Sie verwendet eine PATCH Anfrage und verwendet einen URI, um sich auf eine spezifische Entität zu beziehen. Der Unterschied ist, dass, wenn die Entität nicht existiert, sie erstellt wird. Wenn sie bereits existiert, wird sie aktualisiert. Beim Erstellen einer neuen Entität lassen Sie vom System normalerweise einen eindeutigen Bezeichner zuweisen. Dies ist eine bewährte Methode. Wenn Sie jedoch einen Datensatz mit einem spezifischen id-Wert erstellen müssen, bietet upsert eine Operation, mit der dies möglich ist. Dieses kann in der Situation wertvoll sein, in der Sie Daten in den verschiedenen Systemen synchronisieren.

Jedoch gibt es manchmal Situationen, in denen Sie ein upsert ausführen möchten, aber Sie möchten eine der potenziellen Standardaktionen verhindern: entweder Erstellen oder Update. Sie können dies bewerkstelligen, indem Sie If-Match oder If-None-Match den Kopfzeilen hinzufügen. Weitere Informationen finden Sie unter upsert-Vorgänge begrenzen.

Grundlegende Löschung

Eine Löschungsoperation 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 Primärschlüssel accountid-Wert gleich 00000000-0000-0000-0000-000000000001.

  • Anforderung

    DELETE cc_WebAPI_ServiceURI/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

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 Entität mithilfe des Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright