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

Article
04/26/2022
4 minutes de lecture

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

Cette collection d’exemples démontre comment effectuer certaines catégories d’opérations qui sont conditionnellement basées sur la version de la ligne de table contenue sur le serveur Microsoft Dataverse et/ou actuellement gérée 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#)

L’API Web Dataverse suit les conventions du protocole OData v4.0, qui utilise des ETags pour mettre en œuvre le contrôle de version des ressources. 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 Dataverse 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 lignes du tableau varient en fonction de l’adresse de l’organisation de base et de l’ID de la ligne attribué par votre serveur Dataverse.

Exemple de données

L’exemple crée la ligne de tableau suivante avant l’exécution des sections de code principal.

Type d’entité	Propriétés attribuées par le client	Propriétés attribuées par le serveur
account	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 la bande passante du réseau et le traitement du serveur tout en conservant l’état de ligne le plus récent sur le client. Pour plus d’informations : Récupérations conditionnelles

Tenter de récupérer le compte Contoso Ltd. seulement s’il ne correspond pas à la version actuelle, identifiée par la valeur ETag initiale qui a été renvoyée lors de la création de la ligne de compte. Cette condition est représentée par l’en-tête If-None-Match.

Demande

GET https://[Organization URI]/api/data/v9.0/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/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 la ligne actuelle de la table est la plus récente, donc le serveur ne renvoie pas la ligne demandée dans le corps de la réponse.

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

Demande

PUT https://[Organization URI]/api/data/v9.0/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/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 de lignes de table, la réponse inclut un en-tête ETag qui identifie la version actuelle.

Demande

GET https://[Organization URI]/api/data/v9.0/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/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
ETag: W/"628460"  
{  
   "@odata.context":"https://[Organization URI]/api/data/v9.0/$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": "https://[Organization URI]/api/data/v9.0/$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 telles opérations consiste à mettre en œuvre une approche de concurrence optimiste pour le traitement des lignes dans un environnement multi-utilisateurs. 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 la ligne de compte a été mise à jour dans la section précédente, par conséquent, sa version a été mise à jour sur le serveur.

Demande

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

 PATCH https://[Organization URI]/api/data/v9.0/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/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'.

Réessayez une mise à jour, mais utilisez à la place la valeur ETag actuelle obtenue à partir de la récupération de la dernière ligne dans la section précédente.

Demande

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

Response

 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

 GET https://[Organization URI]/api/data/v9.0/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/1.1 200 OK  
 Content-Type: application/json; odata.metadata=minimal  
 ETag: W/"628461"  
 OData-Version: 4.0  
 {  
   "@odata.context":"https://[Organization URI]/api/data/v9.0/$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": "https://[Organization URI]/api/data/v9.0/$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, voir : 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 cette ligne de compte existe toujours sur le serveur (sauf si elle a été supprimée simultanément par un autre utilisateur ou processus).

Demande

 PATCH https://[Organization URI]/api/data/v9.0/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/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 la ligne existe sur le serveur.

Demande

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

Response

 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 ETag renvoyée a changé pour refléter la nouvelle version mise à jour de la ligne de compte.

Demande

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

Response

 HTTP/1.1 200 OK  
 Content-Type: application/json; odata.metadata=minimal  
 ETag: W/"628463"  
 OData-Version: 4.0  
 {  
   "@odata.context":"https://[Organization URI]/api/data/v9.0/$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": "https://[Organization URI]/api/data/v9.0/$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

 DELETE https://[Organization URI]/api/data/v9.0/accounts(14e151db-9b4f-e611-80e0-00155da84c08) HTTP/1.1  
 OData-MaxVersion: 4.0  
 OData-Version: 4.0  
 Accept: application/json

Réponse

 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 cette ligne de table vient d’être supprimée. Cependant, si cet en-tête If-Match était absent, l’opération d’upsert de base résultante devrait réussir à créer une ligne.

Demande

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

Response

 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’est pas nécessaire de nettoyer les exemples de données car la ligne de compte a déjà été supprimée à l’étape 4.

Voir aussi

Utilisation de l’API web Dataverse
Effectuer les opérations conditionnelles à l’aide de l’API Web
Exemple d’opérations conditionnelles de l’API Web (C#)

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é).

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

Commentaires