Beispiel bedingter Web-API-Operationen
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:
- Beispiel bedingter Web-API-Operationen (C#)
- Beispiele bedingter Web API-Operationen (clientseitiges JavaScript)
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.
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 derIf-None-MatchKopfzeile 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/jsonAntwort:
HTTP/1.1 304 NotModifiedKonsolenausgabe:
Account record retrieved using ETag: W/"72965013" Expected outcome: Entity was not modified so nothing was returned.Der Antwortwert
304 NotModifiedzeigt 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.0Konsolenausgabe:
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/jsonAntwort:
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-MatchKopfzeile 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/jsonAntwort:
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-MatchKopfzeile 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/jsonAntwort:
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).
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für