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.
ETags
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 Überprüfung gibt an, dass eine eindeutige Ressource, die durch eine spezfische URI identifziert ist, auf binärer Ebene identisch ist, wenn ihr entsprechender ETag-Wert unverändert ist. 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.
"If-Match"- und "If-None-Match"-Kopfzeilen
Verwenden Sie If-Match und If-None-Match-Kopfzeilen mit ETag-Werten, um zu prüfen, ob die aktuelle Version einer Ressource mit der zuletzt abgerufenen Version, irgendeiner vorherigen Version 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.
Bedingte Abrufe
ETags ermöglichen es Ihnen, jedes Mal Datensatzabrufe zu optimieren, wenn Sie auf denselben Datensatz mehrere Male zugreifen. Wenn Sie vorher einen Datensatz abgerufen haben, können Sie den ETag-Wert mit dem Header If-None-Match
senden, damit Daten nur dann abgerufen werden, 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 200 OK
mit den neuesten Daten im Text der Anfrage zurück. Wenn sich die Daten nicht geändert haben, wird der HTTP-Statuscode 304 Not Modified
zurückgegeben, um anzuzeigen, dass die Entität nicht geändert wurde.
Das folgende Beispielmeldungspaar gibt Daten für eine Kontoentität mit der 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"
war
Anforderung:
GET [Organization URI]/api/data/v9.0/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.
Tabelle muss optimistische Gleichzeitigkeit aktiviert haben
Überprüfen Sie, ob für Entität die optimistische Parallelität aktiviert ist, indem Sie die unten gezeigte Web-API-Anforderung nutzen. Bei Entitäten mit aktivierter optimistischer Parallelität ist die EntityMetadata.IsOptimisticConcurrencyEnabled-Eigenschaft auf true
festgelegt.
GET [Organization URI]/api/data/v9.0/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled
Die Abfrage darf $ erweitern nicht enthalten
Das Etag kann nur feststellen, ob sich der einzelne Datensatz, der abgerufen wird, geändert hat. Wenn Sie $expand
in Ihrer Abfrage verwenden, werden möglicherweise zusätzliche Datensätze zurückgegeben, und es kann nicht festgestellt werden, ob sich einer dieser Datensätze geändert hat. Wenn die Abfrage $expand
enthält, wird 304 Not Modified
nie zurückgegeben.
Die Abfrage darf keine Anmerkungen enthalten
Wenn die Kopfzeile Prefer: odata.include-annotations
mit einer GET
-Anfrage verbunden ist, wird sie niemals 304 Not Modified
zurückgeben. Die Werte von Anmerkungen können sich auf Werte aus Bezugsdatensätzen beziehen. Diese Datensätze können sich geändert haben und diese Änderung konnte nicht erkannt werden, so dass es falsch wäre, anzugeben, dass sich nichts geändert hat.
upsert-Vorgänge begrenzen
Ein Upsert funktioniert normalerweise durch die Erstellung einer Entität, falls diese noch nicht existiert; andernfalls wird eine bestehende Entität aktualisiert. Allerdings können ETags verwendet werden, um upserts weiter einzuschränken, um entweder Erstellungen oder Updates zu verhindern.
Erstellen im Upsert verhindern
Wenn Sie Daten aktualisieren und es irgendeine Möglichkeit gibt, dass die Entität absichtlich gelöscht wurde, möchten Sie die Entität 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.0/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 die Entität nicht gefunden wird, erhalten Sie eine normale Antwort mit Status 204 No Content
. Wenn die Entität nicht gefunden wird, erhalten Sie die folgende Antwort mit 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"
}
}
Update im Upsert verhindern
Wenn Sie Daten einfügen, besteht die Möglichkeit, dass ein Datensatz mit dem gleichen Wert id
bereits im System vorhanden ist und Sie ihn 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.0/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 die Entität nicht gefunden wird, erhalten Sie eine normale Antwort mit Status 204 No Content
. Wenn die Entität gefunden wird, erhalten Sie die folgende Antwort mit 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."
}
}
Optimistische Parallelität anwenden
Sie können optimistische Gleichzeitigkeit verwenden, um zu ermitteln, ob eine Entität geändert worden ist, seit sie zuletzt abgerufen wurde. Wenn die Entität, die Sie aktualisieren oder löschen möchten, sich auf dem Server geändert hat, seit Sie sie abgerufen haben, sollten Sie nicht den Update- oder Löschvorgang abschließen. Durch das Anwenden des Musters, das hier gezeigt wird, können Sie diese Situation ermitteln, die neueste Version der Entität abrufen, und alle notwendigen Kriterien anwenden, um neu zu bewerten, ob man die Operation noch einmal versucht.
Wenden Sie optimistische Gleichzeitigkeit auf Löschung an
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 zusammengepasst hätte, wird ein Status 204 No Content
erwartet.
Anforderung:
DELETE [Organization URI]/api/data/v9.0/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."
}
}
Wenden Sie optimistische Gleichzeitigkeit auf Aktualisierung an
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 zusammengepasst hätte, wird ein Status 204 No Content
erwartet.
Anforderung:
PATCH [Organization URI]/api/data/v9.0/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."
}
}
Siehe auch
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
Datenabfrage mit 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).
Feedback
https://aka.ms/ContentUserFeedback.
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 unterFeedback senden und anzeigen für