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

Article
08/25/2023

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

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": "59d88f5e-6629-ed11-9db1-0022482746b6",
  "_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": "59d88f5e-6629-ed11-9db1-0022482746b6",
  "_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

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 [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$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(59d88f5e-6629-ed11-9db1-0022482746b6)/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"

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 [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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). 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 [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6) 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(59d88f5e-6629-ed11-9db1-0022482746b6) 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(59d88f5e-6629-ed11-9db1-0022482746b6) 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(59d88f5e-6629-ed11-9db1-0022482746b6)

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 de compte actuel. Cela utilise une demande GET de base.

Demande :

GET [Organization Uri]/api/data/v9.2/accounts(59d88f5e-6629-ed11-9db1-0022482746b6)?$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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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": "59d88f5e-6629-ed11-9db1-0022482746b6",
"_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(59d88f5e-6629-ed11-9db1-0022482746b6) 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

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

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

Partage 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

Ressources supplémentaires