Bedingte Vorgänge mithilfe der Web-API ausführen

  • Artikel

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