Del via

Udfør betingede operationer ved hjælp af web-API

  • Artikel

 

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Microsoft Dynamics 365 understøtter et sæt betingede handlinger, der er afhængige af standardmekanismen for HTTP-ressourceversionering, der kaldes ETags.

Dette emne indeholder

ETags

If-Match- og If-None-Match-headers

Betingede hentninger

Begræns upsert-handlinger

Anvend optimistisk samtidighed

ETags

HTTP-protokollen definerer et objektmærke, eller forkortet ETag (entity tag), for at identificere bestemte versioner af en ressource. ETags er uigennemsigtige id'er, hvis nøjagtige værdier er afhængige af, om de implementeres. ETag-værdier forekommer i to varianter: stærk og svag validering. Stærk validering betyder, at en entydig ressource, der identificeres af en bestemt URI, bliver identisk på binært niveau, hvis den tilsvarende ETag-værdi er uændret. Svag validering garanterer kun, at ressourcerepræsentationen er semantisk den samme for den samme ETag-værdi.

Dynamics 365 genererer en @odata.etag-egenskab, der udfører svar validering, for hver objektforekomst, og denne egenskab returneres automatisk med alle hentede objektposter. Du kan finde flere oplysninger under Hente et objekt ved hjælp af web-API'et.

If-Match- og If-None-Match-headers

Brug If-Match- ogIf-None-Match--headers med ETag-værdier til at kontrollere, om den aktuelle version af en ressource matcher den sidst hentede, svarer til en tidligere version eller ikke svarer til en version. Disse sammenligninger danner grundlag for understøttelse af betingede handlinger. Dynamics 365 indeholder ETags for at understøtte betingede hentninger, optimistisk samtidighed og begrænsede upsert-handlinger.

System_CAPS_warningAdvarsel

Klientkoden bør ikke give mening for den specifikke værdi af et ETag eller et eventuelt synligt forhold mellem ETags ud over, om de er lig med eller ikke lig med. En ETag-værdi for en nyere version af en ressource er f.eks. ikke nødvendigvis større end ETag-værdien for en tidligere version. Desuden kan den algoritme, der bruges til at generere nye ETag-værdier, ændres uden varsel mellem versioner af en tjeneste.

Betingede hentninger

Etags giver dig mulighed at optimere hentning af poster, hver gang du åbner den samme post flere gange. Hvis du tidligere har hentet en post, kan du overføre ETag-værdien med If-None-Match-headeren for at anmode om data, der kun må hentes, hvis de er ændret, siden de sidst blev hentet. Hvis dataene er ændret, returnerer anmodningen en HTTP-status på 200 (OK) med de nyeste data i anmodningens hoveddel. Hvis dataene ikke er blevet ændret, returneres HTTP-statuskoden 304 (Not Modified) for at angive, at objektet ikke er blevet ændret. Følgende eksempelmeddelelsespar returnerer data for et kontoobjekt, hvor accountid er lig med 00000000-0000-0000-0000-000000000001, når dataene ikke er blevet ændret, siden de sidst blev hentet.

  • Anmodning

    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"

  • Svar

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

Begræns upsert-handlinger

En upsert fungerer normalt ved at oprette et objekt, hvis der findes et. Ellers opdateres et eksisterende objekt. ETags kan dog anvendes til yderligere at begrænse upserts til enten at forhindre oprettelse eller tuk at forhindre opdatering.

Undgå create i upsert

Hvis du opdaterer data, og der er mulighed for, at objektet blev slettet med vilje, vil du ikke oprette objektet igen. Hvis du vil undgå dette, skal du tilføje en If-Match-header til anmodningen med værdien "*".

  • Anmodning

    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
}

  • Svar
    Hvis objektet findes, får du et normal svar med status 204 (No Content). Når objektet ikke findes, får du følgende svar med 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>
  }
 }
}

Undgå update i upsert

Hvis du indsætter data, er der mulighed for, at en post med den samme id-værdi allerede findes i systemet, og du vil muligvis ikke opdatere den. Hvis du vil undgå dette, skal du tilføje en If-None-Match-header til anmodningen med værdien "*".

  • Anmodning

    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
}

  • Svar
    Hvis objektet ikke findes, får du et normal svar med status 204 (No Content). Når objektet findes, får du følgende svar med 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>
    }
  }
}

Anvend optimistisk samtidighed

Du kan bruge optimistisk samtidighed til at registrere, om et objekt er blevet ændret, siden det sidst blev hentet. Hvis det objekt, du vil opdatere eller slette, er ændret på serveren, siden du hentede det, ønsker du muligvis ikke at fuldføre opdateringen eller sletningen. Du kan registrere denne situation ved at anvende det mønster, der er vist her, hente den nyeste version af objektet og anvende eventuelle nødvendige kriterier for at vurdere, om du vil prøve handlingen igen.

Anvend optimistisk samtidighed ved sletning

Følgende sletteanmodning for en konto med accountid of00000000-0000-0000-0000-000000000001 mislykkes, fordi ETag-værdien , der blev sendt med If-Match-headeren, er forskellig fra den aktuelle værdi. Hvis værdien havde matchet, ville statussen 204 (No Content) være forventet.

  • Anmodning

    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

  • Svar

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

Anvend optimistisk samtidighed ved opdatering

Følgende opdateringsanmodning for en konto, hvor accountid er 00000000-0000-0000-0000-000000000001, mislykkes, fordi ETag-værdien , der blev sendt med If-Match-headeren, er forskellig fra den aktuelle værdi. Hvis værdien havde matchet, ville en 204 (No Content)-status være forventet.

  • Anmodning

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

  • Svar

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

Se også

Eksempel på Web API Conditional operationer (C#)
Eksempel på Web API Conditional operationer (JavaScript på klientsiden)
Udføre operationer ved hjælp af web-API
Skrive HTTP-anmodninger og håndtere fejl
Forespørg på data ved hjælp af Web-API'en
Oprette et objekt ved hjælp af Web-API
Hente et objekt ved hjælp af web-API'et
Opdatere og slette objekter ved hjælp af web-API'et
Tilknytte og fjerne tilknytningen af objekter ved hjælp af web-API'et
Bruge Web-API-funktioner
Brug Web API-handlinger
Udføre batchhandlinger ved hjælp af Web-API
Efterligne en anden bruger ved hjælp af Web-API'en

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret