Interroger des données à l’aide d’OData

Effectué

OData est un protocole permettant d’interroger les API RESTful. Cette leçon explore quelques façons d’effectuer des opérations CRUD avec les données Microsoft Dataverse.

Créer une ligne

La méthode HTTP POST vous permet de créer des lignes.

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

Récupérer des lignes

La méthode HTTP GET vous permet de récupérer des lignes.

L’exemple suivant récupère un compte avec l’ID 00000000-0000-0000-0000-000000000001 :

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)

D’autres méthodes sont disponibles pour interroger des données à l’aide de la syntaxe de requête OData standard. Pour en savoir plus sur ce processus, consultez Récupérer un ligne de table à l’aide de l’API web.

Mettre à jour des lignes

Selon ce que vous essayez d’accomplir, vous pouvez choisir l’une de ces deux méthodes de mise à jour des lignes :

  • Si vous effectuez une mise à jour de plusieurs valeurs d’attribut, choisissez la méthode HTTP PATCH. Les méthodes PATCH offrent une fonction upsert si vous fournissez une valeur d’ID dans le cadre de votre requête, ce qui constitue une fonctionnalité avantageuse lorsque vous synchronisez des données entre les systèmes.

  • Si vous mettez à jour une seule valeur d’attribut, choisissez la méthode HTTP PUT. Vous ne pouvez pas utiliser cette méthode avec des propriétés de navigation telles que les recherches, car cela nécessite également la suppression d’une référence.

L’exemple suivant présente la mise à jour d’une ligne de table Compte :

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

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

L’en-tête de demande return=representation vous permet de récupérer les données de la table que vous mettez à jour. Si vous souhaitez contrôler les propriétés renvoyées, vous pouvez ajouter une requête $select à votre PATCH URL. Dans l’exemple suivant, l’en-tête a été ajouté et $select a été modifié pour inclure uniquement les attributs name, creditonhold et address1.

Requête

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{"name":"Updated Sample Account"}

Réponse

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",
    "@odata.etag": "W/"536537"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2023-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

Le code suivant est un exemple de requête PUT dans laquelle le nom d’un compte est mis à jour pour une ligne donnée :

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

Supprimer des lignes

La méthode HTTP DELETE vous permet de supprimer des lignes. L’opération est simple : vous fournissez l’URI de la ligne de table à supprimer, comme illustré dans la requête suivante :

DELETE [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

Plus d’opérations

Dataverse fournit de nombreuses opérations prédéfinies que vous pouvez déclencher au moyen de requêtes d’API web. Pour un inventaire complet des fonctionnalités disponibles, consultez Effectuer des opérations à l’aide de l’API web.