Beispiel bedingter Web-API-Operationen

Artikel
08/24/2023

Diese Sammlung von Beispielen demonstriert, wie bestimmte Kategorien von Vorgängen ausgeführt werden, die bedingt auf der Version der Tabellenzeile basieren, die auf dem Microsoft Dataverse-Server enthalten ist und/oder derzeit vom Client verwaltet wird. Weitere Informationen finden Sie unter Ausführen bedingter Operationen mit der Web-API. Dieses Beispiel wurde als ein separates Projekt für die folgenden Sprachen implementiert:

Die Dataverse-Web-API folgt den Konventionen des OData v4.0-Protokolls, das ETags verwendet, um die Ressourcenversionssteuerung 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 verknüpfter Web-API-Operationen, die im zugehörigen Konzeptabschnitt des Themas Bedingte Vorgänge mithilfe der Web-API ausführen detaillierter dargestellt werden.

Abschnitt Code .	Zugeordnete konzeptuelle Themen
Abschnitt 0: Beispielaufzeichnungen erstellen	Erstellen einer Tabellenzeile über die Web-API
Abschnitt 1: Bedingungs-GET	Bedingte Abrufe
Abschnitt 2: Optimistische Parallelität beim Löschen und Aktualisieren	Optimistische Parallelität anwenden upsert-Vorgänge begrenzen
Abschnitt 3: Beispielaufzeichnungen löschen	Grundlegende Löschung Ausführen von Batchbetrieben mithilfe der Web-API

Die folgenden Abschnitte enthalten eine kurze Diskussion zu den ausgeführten Dataverse-Web-API-Vorgängen, sowie den entsprechenden HTTP-Nachrichten und den Ausgaben, die den Konsolen zugeordnet und für jede Sprache gleich sind. Der Kürze halber sind entsprechende HTTP-Kopfzeilen weggelassen worden. Die URIs der Tabellenzeilen variieren mit der Basisorganisationsadresse und der ID der Zeile, die von Ihrem Dataverse-Server zugewiesen wurde.

Abschnitt 0: Beispielaufzeichnungen erstellen

Im Beispiel wird die folgende Tabellenzeile erstellt, bevor die wesentlichen Codeabschnitte ausgeführt werden.

Anforderung:

POST [Organization Uri]/api/data/v9.2/accounts?$select=name,revenue,telephone1,description HTTP/1.1
Prefer: return=representation
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "name": "Contoso Ltd",
  "telephone1": "555-0000",
  "revenue": 5000000,
  "description": "Parent company of Contoso Pharmaceuticals, etc."
}

Antwort:

HTTP/1.1 201 Created
Preference-Applied: return=representation
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Konsolenausgabe:

Created and retrieved the initial account, shown below:
{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Abschnitt 1: Bedingungs-GET

In diesem Abschnitt des Programms wird gezeigt, wie bedingte Abrufe durchgeführt werden, um die Netzwerkbandbreite und die Serververarbeitung zu optimieren und gleichzeitig den aktuellsten Zeilenstatus auf dem Client beizubehalten. Weitere Informationen:Bedingte Abrufe.

Versuchen Sie, das Konto Contoso Ltd. nur dann abzurufen, wenn es nicht mit der aktuellen Version übereinstimmt, die durch den anfänglichen ETag-Wert identifiziert wird, der beim Erstellen der Kontozeile zurückgegeben wurde. Diese Bedingung wird von der If-None-Match Kopfzeile dargestellt.

Anforderung:
```
GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
```
Antwort:
```
HTTP/1.1 304 NotModified
```
Konsolenausgabe:
```
Account record retrieved using ETag: W/"72965013"
Expected outcome: Entity was not modified so nothing was returned.
```
Der Antwortwert 304 NotModified zeigt an, dass die aktuelle Tabellenzeile die aktuellste ist. Daher gibt der Server nicht die angeforderte Zeile im Antworttext zurück.

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

Anforderung:

PUT [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{"value": "555-0001"}

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Konsolenausgabe:

Modified account record retrieved using ETag: W/"72965013"

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 bei allen Abrufen von Tabellenzeilen enthält die Antwort einen ETag-Header, der die aktuelle Version identifiziert.

Anforderung:

GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

Antwort:

HTTP/1.1 200 OK
ETag: W/"72965025"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Konsolenausgabe:

Modified account record retrieved using ETag: W/"72965013"
Notice the updated ETag value and telephone number
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Abschnitt 2: 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 Verwendung für solche Vorgänge ist die Implementierung eines optimistischen Parallelitätsansatzes für die Zeilenverarbeitung in einer Mehrbenutzerumgebung. Weitere Informationen: Wenden Sie optimistische Parallelität an

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 schlägt fehl, weil die Kontozeile im vorherigen Abschnitt aktualisiert wurde, sodass ihre Version auf dem Server aktualisiert wurde.

Anforderung:

DELETE [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Antwort:

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

Konsolenausgabe:

Attempting to delete the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not deleted using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

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.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0002",
"revenue": 6000000
}

Antwort:

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

Konsolenausgabe:

Attempting to update the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not updated using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

Versuchen Sie erneut eine Aktualisierung, wobei Sie jedoch stattdessen den aktuellen ETag-Wert verwenden, der aus dem letzten Zeilenabruf im vorherigen Abschnitt stammt.

Anforderung:

PATCH [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1
If-Match: W/"72965025"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0003",
"revenue": 6000000
}

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)

Konsolenausgabe:

Attempting to update the account using the current ETag value

Account successfully updated using ETag: W/"72965025".

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

Anforderung:

GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Antwort:

HTTP/1.1 200 OK
ETag: W/"72965035"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Konsolenausgabe:

Below is the final state of the account
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Abschnitt 3: Beispielaufzeichnungen löschen

Dieser Abschnitt löscht einfach den in Abschnitt 0: Musterdatensätze erstellen erstellten Datensatz. Es wird eine $batch-Anfrage verwendet.

Anforderung:

POST [Organization Uri]/api/data/v9.2/$batch HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

--batch_98e0fdc2-a298-4f42-85a8-da0536140b78
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-Length: 115

DELETE /api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) HTTP/1.1


--batch_98e0fdc2-a298-4f42-85a8-da0536140b78--

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0

--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
OData-Version: 4.0


--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb--

Konsolenausgabe:

Deleting created records.

Siehe auch

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

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

Teilen über

Beispiel bedingter Web-API-Operationen

Demonstriert

Abschnitt 0: Beispielaufzeichnungen erstellen

Abschnitt 1: Bedingungs-GET

Abschnitt 2: Optimistische Parallelität beim Löschen und Aktualisieren

Abschnitt 3: Beispielaufzeichnungen löschen

Siehe auch

Zusätzliche Ressourcen