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

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.

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.

• 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
  

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

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