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

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

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.

Bedingte Abrufe

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.

Tabelle muss optimistische Gleichzeitigkeit aktiviert haben

Ü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

Die Abfrage darf $ erweitern nicht enthalten

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.

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

upsert-Vorgänge begrenzen

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.

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 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"
 }  
}  

Update im Upsert verhindern

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."
  }  
}  

Optimistische Parallelität anwenden

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.

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 ü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." 
  }  
}  

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