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

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 :

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 contrôle de version.

Cet article explique 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 d’articles liés 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 cet article.

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ées qui sont décrites plus en détail dans la section conceptuelle associée de l’article Effectuer des opérations conditionnelles à l’aide de l’API web.

Section Code	Articles conceptuels associés
Section 0 : Créer des exemples d’enregistrements	Créer une ligne de table à l’aide de l’API web
Section 1 : GET conditionnel	Récupérations conditionnelles
Section 2 : Accès concurrentiel optimiste sur la suppression et la mise à jour	Appliquer l’accès concurrentiel optimiste Limiter les opérations upsert
Section 3 : Supprimer des exemples d’enregistrements	Suppression de base Exécuter des opérations par lots à l’aide de l’API Web

Les sections suivantes contiennent un brève explication des opérations de l’API web Dataverse effectuées, des messages HTTP correspondants et de 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 sont omis. Les URI des lignes de la table varient en fonction de l’adresse de l’organisation de base et de l’ID de la ligne attribué par votre serveur Dataverse.

Section 0 : Créer des exemples d’enregistrements

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

Demande :

POST [Organization Uri]/api/data/v9.2/accounts?$select=name,revenue,telephone1,description HTTP/1.1
Prefer: return=representation
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "name": "Contoso Ltd",
  "telephone1": "555-0000",
  "revenue": 5000000,
  "description": "Parent company of Contoso Pharmaceuticals, etc."
}

Réponse :

HTTP/1.1 201 Created
Preference-Applied: return=representation
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Sortie de la console :

Created and retrieved the initial account, shown below:
{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
  "@odata.etag": "W/\"72965013\"",
  "name": "Contoso Ltd",
  "revenue": 5000000.0,
  "telephone1": "555-0000",
  "description": "Parent company of Contoso Pharmaceuticals, etc.",
  "accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Section 1 : 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

Tentez 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 [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
```
Réponse :
```
HTTP/1.1 304 NotModified
```
Sortie de la console :
```
Account record retrieved using ETag: W/"72965013"
Expected outcome: Entity was not modified so nothing was returned.
```
La valeur de la réponse, 304 NotModified, 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 [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/telephone1 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{"value": "555-0001"}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Sortie de la console :

Modified account record retrieved using ETag: W/"72965013"

Retentez la même opération GET conditionnelle, en utilisant à nouveau 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 [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
If-None-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

Réponse :

HTTP/1.1 200 OK
ETag: W/"72965025"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Sortie de la console :

Modified account record retrieved using ETag: W/"72965013"
Notice the updated ETag value and telephone number
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965025\"",
"name": "Contoso Ltd",
"revenue": 5000000.0,
"telephone1": "555-0001",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Section 2 : 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). L’en-tête If-Match représente cette condition. 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 [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

Sortie de la console :

Attempting to delete the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not deleted using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

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 [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965013"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0002",
"revenue": 6000000
}

Réponse :

HTTP/1.1 412 PreconditionFailed
OData-Version: 4.0

{
"error": {
   "code": "0x80060882",
   "message": "The version of the existing record doesn't match the RowVersion property provided."
 }
}

Sortie de la console :

Attempting to update the account using the original ETag value
Expected Error: The version of the existing record doesn't match the RowVersion property provided.
      Account not updated using ETag 'W/"72965013"', status code: 'PreconditionFailed'.

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 [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1
If-Match: W/"72965025"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
"telephone1": "555-0003",
"revenue": 6000000
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Sortie de la console :

Attempting to update the account using the current ETag value

Account successfully updated using ETag: W/"72965025".

Confirmez la mise à jour réussie en récupérant et en sortant l’état du compte actuel en utilisant une requête GET.

Demande :

GET [Organization Uri]/api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)?$select=name,revenue,telephone1,description HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 200 OK
ETag: W/"72965035"
OData-Version: 4.0

{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Sortie de la console :

Below is the final state of the account
{
"@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#accounts(name,revenue,telephone1,description)/$entity",
"@odata.etag": "W/\"72965035\"",
"name": "Contoso Ltd",
"revenue": 6000000.0,
"telephone1": "555-0003",
"description": "Parent company of Contoso Pharmaceuticals, etc.",
"accountid": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"_transactioncurrencyid_value": "228f42f8-e646-e111-8eb7-78e7d162ced1"
}

Section 3 : Supprimer des exemples d’enregistrements

Cette section supprime simplement l’enregistrement créé dans Section 0 : Créer des exemples d’enregistrements. Il utilise une demande $batch.

Demande :

POST [Organization Uri]/api/data/v9.2/$batch HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

--batch_98e0fdc2-a298-4f42-85a8-da0536140b78
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-Length: 115

DELETE /api/data/v9.2/accounts(00aa00aa-bb11-cc22-dd33-44ee44ee44ee) HTTP/1.1


--batch_98e0fdc2-a298-4f42-85a8-da0536140b78--

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
OData-Version: 4.0


--batchresponse_7bf5a9a8-5b97-4fb0-9243-668f3113e6eb--

Sortie de la console :

Deleting created records.

Voir aussi

Utiliser 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#)
Exemple d’opérations conditionnelles de l’API Web (Javascript côté client)

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-04-02

Partager via

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

Montre ce qui suit

Section 0 : Créer des exemples d’enregistrements

Section 1 : GET conditionnel

Section 2 : Accès concurrentiel optimiste sur la suppression et la mise à jour

Section 3 : Supprimer des exemples d’enregistrements

Voir aussi

Rétroaction

Ressources additionnelles