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

  • Article

Microsoft Dataverse 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.

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.

Dataverse 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 ligne de table à l’aide de l’API web.

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

Utilisez les en-têtes If-Match and 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. Dataverse 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 200 OK 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 304 Not Modified 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 lorsque la valeur Etag était W/"468026"

Demande :

GET [Organization URI]/api/data/v9.0/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

Les sections suivantes décrivent les limites de l’utilisation des récupérations conditionnelles.

La table doit avoir l’accès concurrentiel optimiste activé

Vérifiez si l’accès concurrentiel optimiste est activé pour une entité à l’aide de la demande d’API Web indiquée ci-dessous. Les entités pour lesquelles l’accès concurrentiel optimiste est activé ont la propriété EntityMetadata.IsOptimisticConcurrencyEnabled définie sur true.

GET [Organization URI]/api/data/v9.0/EntityDefinitions(LogicalName='<Entity Logical Name>')?$select=IsOptimisticConcurrencyEnabled

La requête ne doit pas inclure $expand

L’Etag peut uniquement détecter si l’enregistrement unique en cours de récupération a changé. Lorsque vous utilisez $expand dans votre requête, des enregistrements supplémentaires peuvent être renvoyés et il n’est pas possible de détecter si ces enregistrements ont changé ou non. Si la requête comprend $expand, elle ne va jamais retourner 304 Not Modified.

La requête ne doit pas inclure d’annotations

Quand l’en-tête Prefer: odata.include-annotations est inclus avec une requête GET, il ne renvoie jamais 304 Not Modified. Les valeurs des annotations peuvent faire référence aux valeurs d’enregistrements associés. Ces enregistrements peuvent avoir changé, et cette modification n’a pas pu être détectée. Il serait donc incorrect d’indiquer que rien n’a changé.

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 [Organization URI]/api/data/v9.0/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"
 }  
}

É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 [Organization URI]/api/data/v9.0/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."
  }  
}

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 un 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 :

DELETE [Organization URI]/api/data/v9.0/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." 
  }  
}

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

La requête suivante de mise à jour d’un compte avec un 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 [Organization URI]/api/data/v9.0/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."
  }  
}

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 ligne de table à l’aide de l’API web
Récupérer une ligne de table à l’aide de l’API web
Mettre à jour et supprimer des lignes de table à l’aide de l’API web
Associer et dissocier des lignes de tables à 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

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).