Ausführen von bedingten Vorgängen mithilfe der Web-API

Microsoft Dataverse bietet Unterstützung für eine Reihe bedingter Vorgänge, die auf dem standardmäßigen HTTP-Ressourcenversionsverwaltungsmechanismus basieren, der als ETags bezeichnet wird.

ETags

Das HTTP-Protokoll definiert ein Entity-Tag, oder ETag kurz, um bestimmte Versionen einer Ressource zu identifizieren. ETags sind undurchsichtige Bezeichner, deren genaue Werte von der Implementierung abhängig sind. ETag-Werte treten in zwei Varianten auf: starke und schwache Validierung. Eine starke Validierung weist darauf hin, dass eine eindeutige Ressource, die durch einen bestimmten URI identifiziert wird, auf binärer Ebene identisch ist, wenn der entsprechende ETag-Wert unverändert ist. Schwache Überprüfung garantiert nur, dass die Ressourcendarstellung semantisch demselben ETag-Wert entspricht.

Dataverse generiert eine schwach validierende @odata.etag Eigenschaft für jede Entitätsinstanz, und diese Eigenschaft wird automatisch mit jedem abgerufenen Entitätsdatensatz zurückgegeben. Weitere Informationen finden Sie unter Abrufen einer Tabellenzeile mithilfe der Web-API.

If-Match- und If-None-Match-Kopfzeilen

Verwenden Sie If-Match - und If-None-Match-Header mit ETag-Werten , um zu überprüfen, ob die aktuelle Version einer Ressource mit der zuletzt abgerufenen, mit einer früheren Version übereinstimmt oder keiner Version entspricht. Diese Vergleiche bilden die Grundlage der Unterstützung bedingter Operationen. Dataverse stellt ETags bereit, um bedingte Abrufe, optimistische Parallelität und begrenzte upsert-Vorgänge zu unterstützen.

Warnung

Clientcode darf weder dem spezifischen Wert eines ETags noch einer offensichtlichen Beziehung zwischen ETags über Gleichheit oder Ungleichheit hinaus Bedeutung geben. Ein ETag-Wert für eine neuere Version einer Ressource ist beispielsweise nicht garantiert größer als der ETag-Wert für eine frühere Version. Außerdem kann sich der Algorithmus, der zum Generieren neuer ETag-Werte verwendet wird, ohne vorherige Ankündigung zwischen Versionen eines Diensts ändern.

Bedingte Abfragen

Mit Etags können Sie Datensatzabrufe optimieren, wenn Sie mehrmals auf denselben Datensatz zugreifen. Wenn Sie zuvor einen Datensatz abgerufen haben, können Sie den ETag-Wert mit dem If-None-Match Header übergeben, um Daten nur abzurufen, wenn sich die Daten seit dem letzten Abrufen geändert haben. Wenn sich die Daten geändert haben, gibt die Anforderung einen HTTP-Status 200 OK mit den neuesten Daten im Textkörper der Anforderung zurück. Wenn die Daten unverändert sind, wird der HTTP-Statuscode 304 Not Modified zurückgegeben, um anzugeben, dass der Datensatz nicht geändert wurde.

Das folgende Beispielnachrichtenpaar gibt Daten für einen Kontodatensatz zurück, wenn der accountid gleich 00000000-0000-0000-0000-000000000001 ist und sich die Daten seit dem letzten Abrufen, als der Etag-Wert W/"468026" war, nicht geändert haben.

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.

Tabelle muss optimistische Gleichzeitigkeit aktiviert haben

Überprüfen Sie, ob eine Tabelle eine optimistische Parallelität mithilfe der folgenden Web-API-Anforderung aktiviert hat. Tabellen mit aktivierter optimistischer Parallelität haben die Eigenschaft EntityMetadata.IsOptimisticConcurrencyEnabled, die auf den Wert true gesetzt ist.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled

Die Abfrage darf keine $expand enthalten.

Das Etag kann nur erkennen, ob der einzelne Datensatz, der abgerufen wird, geändert wird. Wenn Sie in Ihrer Abfrage verwenden $expand , werden möglicherweise mehr Datensätze zurückgegeben, und es ist nicht möglich zu erkennen, ob diese Datensätze geändert wurden. Wenn die Abfrage enthält $expand, 304 Not Modified wird nie zurückgegeben.

Abfrage darf keine Anmerkungen enthalten

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 auf Werte aus verwandten Datensätzen verweisen. Diese Datensätze wurden möglicherweise geändert, und diese Änderung konnte nicht erkannt werden, daher wäre es falsch, um anzugeben, dass nichts geändert wurde.

Einschränken von Upsert-Vorgängen

Ein Upsert funktioniert normalerweise durch die Erstellung eines Datensatzes, falls dieser noch nicht existiert; andernfalls wird ein vorhandener Datensatz 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 die Möglichkeit besteht, dass der Datensatz absichtlich gelöscht wurde, möchten Sie den Datensatz nicht erneut erstellen. Um dies zu verhindern, fügen Sie der Anforderung eine If-Match Kopfzeile 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 eine normale Antwort mit status 204 No Content. Wenn der Datensatz nicht gefunden wird, erhalten Sie die folgende 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"
 }  
}  

Update im Upsert verhindern

Wenn Sie Daten einfügen, besteht die Möglichkeit, dass ein Datensatz mit demselben id Wert bereits im System vorhanden ist und sie möglicherweise nicht aktualisiert werden soll. Um dies zu verhindern, fügen Sie der Anforderung einen If-None-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-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 eine normale Antwort mit status 204 No Content. Wenn der Datensatz gefunden wird, erhalten Sie die folgende 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."
  }  
}  

Optimistische Parallelität anwenden

Sie können optimistische Parallelität verwenden, um zu ermitteln, ob ein Datensatz seit dem letzten Abrufen geändert wurde. Wenn sich der Datensatz, den Sie aktualisieren oder löschen möchten, seit dem Abruf 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 neueste Version des Datensatzes abrufen und alle erforderlichen Kriterien anwenden, um erneut zu bewerten, ob der Vorgang erneut versucht werden soll.

Optimistische Parallelität beim Löschen anwenden

Die folgende Löschanforderung für ein Konto bei accountid00000000-0000-0000-0000-000000000001 schlägt fehl, da der mit dem If-Match Header gesendete ETag-Wert vom aktuellen Wert abweicht. 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." 
  }  
}  

Optimistische Parallelität beim Update anwenden

Die folgende Aktualisierungsanforderung für ein Konto bei accountid von 00000000-0000-0000-0000-000000000001 schlägt fehl, da der mit dem If-Match-Header gesendete ETag-Wert 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."
  }  
}  

Siehe auch

Beispiel bedingter Web-API-Vorgänge (C#)
Beispiel bedingter Web-API-Vorgänge (clientseitiges JavaScript)
Ausführen von Vorgängen mithilfe der Web-API
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Erstellen einer Tabellenzeile mithilfe der Web-API
Abrufen einer Tabellenzeile über die Web-API
Tabellenzeilen über die Web-API aktualisieren und löschen
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die Web-API
Web-API-Funktionen verwenden
Nutzen von Web-API-Aktionen
Ausführen von Batchvorgängen mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit der Web-API