Del via

Eksempel på Web API Conditional operationer

  • Artikel

 

Udgivet: januar 2017

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

Denne gruppe af eksempler viser, hvordan du udfører handlinger, der er baseret betinget på den version af objektposten, der findes på Dynamics 365-serveren, og/eller i øjeblikket vedligeholdes af klienten. Du kan finde flere oplysninger under Udfør betingede operationer ved hjælp af web-API. Dette eksempel er implementeret som et separat projekt på følgende sprog:

Eksempel på Web API Conditional operationer (C#)

Eksempel på Web API Conditional operationer (JavaScript på klientsiden)

Dynamics 365 Web-API'en følger konventionerne i OData v4.0-protokollen, som bruger ETags til at implementere ressourceversionskontrol. Betingede Web API-operationer afhænger af denne mekanisme til versionsstyring.

Dette emne beskriver strukturen og indholdet af prøverne på et højere, sprogneutralt niveau. Det indeholder oplysninger om HTTP-anmodninger og svar, og det tilknyttede programoutput, hvis det er relevant. Gennemse de tilknyttede eksempelemner ovenfor for at få sprogspecifikke implementeringer og relaterede oplysninger om, hvordan du udfører de handlinger, der er beskrevet i dette emne.

Demonstrerer

Dette eksempel er opdelt i tre hovedsektioner, der er angivet i følgende tabel. Hver sektion indeholder et sæt relaterede Web API-handlinger, der er beskrevet mere detaljeret i den tilknyttede del af emnet Udfør betingede operationer ved hjælp af web-API .

Kodesektion

Tilknyttede emner

Betinget GET

Betingede hentninger

Optimistisk samtidighed ved sletning og opdatering

Anvend optimistisk samtidighed

Styring af upsert-handlinger

Begræns upsert-handlinger

Følgende sektioner indeholder en kort beskrivelse af udførte Dynamics 365 Web-API-handlinger sammen med de tilsvarende HTTP-meddelelser og tilknyttet konsoloutput, som er det samme for hver sprogimplementering. Af pladshensyn er mindre relevante HTTP-headere udeladt. URI'erne for posterne varierer efter den grundlæggende organisations adresse og id'et for den post, der er tildelt af din Dynamics 365-server.

Eksempeldata

Eksemplet opretter følgende post, før hovedkodesektionerne udføres.

Objekttype

Klienttilknyttede egenskaber

Servertilknyttede egenskaber

account EntityType

Navn: Contoso Ltd.
Omsætning: 5000000
Telefon: 555-0000
Beskrivelse: Parent company of Contoso Pharmaceuticals, etc.

Id: 14e151db-9b4f-e611-80e0-00155da84c08
Første Etag: W/"628448"

Betinget GET

Denne sektion af programmet viser, hvordan du kan udføre betingede hentninger for at optimere båndbredde på netværket og serverbehandlingen og stadig bevare den seneste posttilstand på klienten.Flere oplysninger:Betingede hentninger

  1. Forsøg på kun at hente firmaet Contoso Ltd., hvis det ikke svarer til den aktuelle version, der er identificeret af den oprindelige ETag-værdi, der blev returneret, da firmaposten blev oprettet. Denne betingelse repræsenteres af If-None-Match-headeren.

    HTTP-anmodning

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP-svar

    HTTP/1.1 304 Not Modified

    Konsoloutput

    Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.

    Svarværdien, 304 Not Modified, angiver, at den aktuelle post er den mest aktuelle, så serveren returnerer ikke den ønskede post i selve svaret.

  2. Opdater firmaet ved at ændre dets primære telefonnummer-egenskab.

    HTTP-anmodning

    PUT http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json
{
  "value": "555-0001"
}

    HTTP-svar

    HTTP/1.1 204 No Content

    Konsoloutput

    Account telephone number updated.

  3. Forsøg igen den samme betingede GET-handling ved hjælp af den oprindelige ETag-værdi. Denne gang returnerer handlingen de ønskede data, fordi versionen på serveren er forskellig fra (og nyere) end den version, der er identificeret i anmodningen. Som altid, når der hentes poster, indeholder svaret en ETag-header, der identificerer den aktuelle version.

    HTTP-anmodning

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP-svar

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628460"
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628460\"",
  "name":"Contoso Ltd",
  "revenue":5000000.0000,
  "telephone1":"555-0001",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Konsoloutput

    Instance retrieved using ETag: W/"628448"
{
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628460\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0001",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Optimistisk samtidighed ved sletning og opdatering

Denne sektion af programmet viser, hvordan du udfører betinget sletnings- og opdateringshandlinger. Den mest almindelige brug for sådanne handlinger består i at implementere en optimistisk samtidigheds-fremgangsmåde for at registrere behandling i et flerbrugermiljø.Flere oplysninger:Anvend optimistisk samtidighed

  1. Forsøg at slette det oprindelige firma, hvis og kun hvis det svarer til den oprindelige version (ETag-værdi). Denne betingelse repræsenteres af If-Match-headeren. Handlingen mislykkedes, fordi firmaposten blev opdateret i forrige sektion, og derfor blev dens version opdateret på serveren.

    HTTP-anmodning

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP-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.", . . .
    }
}

    Konsoloutput

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not deleted using ETag 'W/"628448"', status code: '412'.

  2. Forsøg at opdatere firmaet, hvis og kun hvis det svarer til den oprindelige ETag-værdi. Igen repræsenteres denne betingelse af If-Match-headeren, og handlingen mislykkes af samme grund.

    HTTP-anmodning

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628448"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0002",
  "revenue": 6000000
}

    HTTP-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.", . . . 
  }
}

    Konsoloutput

    Expected Error: The version of the existing record doesn't match the property provided.
        Account not updated using ETag 'W/"628448"', status code: '412'.

  3. Forsøg igen på en opdatering, men brug i stedet den aktuelle ETag-værdi fra hentningen af den sidste post i den forrige sektion.

    HTTP-anmodning

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: W/"628460"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
  "telephone1": "555-0003",
  "revenue": 6000000
}

    HTTP-svar

    HTTP/1.1 204 No Content

    Konsoloutput

    Account successfully updated using ETag: W/"628460", status code: '204'.

  4. Bekræft, at opdateringen lykkedes, ved at hente og udskrive den aktuelle firmatilstand. Der bruges en grundlæggende GET-anmodning.

    HTTP-anmodning

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP-svar

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628461"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628461\"",
  "name":"Contoso Ltd",
  "revenue":6000000.0000,
  "telephone1":"555-0003",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Konsoloutput

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628461\"",
  "name": "Contoso Ltd",
  "revenue": 6000000.0,
  "telephone1": "555-0003",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

Styring af upsert-handlinger

Denne sektion af programmet viser, hvordan du udfører betingede PATCH-handlinger ved at begrænse upsert-handlinger, så de udføres som kun-opdaterings- eller kun indsætnings-handlinger.Flere oplysninger:Begræns upsert-handlinger

  1. Forsøg at indsætte, uden at opdatere, de primære telefon- og omsætningsegenskaber for dette firma.If-None-Match-headeren med værdien * repræsenterer denne upsert-tilstand. Handlingen mislykkedes, fordi denne firmapost stadig findes på serveren (medmindre den blev slettet samtidig af en anden bruger eller proces).

    HTTP-anmodning

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-None-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0004",
  "revenue": 7500000
}

    HTTP-svar

    HTTP/1.1 412 Precondition Failed
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"A record with matching key values already exists.", . . .
  }
}

    Konsoloutput

    Expected Error: A record with matching key values already exists.
        Account not updated using ETag 'W/"628448", status code: '412'.

  2. Forsøg at udføre den samme opdateringshandling uden oprettelse. For at kunne gøre det bruges den betingede If-Match-header med værdien *. Handlingen lykkes, fordi posten findes på serveren.

    HTTP-anmodning

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0005",
  "revenue": 7500000
}

    HTTP-svar

    HTTP/1.1 204 No Content

    Konsoloutput

    Account updated using If-Match '*'

  3. Hent og output den aktuelle firmatilstand med en grundlæggende GET-anmodning. Bemærk, at den returnerede ETag-værdi er blevet ændret, så den afspejler den nye opdaterede version af firmaposten.

    HTTP-anmodning

    GET http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP-svar

    HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
ETag: W/"628463"
OData-Version: 4.0
{
  "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag":"W/\"628463\"",
  "name":"Contoso Ltd","revenue":7500000.0000,
  "telephone1":"555-0005",
  "description":"Parent company of Contoso Pharmaceuticals, etc.",
  "accountid":"14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value":"0d4ed62e-95f7-e511-80d1-00155da84c03"
}

    Konsoloutput

    {
  "@odata.context": "http://cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"628463\"",
  "name": "Contoso Ltd",
  "revenue": 7500000.0,
  "telephone1": "555-0005",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "14e151db-9b4f-e611-80e0-00155da84c08",
  "_transactioncurrencyid_value": "0d4ed62e-95f7-e511-80d1-00155da84c03"
}

  4. Slet firmaet med et grundlæggende DELETE.

    HTTP-anmodning

    DELETE http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

    HTTP-svar

    HTTP/1.1 204 No Content

    Konsoloutput

    Account was deleted.

  5. Forsøg at opdatere firmaet, hvis det findes, ligesom i trin 2. Igen er denne betingelse repræsenteret af If-Match -headeren med værdien *. Denne handling mislykkes, fordi denne post lige er blevet slettet. Men hvis denne If-Match -header havde manglet, ville den resulterende grundlæggende upsert-handling have oprettet en ny post.

    HTTP-anmodning

    PATCH http://cc_WebAPI_ServiceURI/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
{
  "telephone1": "555-0006",
  "revenue": 7500000
}

    HTTP-svar

    HTTP/1.1 404 Not Found
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
  "error":{
    "code":"","message":"account With Id = 14e151db-9b4f-e611-80e0-00155da84c08 Does Not Exist", . . .
  }
}

    Konsoloutput

    Expected Error: Account with Id = 14e151db-9b4f-e611-80e0-00155da84c08 does not exist.
Account not updated because it does not exist, status code: '404'.

Der er ingen grund til at rydde op i eksempeldata, fordi den ene firmapost allerede blev blevet slettet i trin 4.

Se også

Brug Microsoft Dynamics 365 Web API
Udfør betingede operationer ved hjælp af web-API
Eksempel på Web API Conditional operationer (C#)
Eksempel på Web API Conditional operationer (JavaScript på klientsiden)

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret