Delen via

Voorbeeld van voorwaardelijke Web API-bewerkingen

  • Artikel

 

Gepubliceerd: januari 2017

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

Deze groep voorbeelden laat zien hoe u bewerkingen uitvoert, die voorwaardelijk zijn op basis van de versie van de entiteitsrecord die op de Dynamics 365-server en/of momenteel op de client wordt bijgehouden. Zie Voorwaardelijke bewerkingen uitvoer met de web-API voor meer informatie. Dit voorbeeld wordt geïmplementeerd als afzonderlijk project voor de volgende talen:

Voorbeeld van voorwaardelijke Web API-bewerkingen (C#)

Voorbeeld voorwaardelijke bewerkingen web-API (JavaScript op client)

De web-API van Dynamics 365 volgt de conventies van het OData v4.0-protocol, dat gebruik maakt van ETags om resourceversiebeheer uit te voeren. Voorwaardelijke bewerkingen van de web-API zijn afhankelijk van dit versiebeheermechanisme.

In dit onderwerp vindt u een uitleg van de structuur en de inhoud van de voorbeelden op een taalonafhankelijk, hoger niveau. Hierin worden de HTTP-aanvragen en -responsen uitgelegd evenals de bijbehorende programmauitvoer, indien van toepassing. In de voorbeeldonderwerpen waarnaar hierboven wordt verwezen, vindt u uitleg over taalspecifieke implementaties en gerelateerde informatie over de uitvoering van de bewerkingen die in dit onderwerp worden beschreven

Demonstreert

Dit voorbeeld is onderverdeeld in drie hoofdsecties, die in de volgende tabel worden vermeld. Elke sectie bevat een set gerelateerde web-API-bewerkingen die nader besproken worden in de bijbehorende conceptuele sectie van het onderwerp Voorwaardelijke bewerkingen uitvoer met de web-API.

Codesectie

Bijbehorende conceptuele onderwerpen

Voorwaardelijke GET

Voorwaardelijk ophalen

Optimistische gelijktijdigheid bij verwijderen en bijwerken

Optimistisch gelijktijdigheid toepassen

Upsert-bewerking aansturen

Upsert-bewerkingen beperken

De volgende secties bevatten een korte bespreking van de door de web-API van Dynamics 365 uitgevoerde bewerkingen, samen met de betreffende HTTP-berichten en bijbehorende consoleuitvoer, die hetzelfde is voor elke taalimplementatie. Omwille van de beknoptheid zijn minder relevante HTTP-headers weggelaten. De URI's van de records verschillen, afhankelijk van het adres van de basisorganisatie en de ID van de record die door uw Dynamics 365-server is toegewezen.

Voorbeeldgegevens

In het voorbeeld wordt de volgende record aangemaakt, voordat de belangrijkste codesecties worden uitgevoerd.

Entiteitstype

Door client toegewezen eigenschappen

Door server toegewezen eigenschappen

account EntityType

Naam: Contoso Ltd.
Omzet: 5000000
Telefoon: 555-0000
Beschrijving: Parent company of Contoso Pharmaceuticals, etc.

ID: 14e151db-9b4f-e611-80e0-00155da84c08
Initiële Etag: W/"628448"

Voorwaardelijke GET

In deze sectie van het programma ziet u hoe u voorwaardelijke ophaalbewerkingen uitvoert voor optimaal gebruik van de netwerkcapaciteit en verwerkingscapaciteit van de server, terwijl u toch de meest actuele recordstatus handhaaft op de client.Meer informatie:Voorwaardelijk ophalen

  1. Probeer de account Contoso Ltd. alleen op te halen als deze niet overeenkomt met de huidige versie, zoals aangegeven door de initiële Etag-waarde die werd geretourneerd toen de accountrecord werd gemaakt. Deze voorwaarde wordt vertegenwoordigd door de header If-None-Match.

    HTTP-aanvraag

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

    HTTP/1.1 304 Not Modified

    Consoleuitvoer

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

    De responswaarde 304 Not Modified geeft aan dat de huidige record de meest actuele versie is, zodat de server niet de aangevraagde record retourneert in de responshoofdtekst.

  2. Werk de account bij door de primaire eigenschap Telefoonnummer te wijzigen.

    HTTP-aanvraag

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

    HTTP/1.1 204 No Content

    Consoleuitvoer

    Account telephone number updated.

  3. Voer dezelfde voorwaardelijke GET-bewerking opnieuw uit, weer met de originele ETag-waarde. Deze keer retourneert de bewerking de gevraagde gegevens, omdat de versie op de server afwijkt van (en meer recent is dan) de versie die in de aanvraag wordt aangegeven. Net zoals elke keer dat een record wordt opgehaald, bevat de respons een ETag-koptekst die de huidige versie identificeert.

    HTTP-aanvraag

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

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

    Consoleuitvoer

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

Optimistische gelijktijdigheid bij verwijderen en bijwerken

In deze sectie van het programma ziet u hoe u voorwaardelijke bewerkingen voor verwijderen en bijwerken uitvoert. Deze bewerkingen worden meestal gebruikt om een optimistisch gelijktijdigheidsbenadering voor verwerking van records te implementeren in omgevingen met meerdere gebruikers.Meer informatie:Optimistisch gelijktijdigheid toepassen

  1. Probeer de oorspronkelijke account te verwijderen, maar alleen als deze overeenkomt met de originele versie (ETag-waarde) Deze voorwaarde wordt vertegenwoordigd door de header If-Match. Deze bewerking mislukt, omdat de accountrecord in de vorige sectie werd bijgewerkt en daardoor de versie werd bijgewerkt op de server.

    HTTP-aanvraag

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

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

    Consoleuitvoer

    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. Probeer de oorspronkelijke account bij te werken, maar alleen als deze overeenkomt met de originele versie (ETag-waarde) Ook hier wordt deze voorwaarde vertegenwoordigd door de header If-Match en de bewerking mislukt om dezelfde reden.

    HTTP-aanvraag

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

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

    Consoleuitvoer

    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. Probeer opnieuw een update uit te voeren, maar gebruik nu de huidige ETag-waarde die is verkregen met de laatste ophaalbewerking voor de record in de vorige sectie.

    HTTP-aanvraag

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

    HTTP/1.1 204 No Content

    Consoleuitvoer

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

  4. Bevestig dat de update is geslaagd door de huidige accountstatus op te halen en uit te voeren. Hiervoor wordt een basale GET-aanvraag gebruikt.

    HTTP-aanvraag

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

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

    Consoleuitvoer

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

Upsert-bewerking aansturen

In deze sectie van het programma ziet u hoe u voorwaardelijke PATCH-bewerkingen uitvoert, zodat upsert-bewerkingen uitsluitend worden uitgevoerd als update-bewerkingen of insert-bewerkingen.Meer informatie:Upsert-bewerkingen beperken

  1. Probeer zonder update de primaire eigenschappen Telefoonnummer en Omzet van deze account in te voegen. De header If-None-Match met de waarde * vertegenwoordigt deze upsert-voorwaarde. Deze bewerking mislukt, omdat deze accountrecord nog steeds bestaat op de server (tenzij hij gelijktijdig door een andere gebruiker of een ander proces werd verwijderd).

    HTTP-aanvraag

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

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

    Consoleuitvoer

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

  2. Probeer dezelfde update-bewerking uit te voeren zonder CREATE. Om dit te bereiken, wordt de voorwaardelijke header If-Match gebruikt met de waarde *. Deze bewerking slaagt, omdat de record bestaat op de server.

    HTTP-aanvraag

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

    HTTP/1.1 204 No Content

    Consoleuitvoer

    Account updated using If-Match '*'

  3. Haal de huidige accountstatus op en voer deze uit met een basale GET-aanvraag. Let erop dat de geretourneerde ETag-waarde is gewijzigd om aan te geven dat er een nieuwe, bijgewerkte versie van de accountrecord is.

    HTTP-aanvraag

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

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

    Consoleuitvoer

    {
  "@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. Verwijder de account met een basale DELETE-aanvraag.

    HTTP-aanvraag

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

    HTTP/1.1 204 No Content

    Consoleuitvoer

    Account was deleted.

  5. Probeer net als in stap 2 de account bij te werken, als deze bestaat. Opnieuw wordt deze voorwaarde weergegeven door de header If-Match met de waarde *. Deze bewerking mislukt, omdat deze record net is verwijderd. Als deze header If-Match niet aanwezig is, zou de resulterende basale upsert-bewerking erin moeten slagen om een nieuwe record aan te maken.

    HTTP-aanvraag

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

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

    Consoleuitvoer

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

Het is niet nodig om de voorbeeldgegeven op te schonen, omdat de accountrecord al in stap 4 werd verwijderd.

Zie ook

De web-API van Microsoft Dynamics 365 gebruiken
Voorwaardelijke bewerkingen uitvoer met de web-API
Voorbeeld van voorwaardelijke Web API-bewerkingen (C#)
Voorbeeld voorwaardelijke bewerkingen web-API (JavaScript op client)

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht