Partager via


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

 

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

Exemple d'opérations conditionnelles de l'API Web (C#)
Exemple d'opérations conditionnelles de l'API Web (Javascript côté client)
Effectuer des opérations à l'aide de l'API Web
Composer des demandes HTTP et gérer les erreurs
Interroger les données à l'aide de l'API Web
Créer une entité à l'aide de l'API Web
Récupérer une entité à l'aide de l'API Web
Mettre à jour et supprimer des entités à l'aide de l'API Web
Associer et dissocier les entités à l'aide de l'API Web
Utiliser des fonctions API Web
Utiliser des actions API Web
Exécuter des opérations par lots à l'aide de l'API Web
Emprunter l'identité d'un autre utilisateur à l'aide de l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright