Effectuer les opérations conditionnelles à l'aide de l'API Web

Article
10/31/2017

Date de publication : janvier 2017

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

Microsoft Dynamics 365 fournit la prise en charge d'un ensemble d'opérations conditionnelles basées sur le mécanisme de contrôle de version de ressource HTTP standard appelé ETags.

Contenu de la rubrique

ETags

En-têtes If-Match et If-None-Match

Récupérations conditionnelles

Limiter les opérations upsert

Appliquer l'accès concurrentiel optimiste

ETags

Le protocole HTTP définit une balise d'entité, ou ETag en abrégé, pour identifier les versions spécifiques d'une ressource. Les ETags sont des identificateurs opaques dont les valeurs exactes sont dépendantes de la mise en œuvre. Les valeurs d'ETag se présentent sous deux formes : validation forte et faible. La validation forte indique qu'une ressource unique, identifiée à l'aide d'un URI spécifique, sera identique au niveau binaire si sa valeur ETag correspondante est inchangée. La validation faible garantit uniquement que la représentation d'une ressource est sémantiquement équivalente pour la même valeur de l'ETag.

Dynamics 365 génère une propriété @odata.etag à validation faible pour chaque instance d'entité, et cette propriété est automatiquement retournée à chaque enregistrement d'entité récupéré. Pour plus d'informations, voir Récupérer une entité à l'aide de l'API Web.

En-têtes If-Match et If-None-Match

Utilisez les en-têtes If-Match et If-None-Match avec des valeurs ETag pour vérifier si la version actuelle d'une ressource correspond à celle récupérée en dernier, correspond à une version précédente ou ne correspond à aucune version. Ces comparaisons forment la base de support conditionnelle d'exploitation. Dynamics 365 fournit des ETags pour prendre en charge des récupérations conditionnelles, l'accès concurrentiel optimiste et des opérations upsert limitées.

Avertissement

Un code client ne doit donner aucune signification à la valeur spécifique d'un ETag, ni à une relation apparente entre des ETags outre l'égalité ou l'inégalité. Par exemple, la valeur d'un ETag pour une version plus récente d'une ressource n'est pas garantie comme étant supérieure à la valeur de l'ETAG d'une version antérieure. En outre, l'algorithme utilisé pour générer des valeurs d'ETag peut faire l’objet de modifications sans préavis. entre les versions d'un service.

Récupérations conditionnelles

Les Etags vous permettent d'optimiser les récupérations d'enregistrement lorsque vous accédez au même enregistrement plusieurs fois. Si vous avez déjà récupéré un enregistrement, vous pouvez transmettre la valeur ETag avec l'en-tête If-None-Match pour demander les données à récupérer uniquement s'il a changé depuis la dernière récupération. Si les données ont changé, la requête renvoie un statut HTTP (OK) de 200 avec les dernières données dans le corps de la requête. Si les données n'ont pas changé, le code de statut HTTP (Not Modified) 304 est renvoyé pour indiquer que l'entité n'a pas été modifiée. L'exemple de message suivant renvoie des données pour une entité de compte avec un accountid égal à 00000000-0000-0000-0000-000000000001 lorsque les données n'ont pas changé depuis la dernière récupération.

Demande

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"

Réponse

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

Limiter les opérations upsert

Un upsert fonctionne habituellement en créant une entité si elle n'existe pas ; sinon, il met une entité existante à jour. Toutefois, les ETags peuvent être utilisés pour contraindre davantage les upserts à empêcher des créations ou à empêcher des mises à jour.

Éviter la création dans upsert

Si vous mettez à jour des données et qu'il y a une possibilité que l'entité ait été supprimée intentionnellement, vous ne voudrez pas recréer l'entité. Pour éviter cela, ajoutez un en-tête If-Match à la requête avec une valeur « * ».

Demande

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
}

Réponse
Si l'entité est détectée, vous recevrez une réponse normale avec le statut 204 (No Content). Si l'entité n'est pas détectée, vous recevrez la réponse suivante avec le statut 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>
  }
 }
}

Éviter la mise à jour dans upsert

Si vous insérez des données, il existe la possibilité qu'un enregistrement avec la même valeur id existe déjà dans le système et vous ne voudrez peut être pas le mettre à jour. Pour éviter cela, ajoutez un en-tête If-None-Match à la requête avec une valeur « * ».

Demande

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
}

Réponse
Si l'entité n'est pas détectée, vous recevrez une réponse normale avec le statut 204 (No Content). Si l'entité est détectée, vous recevrez la réponse suivante avec le statut 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>
    }
  }
}

Appliquer l'accès concurrentiel optimiste

Vous pouvez utiliser l'accès concurrentiel optimiste pour détecter si une entité a été modifiée depuis la dernière fois qu'elle a été récupérée. Si l'entité que vous voulez mettre à jour ou supprimer a été modifiée sur le serveur depuis que vous l'avez récupérée, vous ne pouvez pas effectuer la mise à jour ou supprimer l'opération. En appliquant le modèle indiqué ici vous pouvez détecter ce cas, récupérer la dernière version de l'entité, et appliquer tous les critères nécessaires pour réévaluer s'il faut retenter l'opération.

Appliquer l'accès concurrentiel optimiste sur la suppression

La requête suivante de suppression d'un compte avec accountid of00000000-0000-0000-0000-000000000001 échoue car la valeur ETag envoyée avec l'en-tête If-Match est différente de la valeur actuelle. Si la valeur correspond, un statut 204 (No Content) est attendu.

Demande

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

Réponse

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

Appliquer l'accès concurrentiel optimiste sur la mise à jour

La requête suivante de mise à jour d'un compte avec accountid de 00000000-0000-0000-0000-000000000001 échoue car la valeur ETag envoyée avec l'en-tête If-Match est différente de la valeur actuelle. Si la valeur correspond, un statut 204 (No Content) est attendu.

Demande

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

Réponse

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

Voir aussi

Microsoft Dynamics 365

Effectuer les opérations conditionnelles à l'aide de l'API Web

Contenu de la rubrique

ETags

En-têtes If-Match et If-None-Match

Récupérations conditionnelles

Limiter les opérations upsert

Éviter la création dans upsert

Éviter la mise à jour dans upsert

Appliquer l'accès concurrentiel optimiste

Appliquer l'accès concurrentiel optimiste sur la suppression

Appliquer l'accès concurrentiel optimiste sur la mise à jour

Voir aussi

Ressources supplémentaires