Beispiel bedingter Web-API-Operationen

Artikel
03/04/2017

Veröffentlicht: Januar 2017

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

Diese Gruppe von Beispielen zeigt, wie Vorgänge ausgeführt werden, die auf der Version des Entitätsdatensatzes basiert, die sich auf dem Dynamics 365 Server sind und/oder vom Kunden derzeit gewartet werden. Weitere Informationen finden Sie unter Bedingte Vorgänge mithilfe der Web-API ausführen. Dieses Beispiel wurde als ein separates Projekt für die folgenden Sprachen implementiert:

Beispiel bedingter Web-API-Operationen (C#)

Beispiele bedingter Web API-Operationen (clientseitiges JavaScript)

Die Dynamics 365-Web API folgt den Konventionen des Data v4.0 Protokolls, das die ETag verwendet, um die Ressourcenversionsteuerung zu implementieren. Web API-bedingte Operationen hängen von diesem Versionenmechanismus ab.

In diesem Thema werden die Struktur und der Inhalt der Beispiele für eine spätere, sprachunabhängigen Ebene behandelt. Sie erläutert die Details der HTTP-Anforderungen und die Reaktionen und die zugeordnete Programmausgabe, soweit vorhanden. Wiederholen Sie die verknüpften Beispielthemen oben, um sprachspezifische Implementierungen und verwandte Details zu erhalten und zu sehen, wie die in diesem Thema beschriebenen Methoden verwendet werde.

Demonstriert

Dieses Beispiel ist in drei allgemeine Abschnitte unterteilt, die in der folgenden Tabelle aufgeführt sind. Jeder Abschnitt enthält einen Satz verbundener Web API-Vorgänge, die im Details in den zugeordneten Begriffsabschnitten des Hilfethemas Bedingte Vorgänge mithilfe der Web-API ausführen erläutert werden.

Abschnitt Code .	Zugeordnete konzeptuelle Themen
Bedingt ABRUFEN	Bedingte Abrufe
Optimistische Parallelität beim Löschen und Aktualisieren	Optimistische Parallelität anwenden
Steuern von upsert Vorgänge	upsert-Vorgänge begrenzen

Die folgenden Abschnitte enthalten eine kurze Diskussion zu den ausgeführten Dynamics 365 Web-API-Vorgängen, sowie den entsprechenden HTTP-Nachrichten und den Ausgaben, die der Konsolen zugeordnet sind und für jede Sprache gleich sind. Der Kürze halber sind entsprechende HTTP-Kopfzeilen weggelassen worden. Die URIs der Datensätze unterscheiden sich bei der Grundorganisationsadresse und der ID des Datensatzes, der Ihnen durch Ihrem Dynamics 365-Server zugewiesen wird.

Beispieldaten

Das Beispiel erstellt den folgenden Datensatz, bevor die Hauptcodeabschnitte ausgeführt werden.

Entitätstyp	Vom Client zugewiesene Eigenschaften	Vom Server zugewiesene Eigenschaften
account EntityType	Name: Contoso Ltd. Umsatz: 5000000 Telefon: 555-0000 Beschreibung: Parent company of Contoso Pharmaceuticals, etc.	ID: 14e151db-9b4f-e611-80e0-00155da84c08 Initial Etag: W/"628448"

Bedingt ABRUFEN

Dieser Abschnitt des Programms wird veranschaulicht, wie Sie bedingte Abrufe ausführen, um die Netzwerkbandweite und die Serververarbeitung zu optimieren, während der aktuellste Datensatzstatus vom Client beibehalten wird.Weitere Informationen:Bedingte Abrufe

Versuchen Sie nur dann die Firma Contoso Ltd. abzurufen, wenn nicht der aktuellen Version entspricht, die vom eTagwert identifiziert wurde, der zurückgegeben wurde, als der Firmendatensatzes erstellt wurde. Diese Bedingung wird von der If-None-Match Kopfzeile dargestellt.

HTTP-Anforderung
```
GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
```
HTTP-Antwort
```
HTTP/1.1 304 Not Modified
```
Konsolenausgabe
```
Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.
```
Der Reaktionswert 304 Not Modified gibt an, dass der aktuelle Datensatz der aktuellste ist, damit der Server nicht den angeforderten Datensatz im Antworttext zurückgeben muss.

Aktualisieren Sie die Firma, indem Sie eine primäre Telefonnummerneigenschaft ändern.

HTTP-Anforderung

PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

HTTP-Antwort

HTTP/1.1 204 No Content

Konsolenausgabe

Account telephone number updated.

Verringern Sie denselben bedingten Abrufvorgang erneut mit dem ursprünglichen eTagwert. Diesmal gibt der Vorgang die angeforderten Daten zurück, weil die Version auf dem Server anders (und neuer ) ist als die Version, die mit der Anforderung identifiziert wurde. Wie alle Datenabrufe enthält die Antwort die eTagkopfzeile, die die aktuelle Version angibt.

HTTP-Anforderung

GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

HTTP-Antwort

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Konsolenausgabe

Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Optimistische Parallelität beim Löschen und Aktualisieren

Dieser Abschnitt des Programms veranschaulicht, wie Sie bedingte Vorgänge löschen und aktualisieren. Die häufigste Nutzung für solche Vorgänge ist die Implementierung eines optimistischen Parallelitätsansatzes für die Datensatzverarbeitung in einer Umgebung für mehrere Anwender.Weitere Informationen:Optimistische Parallelität anwenden

Versuchen Sie die ursprüngliche Firma nur dann zu löschen, wenn sie der ursprünglichen Version (ETag-Wert) entspricht. Diese Bedingung wird von der If-Match Kopfzeile dargestellt. Dieser Vorgang ist fehlerhaft, weil der Firmendatensatz im vorherigen Abschnitt aktualisiert wurde und deshalb diese Version auf dem Server aktualisiert wurde.

HTTP-Anforderung

DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

HTTP-Antwort

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . .
    }
}

Konsolenausgabe

Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

Versuchen Sie, die Firma nur dann zu aktualisieren, wenn sie der ursprünglichen Version (ETag-Wert) entspricht. Wieder wird diese Bedingung von der If-Match Kopfzeile dargestellt und der Vorgang schlägt aus dem gleichen Grund fehl.

HTTP-Anforderung

PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

HTTP-Antwort

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"The version of the existing record doesn't match the RowVersion property provided.", . . . 
  }
}

Konsolenausgabe

Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

Führen Sie erneut ein Update durch, verwenden Sie aber stattdessen den aktuellen eTagwert aus der letzten Datensatzabfrage im vorherigen Abschnitt.

HTTP-Anforderung

PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

HTTP-Antwort

HTTP/1.1 204 No Content

Konsolenausgabe

Account successfully updated using ETag: W/"628460", status code: '204'.

Bestätigen Sie das Update, indem Sie den Status der aktuellen Firma abrufen und ausgeben. Dies benötigt eine GET-Anforderung.

HTTP-Anforderung

GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

HTTP-Antwort

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Konsolenausgabe

{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Steuern von upsert Vorgänge

Dieser Abschnitt des Programms veranschaulicht, wie Sie bedingte PATCH Vorgänge ausführen und upsert Vorgänge begrenzen, um entweder einen Vorgang auszuführen, der nur aktualisiert oder nur einfügt.Weitere Informationen:upsert-Vorgänge begrenzen

Versuchen Sie primären Telefon- und Umsatzeigenschaften für diese Firma einzufügen ohne zu aktualisieren. Die If-None-Match Kopfzeile mit dem Wert von * steht für diese upsert Bedingung. Dieser Vorgang schlägt fehl, weil dieser Firmendatensatz immer noch auf dem Server vorhanden (es sei denn, er wurde gleichzeitig durch einen anderen Benutzer gelöscht).

HTTP-Anforderung

PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

HTTP-Antwort

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

Konsolenausgabe

Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

Versucht, den selben Aktualisierungsvorgang ohne Erstellung auszuführen. Um dies zu erzielen, wird die bedingte If-Match Kopfzeile mit dem Wert von *verwendet. Dieser Vorgang ist erfolgreich, da der Datensatz auf dem Server vorhanden ist.

HTTP-Anforderung

PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

HTTP-Antwort

HTTP/1.1 204 No Content

Konsolenausgabe

Account updated using If-Match '*'

Abrufen und Ausgabe des aktuellen Firmenstatus mit einer einfachen GET Anforderung. Beachten Sie, dass der zurückgegebene eTagwert sich geändert hat, um die neue, aktualisierte Version des Firmendatensatzes zu widerspiegeln.

HTTP-Anforderung

GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

HTTP-Antwort

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Konsolenausgabe

{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Löschen Sie die Firma mit einer einfachen DELETE.

HTTP-Anforderung

DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

HTTP-Antwort

HTTP/1.1 204 No Content

Konsolenausgabe

Account was deleted.

Wie in Schritt 2, versucht zu aktualisieren, wenn die Firma vorhanden ist. Wieder wird diese dem von der If-Match Kopfzeile mit dem Wert von *dargestellt. Dieser Vorgang schlägt fehl, da der entsprechende Datensatz soeben gelöscht wurde. Wenn aber diese If-Match Kopfzeile fehlte, dann sollte der daraus resultierende einfache upsert-Vorgang erfolgreich einen neuen Datensatz erstellen.

HTTP-Anforderung

PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

HTTP-Antwort

HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

Konsolenausgabe

Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

Es ist nicht notwendig, Beispieldaten zu löschen, da bereits der Firmendatensatz in Schritt 4 gelöscht wurde.

Siehe auch

Verwenden der Microsoft Dynamics 365-Web-API
Bedingte Vorgänge mithilfe der Web-API ausführen
Beispiel bedingter Web-API-Operationen (C#)
Beispiele bedingter Web API-Operationen (clientseitiges JavaScript)

Microsoft Dynamics 365

Beispiel bedingter Web-API-Operationen

Demonstriert

Beispieldaten

Bedingt ABRUFEN

Optimistische Parallelität beim Löschen und Aktualisieren

Steuern von upsert Vorgänge

Siehe auch

Zusätzliche Ressourcen