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

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 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.

In diesem Thema

ETags

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

Bedingte Abrufe

upsert-Vorgänge begrenzen

Optimistische Parallelität anwenden

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.

Dynamics 365 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 Entität mithilfe des Web-API.

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

Verwenden Sie If-Match- undIf-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. Dynamics 365 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 (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 worden ist. Das folgende Beispielmeldungspaar gibt Daten für eine Kontoentität zurück, wobei die accountid gleich 00000000-0000-0000-0000-000000000001 ist, wenn sich die Daten nicht geändert haben, seit sie das letzte Mal abgerufen wurden.

  • Anforderung

    GET cc_WebAPI_ServiceURI/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

upsert-Vorgänge begrenzen

Ein upsert arbeitet gewöhnlich, indem es eine Entität erstellt, wenn sie nicht vorhanden ist; anderenfalls aktualisiert es eine vorhandene Entität. 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 cc_WebAPI_ServiceURI/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 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",
  "innererror": {
   "message": "account With Id = 00000000-0000-0000-0000-000000000001 Does Not Exist",
   "type": "System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
   "stacktrace": <stack trace removed for brevity>
  }
 }
}

Update im Upsert verhindern

Wenn Sie Daten einfügen, könnte es sein, dass ein Datensatz mit dem gleichen id-Wert existiert bereits im System, den Sie nicht aktualisieren wollen. Um dies zu verhindern, fügen Sie einen If-None-Match-Header mit dem Wert "*" hinzu.

  • Anforderung

    PATCH cc_WebAPI_ServiceURI/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.",
   "innererror":{
    "message":"Cannot insert duplicate key.",
    "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
    "stacktrace":<stack trace removed for brevity>
    }
  }
}

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 of00000000-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 cc_WebAPI_ServiceURI/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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

Wenden Sie optimistische Gleichzeitigkeit auf Aktualisierung an

Die folgende Updatefrage 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 204 (No Content) Status erwartet.

  • Anforderung

    PATCH cc_WebAPI_ServiceURI/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.",
    "innererror":{
      "message":"The version of the existing record doesn't match the RowVersion property provided.",
      "type":"System.ServiceModel.FaultException`1[[Microsoft.Xrm.Sdk.OrganizationServiceFault, Microsoft.Xrm.Sdk, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35]]",
"stacktrace":"  <stack trace details omitted for brevity>
    }
  }
}

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 Entität mithilfe des Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten aktualisieren und löschen mithilfe der Web API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright