Bedingte Vorgänge mithilfe der Web-API ausführen
Microsoft Dataverse stellt Unterstützung für einen Satz bedingter Vorgänge bereit, die auf dem standardmäßigen HTTP-Ressourcen-Versionsverwaltungsmechanismus basieren, der als ETags bezeichnet wird.
Das HTTP-Protokoll definiert einen Entitätstag oder kurz ausgedrückt ETag, um spezifische Versionen einer Ressource zu identifizieren. ETag sind undurchsichtige Bezeichner, deren genauen Werte von der Implementierung abhängen. ETag-Werte treten in zwei Arten auf: starke und schwache Überprüfung. Eine starke Validierung zeigt an, dass eine eindeutige Ressource, die durch eine bestimmte URI identifiziert wird, auf binärer Ebene identisch ist, wenn der entsprechende ETag-Wert unverändert bleibt. Eine schwache Überprüfung stellt nur sicher, dass die Ressourcendarstellung für denselben ETag-Wert semantisch gleichwertig ist.
Dataverse generiert eine schwache Überprüfungs-@odata.etag
-Eigenschaft für jede Entitätsinstanz, und diese Eigenschaft wird automatisch bei jedem abgerufenen Entitätsdatensatz zurückgegeben. Weitere Informationen finden Sie unter Abrufen einer Tabellenzeile über die Web-API.
Verwenden Sie die Header If-Match und If-None-Match mit ETag-Werten, um zu überprüfen, ob die aktuelle Version einer Ressource mit der zuletzt abgerufenen Version übereinstimmt, mit einer vorherigen Version übereinstimmt oder mit keiner Version übereinstimmt. Diese Vergleiche bilden die Grundlage bedingter Vorgangsunterstützung. Dataverse stellt ETags bereit, um bedingte Abrufe, optimistische Parallelität und begrenzte upsert-Vorgänge zu unterstützen.
Warnung
Der Clientcode sollte dem spezifischen Wert eines ETag keine Bedeutung geben, noch irgendeine offensichtliche Beziehung zwischen ETags außer Gleichheit und Ungleichheit. Beispielsweise wird nicht garantiert, dass ein ETag-Wert für eine aktuellere Version einer Ressource größer als der ETag-Wert für eine frühere Version ist. Außerdem kann der Algorithmus, der zum Generieren neuer ETag-Werte verwendet wird, ohne Vorankündigung zwischen Versionen eines Service geändert werden.
ETags ermöglichen es Ihnen, jedes Mal Datensatzabrufe zu optimieren, wenn Sie auf denselben Datensatz mehrere Male zugreifen. Wenn Sie zuvor einen Datensatz abgerufen haben, können Sie den ETag-Wert mit dem Header If-None-Match
übergeben, um den Abruf der Daten nur dann anzufordern, wenn sie sich seit dem letzten Abruf geändert haben. Wenn sich die Daten geändert haben, gibt die Anfrage einen HTTP-Status von 200 OK
mit den neuesten Daten im Text der Anfrage zurück. Wenn die Daten unverändert bleiben, wird der HTTP-Statuscode 304 Not Modified
zurückgegeben, um anzuzeigen, dass der Datensatz nicht geändert wurde.
Das folgende Beispiel eines Nachrichtenpaars gibt Daten für einen Kontodatensatz mit accountid
gleich 00000000-0000-0000-0000-000000000001
zurück, wenn sich die Daten seit dem letzten Abruf nicht geändert haben, als der Etag-Wert W/"468026"
Anforderung:
GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: W/"468026"
Antwort:
HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
In den folgenden Abschnitten werden Einschränkungen für die Verwendung von bedingten Abrufen beschrieben.
Überprüfen Sie mit der folgenden Web-API-Anforderung, ob für eine Tabelle optimistische Parallelität aktiviert ist. Bei Tabellen mit aktivierter optimistischer Parallelität ist die Eigenschaft EntityMetadata.IsOptimisticConcurrencyEnabled auf true
gesetzt.
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled
Der ETag kann nur erkennen, ob sich der einzelne abgerufene Datensatz geändert hat. Wenn Sie in Ihrer Abfrage $expand
verwenden, werden möglicherweise weitere Datensätze zurückgegeben und es lässt sich nicht feststellen, ob sich einer dieser Datensätze geändert hat oder nicht. Wenn die Abfrage $expand
enthält, wird 304 Not Modified
nie zurückgegeben.
Wenn der Prefer: odata.include-annotations
Header in einer GET
Anforderung enthalten ist, 304 Not Modified
wird nie zurückgegeben. Die Werte von Anmerkungen können sich auf Werte aus Bezugsdatensätzen beziehen. Diese Datensätze haben sich möglicherweise geändert und diese Änderung konnte nicht erkannt werden. Daher wäre es falsch, anzugeben, dass sich nichts geändert hat.
Ein Upsert funktioniert normalerweise so, dass es einen Datensatz erstellt, wenn dieser nicht existiert; andernfalls aktualisiert es einen vorhandenen Datensatz. Allerdings können ETags verwendet werden, um upserts weiter einzuschränken, um entweder Erstellungen oder Updates zu verhindern.
Wenn Sie Daten aktualisieren und die Möglichkeit besteht, dass der Datensatz absichtlich gelöscht wurde, möchten Sie den Datensatz wahrscheinlich nicht neu erstellen. Um dies zu verhindern, fügen Sie einen If-Match
-Header mit dem Wert *
hinzu.
Anforderung:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: *
{
"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:
Wenn der Datensatz gefunden wird, erhalten Sie ein normales Antwort mit dem Status 204 No Content
. Wenn der Datensatz nicht gefunden wird, erhalten Sie Folgendes Antwort mit dem Status 404 Not Found
.
HTTP/1.1 404 Not Found
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal
{
"error": {
"code": "",
"message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist"
}
}
Wenn Sie Daten einfügen, besteht die Möglichkeit, dass im System bereits ein Datensatz mit demselben id
Wert vorhanden ist und Sie ihn möglicherweise nicht aktualisieren möchten. Um dies zu verhindern, fügen Sie der Anfrage einen If-None-Match
-Kopf mit dem Wert "*" hinzu.
Anforderung:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: *
{
"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:
Wenn der Datensatz nicht gefunden wird, erhalten Sie ein normales Antwort mit dem Status 204 No Content
. Wenn der Datensatz gefunden wird, erhalten Sie Folgendes Antwort mit dem Status 412 Precondition Failed
.
HTTP/1.1 412 Precondition Failed
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal
{
"error":{
"code":"",
"message":"A record with matching key values already exists."
}
}
Mithilfe optimistischer Parallelität können Sie feststellen, ob ein Datensatz seit dem letzten Abruf geändert wurde. Wenn sich der Datensatz, den Sie aktualisieren oder löschen möchten, seit dem Abrufen auf dem Server geändert hat, möchten Sie den Aktualisierungs- oder Löschvorgang möglicherweise nicht abschließen. Durch Anwenden des hier gezeigten Musters können Sie diese Situation erkennen, die aktuellste Version des Datensatzes abrufen und alle erforderlichen Kriterien anwenden, um neu zu bewerten, ob der Vorgang erneut versucht werden soll.
Die folgende Löschanfrage für ein Konto mit accountid
von00000000-0000-0000-0000-000000000001
schlägt fehl, weil der ETag-Wert, der mit dem If-Match
-Header gesendet wurde, sich vom aktuellen Wert unterscheidet. Wenn der Wert übereinstimmt, wird ein 204 No Content
Status erwartet.
Anforderung:
DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
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."
}
}
Die folgende Aktualisierungsanfrage für ein Konto mit accountid
von 00000000-0000-0000-0000-000000000001
schlägt fehl, weil der ETag-Wert, der mit dem If-Match
-Header gesendet wurde, sich vom aktuellen Wert unterscheidet. Wenn der Wert übereinstimmt, wird ein 204 No Content
Status erwartet.
Anforderung:
PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
If-Match: W/"470867"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
{"name":"Updated Account Name"}
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."
}
}
Beispiel bedingter Web-API-Operationen (C#)
Beispiele bedingter Web API-Operationen (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
Abfragen von Daten mithilfe der Web-API
Erstellen einer Tabellenzeile über die Web-API
Abrufen einer Tabellenzeile über die Web-API
Aktualisieren und Löschen von Tabellenzeilen über die Web-API
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die Web-API
Nutzen von Web-API-Funktionen
Web-API-Aktionen verwenden
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
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).