Delen via

Voorwaardelijke bewerkingen uitvoer met de web-API

  • Artikel

 

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 biedt ondersteuning voor een reeks voorwaardelijke bewerkingen die gebruik maken van het standaardmechanisme voor HTTP-resourceversiebeheer, bekend onder de naam ETags.

In dit onderwerp

ETags

If-Match- en If-None-Match-kopteksten

Voorwaardelijk ophalen

Upsert-bewerkingen beperken

Optimistisch gelijktijdigheid toepassen

ETags

Het HTTP-protocol definieert een entity tag (entiteitcode) of ETAG, waarmee specifieke versies van een resource worden geïdentificeerd. ETags zijn ondoorzichtige identificaties waarvan de exacte waarden afhangen van de implementatie. ETag-waarden komen voor in twee vormen: sterke en zwakke validatie. Sterke validatie geeft aan dat een unieke resource, aangegeven met een specifieke URI, op het binaire niveau identiek is als de bijbehorende ETag-waarde ongewijzigd blijft. Zwakke validatie garandeert alleen dat de de resourceweergave semantisch overeenkomt bij dezelfde ETag-waarde.

Dynamics 365 genereert een zwak validerende eigenschap @odata.etag voor elk entiteitsexemplaar, en deze eigenschap wordt automatisch geretourneerd met elke opgehaalde entiteitsrecord. Zie Een entiteit ophalen met de web-API voor meer informatie.

If-Match- en If-None-Match-kopteksten

Gebruik If-Match- en If-None-Match-kopteksten met ETag-waarden om te controleren of de huidige versie van een resource overeenkomt met de laatste opgehaalde versie, overeenkomt met een willekeurige eerdere versie of niet overeenkomt met een vorige versie. Deze vergelijkingen vormen de basis voor ondersteuning voor voorwaardelijke bewerkingen. Dynamics 365 biedt ETags om voorwaardelijke retrievals, optimistische gelijktijdigheid en beperkte upsert-bewerkingen te ondersteunen.

System_CAPS_warningWaarschuwing

De clientcode mag geen betekenis toekennen aan de specifieke waarde van een ETAG, noch aan een eventuele vermoedelijke relatie tussen ETags anders dan gelijkheid of ongelijkheid. Een ETAG-waarde voor een recentere versie van een resource is niet per se groter dan de ETAG-waarde voor een eerdere versie. Ook kan het algoritme dat wordt gebruikt om nieuwe ETAG-waarden te genereren, zonder voorafgaande kennisgeving worden gewijzigd bij een nieuwe versie van een service.

Voorwaardelijk ophalen

Met ETags kunt u het ophalen van records optimaliseren, wanneer u dezelfde record meerdere keren achter elkaar opent. Als u een record al eerder hebt opgehaald, kunt u de ETag-waarde doorgeven met de If-None-Match-koptekst . Zo vraagt u om gegevens alleen op te halen als deze werden gewijzigd nadat u de record voor het laatst hebt opgehaald. Als de gegevens zijn gewijzigd, retourneert de aanvraag een HTTP-status van 200 (OK) met de meest recente gegevens in de hoofdtekst van de aanvraag. Als de gegevens niet werden gewijzigd, wordt de HTTP-statuscode 304 (Not Modified) geretourneerd om aan te geven dat de entiteit niet is gewijzigd. In het volgende voorbeeld worden in een berichtenpaar gegevens van een accountentiteit geretourneerd waarin accountid gelijk is aan 00000000-0000-0000-0000-000000000001, wanneer de gegevens niet zijn gewijzigd nadat deze voor het laatst waren opgehaald.

  • Aanvraag

    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"

  • Respons

    HTTP/1.1 304 Not Modified
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

Upsert-bewerkingen beperken

Een upsert functioneert normaal gesproken door een entiteit te maken als deze nog niet bestaat; anders werkt hij een bestaande entiteit bij. Met ETags kunnen upserts verder worden ingeperkt, door het aanmaken of bijwerken te voorkomen.

Maken voorkomen in upsert

Als u gegevens bijwerkt en er bestaat een kans dat de entiteit met opzet is verwijderd, wilt u de entiteit niet opnieuw maken. Als u dit wilt voorkomen, voegt u een If-Match-koptekst aan de aanvraag toe met een waarde van "*".

  • Aanvraag

    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
}

  • Respons
    Als de entiteit wordt gevonden, krijgt u een normale respons met de status 204 (No Content). Als de entiteit niet wordt gevonden, krijgt u de volgende respons met de 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>
  }
 }
}

Bijwerken voorkomen in upsert

Als u gegevens invoegt, is er een kans dat een record met dezelfde id-waarde al in het systeem bestaat en u deze niet wilt bijwerken. Als u dit wilt voorkomen, voegt u een If-None-Match-koptekst aan de aanvraag toe met een waarde van "*".

  • Aanvraag

    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
}

  • Respons
    Als de entiteit niet wordt gevonden, krijgt u een normale respons met de status 204 (No Content). Als de entiteit wordt gevonden, krijgt u de volgende respons met 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>
    }
  }
}

Optimistisch gelijktijdigheid toepassen

U kunt optimistische gelijktijdigheid gebruiken om te detecteren of een entiteit is gewijzigd sinds deze de laatste keer is opgehaald. Als de entiteit die u wilt bijwerken of verwijderen is gewijzigd op de server nadat u deze hebt opgehaald, wilt u mogelijk de bijwerk- of verwijderbewerking niet voltooien. Met het hier weergegeven patroon kunt u deze situatie detecteren, de meest recente versie van de entiteit ophalen en eventuele criteria toepassen om opnieuw te bekijken of de bewerking opnieuw moet worden geprobeerd.

Optimistische gelijktijdigheid toepassen op verwijderen

De volgende verwijderaanvraag voor een account met accountid of00000000-0000-0000-0000-000000000001 mislukt, omdat de waarde ETag die is verzonden met de koptekst If-Match afwijkt van de huidige waarde. Als de waarde hetzelfde was geweest, zou de status 204 (No Content) worden verwacht.

  • Aanvraag

    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

  • Respons

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

Optimistische gelijktijdigheid toepassen op bijwerken

De volgende updateaanvraag voor een account met accountid van 00000000-0000-0000-0000-000000000001 mislukt, omdat de waarde ETag die is verzonden met de koptekst If-Match afwijkt van de huidige waarde. Als de waarde hetzelfde is, wordt de status 204 (No Content) verwacht.

  • Aanvraag

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

  • Respons

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

Zie ook

Voorbeeld van voorwaardelijke Web API-bewerkingen (C#)
Voorbeeld voorwaardelijke bewerkingen web-API (JavaScript op client)
Bewerkingen uitvoeren met de web-API
HTTP-aanvragen opstellen en fouten afhandelen
Querygegevens met behulp van de web-API
Een entiteit maken met de web-API
Een entiteit ophalen met de web-API
Entiteiten bijwerken en verwijderen met de Web-API
Entiteiten koppelen en ontkoppelen met de web-API
Web-API-functies gebruiken
Web-API-acties gebruiken
Batchbewerkingen uitvoeren met de Web API
Zich als een andere gebruiker voordoen die de Web API gebruikt

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht