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

Microsoft Dataverse unterstützt bedingte Vorgänge, die den standardmäßigen HTTP-Ressourcenversionsverwaltungsmechanismus verwenden, der als ETags bezeichnet wird. Verwenden Sie bedingte Vorgänge, indem Sie die Web-API verwenden, um Datensatzabrufe zu optimieren, Upsert-Vorgänge einzuschränken und optimistische Parallelität anzuwenden, um zu verhindern, dass änderungen von anderen Personen überschrieben werden.

ETags und Ressourcenversionierung

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ängen. ETag-Werte treten in zwei Varianten auf: starke und schwache Validierung. Eine starke Validierung gibt an, 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 gibt diese Eigenschaft automatisch mit jedem abgerufenen Entitätsdatensatz zurück. Weitere Informationen finden Sie unter Abrufen einer Tabellenzeile mithilfe der Web-API.

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

Verwenden Sie die Kopfzeilen 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 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 sollte weder dem spezifischen Wert eines ETags noch einer offensichtlichen Beziehung zwischen ETags außer Gleichheit oder Ungleichheit keine Bedeutung beimessen. 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

Etags helfen Ihnen, Datensatzabrufe zu optimieren, wenn Sie mehrmals auf denselben Datensatz zugreifen. Wenn Sie zuvor einen Datensatz abgerufen haben, übergeben Sie den ETag-Wert mit dem If-None-Match Header, um Daten nur anzufordern, wenn sie seit dem letzten Abrufen geändert wurden. 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, gibt die Anfrage den HTTP-Statuscode 304 Not Modified zurück, um anzugeben, dass der Datensatz nicht geändert wurde.

Das folgende Beispielnachrichtenpaar gibt Daten für einen Kontodatensatz zurück, bei dem accountid gleich 00000000-0000-0000-0000-000000000001 ist, wenn sich die Daten seit dem letzten Abrufen nicht geändert haben und der Etag-Wert lautete 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 mithilfe der folgenden Web-API-Anforderung, ob für eine Tabelle die optimistische Nebenläufigkeit aktiviert ist. Tabellen mit aktivierter optimistischer Parallelität haben die Eigenschaft EntityMetadata.IsOptimisticConcurrencyEnabled auf true festgelegt. Verwenden Sie diese URL, um den Wert abzurufen:

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

In diesem Beispiel wird der Wert aus der Kontakttabelle abgerufen:

Anforderung:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='contact')?$select=IsOptimisticConcurrencyEnabled  HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Antwort:

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(IsOptimisticConcurrencyEnabled)/$entity",
   "MetadataId": "608861bc-50a4-4c5f-a02c-21fe1943e2cf",
   "IsOptimisticConcurrencyEnabled": true
}

Die Abfrage darf keine $expand enthalten.

Das Etag kann nur erkennen, ob der einzelne Datensatz, den Sie abrufen, geändert wurde. Wenn Sie $expand in Ihrer Abfrage verwenden, geben Sie möglicherweise weitere Datensätze zurück, und es ist nicht möglich, zu erkennen, ob diese Datensätze geändert wurden. Wenn die Abfrage $expand enthält, gibt die Anforderung nie 304 Not Modified zurück.

Abfrage darf keine Anmerkungen enthalten

Wenn Sie den Prefer: odata.include-annotations-Header in eine GET-Anforderung einfügen, gibt der Server 304 Not Modified nie zurück. Die Werte von Anmerkungen können auf Werte aus verwandten Datensätzen verweisen. Diese Datensätze wurden möglicherweise geändert, und der Server kann diese Änderung nicht erkennen, daher wäre es falsch, um anzugeben, dass nichts geändert wurde.

Einschränken von Upsert-Vorgängen

Ein Upsert-Vorgang erstellt einen Datensatz, wenn er nicht vorhanden ist; andernfalls wird ein vorhandener Datensatz aktualisiert. Sie können ETags jedoch verwenden, um Upserts weiter einzuschränken, um entweder Erstellungen zu verhindern 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 möglicherweise nicht erneut erstellen. Um diese Bedingung zu verhindern, fügen Sie der Anfrage einen If-Match Header mit dem Wert von * 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 Server den Datensatz findet, erhalten Sie eine normale Antwort mit status 204 No Content. Wenn der Server den Datensatz nicht findet, 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, ist möglicherweise bereits ein Datensatz mit demselben id Wert im System vorhanden. Möglicherweise möchten Sie diesen vorhandenen Datensatz nicht aktualisieren. Um das Aktualisieren des Datensatzes 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

Verwenden Sie optimistische Nebenläufigkeit, um zu erkennen, ob ein Datensatz seit dem letzten Abrufen geändert wurde. Wenn der Datensatz, den Sie aktualisieren oder löschen möchten, seit Sie ihn abgerufen haben, auf dem Server geändert wurde, möchten Sie den Update- oder Löschvorgang möglicherweise nicht abschließen. Mithilfe des folgenden 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 mit 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 übereinstimmte, erhielten Sie einen 204 No Content Status.

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, erhalten Sie einen 204 No Content Status.

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 für bedingte Web-API-Vorgänge (PowerShell)
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

  • Zuletzt aktualisiert um