Exemple d'opérations conditionnelles de l'API Web

Article
03/04/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Ce groupe d'exemples explique comment effectuer des opérations qui sont basées conditionnellement sur la version de l'enregistrement d'entité contenu sur le serveur Dynamics 365 et/ou actuellement conservé par le client. Pour plus d'informations, voir Effectuer les opérations conditionnelles à l'aide de l'API Web. Cet exemple est mis en œuvre comme un projet distinct pour les langues suivantes :

Exemple d'opérations conditionnelles de l'API Web (C#)

Exemple d'opérations conditionnelles de l'API Web (Javascript côté client)

L'API Web Dynamics 365 suit les conventions du protocole OData v4.0, qui utilise ETags pour mettre en œuvre le contrôle de la version de ressource. Les opérations conditionnelles de l'API Web dépendent de ce mécanisme de gestion des versions.

Cette rubrique décrit la structure et le contenu des exemples à un niveau de langue neutre supérieur. Elle présente en détail les demandes et les réponses HTTP, et la sortie de programme associée, le cas échéant. Examinez les exemples de rubriques liées ci-dessus pour obtenir des détails de mise en œuvre spécifiques à chaque langue et des détails connexes sur la façon d'exécuter les opérations décrites dans cette rubrique.

Montre ce qui suit

Cet exemple est réparti en trois sections principales, répertoriées dans le tableau suivant. Chaque section contient un ensemble d'opérations de l'API Web associée décrites plus en détail dans la section conceptuelle associée de la rubrique Effectuer les opérations conditionnelles à l'aide de l'API Web.

Section Code	Rubriques conceptuelles associées
GET conditionnel	Récupérations conditionnelles
Accès concurrentiel optimiste sur la suppression et la mise à jour	Appliquer l'accès concurrentiel optimiste
Contrôle des opérations upsert	Limiter les opérations upsert

Les sections suivantes contiennent un bref examen des opérations de l'API Web Dynamics 365 effectuées, ainsi que les messages HTTP correspondants et la sortie de la console associée qui est la même pour chaque mise en œuvre de langue. Par souci de concision, des en-têtes HTTP moins pertinents ont été omis. Les URI des enregistrements peuvent varier de l'adresse de base de l'organisation et de l'ID d'enregistrement attribué par votre serveur Dynamics 365.

Exemple de données

L'exemple crée l'enregistrement suivant avant que les sections principales de code soient effectuées.

Type d’entité	Propriétés attribuées par le client	Propriétés attribuées par le serveur
account EntityType	Nom : Contoso Ltd. Revenu : 5000000 Téléphone : 555-0000 Description : Parent company of Contoso Pharmaceuticals, etc.	ID : 14e151db-9b4f-e611-80e0-00155da84c08 Etag initial : W/"628448"

GET conditionnel

Cette section du programme montre comment effectuer des récupérations conditionnelles afin d'optimiser le traitement de la bande passante réseau et du serveur tout en conservant l'état de l'enregistrement le plus récent sur le client.Pour plus d'informations :Récupérations conditionnelles

Essayez de récupérer le compte Contoso Ltd. uniquement s'il ne correspond pas à la version actuelle, identifié par la valeur d'origine de l'ETag qui a été renvoyée lorsque le compte a été créé. Cette condition est représentée par l'en-tête If-None-Match.

Demande HTTP
```
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
```
Réponse HTTP
```
HTTP/1.1 304 Not Modified
```
Sortie de la console
```
Instance retrieved using ETag: W/"628448"
Expected outcome: Entity was not modified so nothing was returned.
```
La valeur de la réponse, 304 Not Modified, indique que l'enregistrement actuel est le plus récent, le serveur ne renvoie donc pas l'enregistrement demandé dans le corps de réponse.

Mettez le compte à jour en modifiant sa propriété de numéro de téléphone principal.

Demande HTTP

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

Réponse HTTP

HTTP/1.1 204 No Content

Sortie de la console

Account telephone number updated.

Refaites une tentative avec la même opération GET conditionnelle, de nouveau à l'aide de la valeur ETag d'origine. Cette fois, l'opération retourne les données demandées, car la version sur le serveur est différente (et plus récente) que la version identifiée dans la demande. Comme dans toutes les récupérations d'enregistrements, la réponse inclut un en-tête ETag qui identifie la version actuelle.

Demande HTTP

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

Réponse HTTP

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

Sortie de la console

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

Accès concurrentiel optimiste sur la suppression et la mise à jour

Cette section du programme montre comment effectuer des opérations conditionnelles de suppression et de mise à jour. L'utilisation la plus courante de ces opérations consiste à mettre en œuvre une approche d'accès concurrentiel optimiste pour enregistrer le traitement dans un environnement multi-utilisateur.Pour plus d'informations :Appliquer l'accès concurrentiel optimiste

Essayez de supprimer le compte d'origine si et uniquement s'il correspond à la version d'origine (valeur de l'ETag). Cette condition est représentée par l'en-tête If-Match. Cette opération échoue, car l'enregistrement de compte a été mis à jour dans la section précédente, ce qui signifie que sa version a été mise à jour sur le serveur.

Demande HTTP

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

Réponse HTTP

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

Sortie de la console

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

Essayez de mettre à jour le compte d'origine si et uniquement s'il correspond à la valeur de l'ETag d'origine. Ici aussi, cette condition est représentée par l'en-tête If-Match et l'opération échoue pour la même raison.

Demande HTTP

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
}

Réponse HTTP

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

Sortie de la console

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

Refaites une tentative de mise à jour, mais utilisez à la place la valeur de l'ETag actuelle obtenue lors de la dernière récupération d'enregistrement dans la section précédente.

Demande HTTP

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
}

Réponse HTTP

HTTP/1.1 204 No Content

Sortie de la console

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

Confirmez la mise à jour réussie en récupérant et en sortant l'état de compte actuel. Cela utilise une demande GET de base.

Demande HTTP

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

Réponse HTTP

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

Sortie de la console

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

Contrôle des opérations upsert

Cette section du programme montre comment exécuter des opérations PATCH conditionnelles, limiter les opérations upsert à effectuer en tant qu'opérations de mise à jour uniquement ou d'insertion uniquement.Pour plus d'informations :Limiter les opérations upsert

Essayez d'insérer, sans mettre à jour, les propriétés de téléphone principal et de revenus de ce compte. L'en-tête If-None-Match avec une valeur de * représente cette condition upsert. Cette opération échoue, car l'enregistrement de compte existe toujours sur le serveur (à moins qu'il ait été supprimé simultanément par un autre utilisateur ou processus.)

Demande HTTP

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
}

Réponse HTTP

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

Sortie de la console

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

Tentative d'effectuer la même opération de mise à jour sans création. Pour y parvenir, l'en-tête If-Match conditionnel est utilisé avec une valeur de *. Cette opération réussit, car l'enregistrement existe sur le serveur.

Demande HTTP

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
}

Réponse HTTP

HTTP/1.1 204 No Content

Sortie de la console

Account updated using If-Match '*'

Récupérez et sortez l'état de compte actuel avec une demande GET de base. Notez que la valeur de l'ETag retournée a été modifiée pour refléter la nouvelle version mise à jour de l'enregistrement de compte.

Demande HTTP

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

Réponse HTTP

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

Sortie de la console

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

Supprimez le compte avec un DELETE de base.

Demande HTTP

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

Réponse HTTP

HTTP/1.1 204 No Content

Sortie de la console

Account was deleted.

Exactement comme à l'étape 2, faites une tentative pour mettre le compte à jour s'il existe. Ici aussi, cette condition est représentée par l'en-tête If-Match avec une valeur de *. Cette opération échoue, car cet enregistrement vient d'être supprimé. Toutefois, si cet en-tête If-Match était absent, l'opération upsert de base qui en résulte devrait créer un nouvel enregistrement avec succès.

Demande HTTP

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
}

Réponse HTTP

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

Sortie de la console

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

Il n'existe aucun exemple de donnée de nettoyage, car l'enregistrement de compte a déjà été supprimé à l'étape 4.

Voir aussi

Utilisez l'API Web Microsoft Dynamics 365
Effectuer les opérations conditionnelles à l'aide de l'API Web
Exemple d'opérations conditionnelles de l'API Web (C#)
Exemple d'opérations conditionnelles de l'API Web (Javascript côté client)

Microsoft Dynamics 365

Partager via

Exemple d'opérations conditionnelles de l'API Web

Montre ce qui suit

Exemple de données

GET conditionnel

Accès concurrentiel optimiste sur la suppression et la mise à jour

Contrôle des opérations upsert

Voir aussi

Ressources supplémentaires