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

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. Une validation forte indique qu’une ressource unique, identifiée par un URI spécifique, est 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 et If-None-Match avec des valeurs ETag pour vérifier si la version actuelle d’une ressource correspond à la dernière version récupérée, 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.

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 que les données soient récupérées uniquement si elles ont changé depuis la dernière fois qu’elles ont été récupérées. Si les données ont changé, la requête renvoie un statut HTTP de 200 OK avec les dernières données dans le corps de la requête. Si les données ne sont pas modifiées, le code d’état HTTP 304 Not Modified est renvoyé pour indiquer que l’enregistrement n’a pas été modifié.

La paire de messages d’exemple suivante renvoie des données pour un enregistrement de compte avec le accountid égal à 00000000-0000-0000-0000-000000000001 lorsque les données n’ont pas changé depuis leur dernière récupération lorsque la valeur Etag était W/"468026"

Demande :

GET [Organization URI]/api/data/v9.2/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 une table a une concurrence optimiste activée à l’aide de la requête API Web suivante. Les tables pour lesquelles la concurrence optimiste est activée ont la propriété EntityMetadata.IsOptimisticConcurrencyEnabled définie sur true.

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

La requête ne doit pas inclure $expand

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

La requête ne doit pas inclure d’annotations

Lorsque l’en-tête est inclus dans une requête, il n’est jamais renvoyé. Prefer: odata.include-annotations GET 304 Not Modified Les valeurs des annotations peuvent faire référence aux valeurs d’enregistrements associés. Ces enregistrements ont peut-être changé et ce changement n’a pas pu être détecté, il serait donc incorrect d’indiquer que rien n’a changé.

Limiter les opérations upsert

Un upsert fonctionne généralement en créant un enregistrement s’il n’existe pas ; sinon, il met à jour un enregistrement existant. 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 existe une possibilité que l’enregistrement ait été supprimé intentionnellement, vous ne souhaiterez pas recréer l’enregistrement. Pour éviter cela, ajoutez un en-tête If-Match à la requête avec une valeur *.

Demande :

PATCH [Organization URI]/api/data/v9.2/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’enregistrement est trouvé, vous obtenez un réponse normal avec le statut 204 No Content. Lorsque l’enregistrement n’est pas trouvé, vous obtenez le message réponse suivant 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 est possible qu’un enregistrement avec la même valeur existe déjà dans le système et que vous ne souhaitiez pas le mettre à jour. id Pour éviter cela, ajoutez un en-tête If-None-Match à la requête avec une valeur « * ».

Demande :

PATCH [Organization URI]/api/data/v9.2/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’enregistrement n’est pas trouvé, vous obtiendrez un réponse normal avec le statut 204 No Content. Lorsque l’enregistrement est trouvé, vous obtenez le réponse suivant 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 la concurrence optimiste pour détecter si un enregistrement a été modifié depuis sa dernière récupération. Si l’enregistrement que vous souhaitez mettre à jour ou supprimer a changé sur le serveur depuis que vous l’avez récupéré, vous ne souhaiterez peut-être pas terminer l’opération de mise à jour ou de suppression. En appliquant le modèle présenté ici, vous pouvez détecter cette situation, récupérer la version la plus récente de l’enregistrement et appliquer tous les critères nécessaires pour réévaluer s’il faut réessayer 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 204 No Content statut est attendu.

Demande :

DELETE [Organization URI]/api/data/v9.2/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 204 No Content statut est attendu.

Demande :

PATCH [Organization URI]/api/data/v9.2/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 des 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