Partager via

Récupérer une ligne de table à l’aide de l’API web

Utilisez une GET demande pour récupérer des données pour un enregistrement spécifié en tant que ressource avec un identificateur unique. Lors de la récupération d’une ligne de table (enregistrement d’entité), vous pouvez également demander des propriétés spécifiques et développer les propriétés de navigation pour retourner des propriétés à partir d’enregistrements associés dans différentes tables.

Note

Pour plus d’informations sur la récupération des définitions de table, consultez les définitions de table de requête à l’aide de l’API web.

Récupération de base

L’exemple suivant retourne des données pour un enregistrement d’entité de compte avec la valeur de clé primaire égale à 000000-0000-0000-0000-00000000001 :

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

Cet exemple renvoie toutes les propriétés de l’enregistrement de compte, ce qui n’est pas une bonne pratique de performances. Vous devez toujours utiliser l’option $select de requête système pour limiter les propriétés retournées lors de la récupération des données. Cela est particulièrement important lors de la récupération de plusieurs lignes de données. Pour plus d'informations, consultez Interroger les données à l'aide de l'API Web.

Récupérer des propriétés spécifiques

Pour limiter les propriétés retournées lorsque vous récupérez des données avec une requête GET, utilisez l’option $select de requête système avec une liste séparée par des virgules des noms de propriétés. Demander uniquement les propriétés dont vous avez besoin est une bonne pratique de performances importante. Si vous ne spécifiez pas de propriétés à retourner, toutes les propriétés sont retournées.

L'exemple suivant récupère les propriétés name et revenue de l'entité de compte avec la valeur de clé primaire égale à 00000000-0000-0000-0000-000000000001 :

Requête :

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

Réponse:

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

{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,revenue)/$entity",  
"@odata.etag": "W/\"502186\"",  
"name": "A. Datum Corporation (sample)",  
"revenue": 10000,  
"accountid": "00000000-0000-0000-0000-000000000001",  
"_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"  
}

Lorsque vous demandez certains types de propriétés, vous pouvez vous attendre à ce que des propriétés en lecture seule soient retournées automatiquement.

Si vous demandez une valeur monétaire, la propriété de recherche _transactioncurrencyid_value est retournée. Cette propriété contient uniquement la valeur GUID de la devise de transaction. Vous pouvez donc l’utiliser pour récupérer des informations sur la devise à l’aide de l’EntityType transactioncurrency. Vous pouvez également obtenir plus de données dans la même requête en demandant des annotations.

Si vous demandez une propriété qui fait partie d’un attribut composite pour une adresse, vous obtenez également la propriété composite. Par exemple, si votre requête demande la address1_line1 propriété pour un contact, la address1_composite propriété est également retournée.

Récupérer un enregistrement à l’aide d’une autre clé

Si une entité a une autre clé définie, vous pouvez l’utiliser au lieu de l’identificateur unique pour récupérer, mettre à jour ou supprimer l’entité. Par défaut, aucune autre clé n’est configurée pour les entités. Les autres clés sont disponibles uniquement si votre organisation ou une solution les ajoute.

Les valeurs de clé alternatives avec les caractères suivants /, <, >, *, %, &, :, \\, ?, + ne sont actuellement pas prises en charge.

Par exemple, si l’entité Contact a une définition de clé alternative qui inclut à la fois les propriétés firstname et emailaddress1, vous pouvez récupérer le contact en utilisant une requête avec les données fournies pour ces clés :

GET [Organization URI]/api/data/v9.2/contacts(firstname='Joe',emailaddress1='abc@example.com')

Si la définition de clé alternative contient un champ de type de recherche (par exemple, la primarycontactid propriété de l’entité account), vous pouvez récupérer account en utilisant les propriétés de recherche, comme dans l’exemple suivant :

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

Récupérer des documents dans des partitions de stockage

Lorsque vous récupérez un enregistrement dans une table élastique stockée dans une partition, veillez à spécifier la clé de partition.

Récupérer une valeur de propriété unique

Lorsque vous devez uniquement récupérer la valeur d’une propriété unique, vous pouvez ajouter le nom de la propriété à l’URI d’entité. La réduction de la quantité de données retournées est une bonne pratique en matière de performances.

L’exemple suivant retourne uniquement la valeur de la name propriété pour une account entité :

Requête :

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

Réponse:

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

{
"@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
"value":"Adventure Works (sample)"
}

Récupérer la valeur brute d’une propriété

Pour récupérer la valeur brute d’une propriété primitive, plutôt que JSON, ajoutez /$value à l’URL ; par exemple :

Requête :

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name/$value HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Réponse:

HTTP/1.1 200 OK
Content-Type: text/plain
OData-Version: 4.0

Adventure Works (sample)

L’utilisation de la valeur brute n’est pas courante, sauf si vous utilisez des données de fichier ou d’image. Plus d’informations : Téléchargez un fichier dans une seule requête à l’aide de l’API web.

Récupérer les valeurs des propriétés de navigation

Vous pouvez accéder aux valeurs des propriétés de navigation ou des champs de recherche en ajoutant le nom de la propriété de navigation à l’URI d’une entité individuelle.

L'exemple suivant renvoie le fullname du contact principal d'un(e) account en utilisant la propriété de navigation à valeur unique primarycontactid.

Requête :

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Réponse:

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

{  
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)/$entity",  
"@odata.etag": "W/\"500128\"",  
"fullname": "Rene Valdes (sample)",  
"contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"  
}

Pour les propriétés de navigation à valeur de collection, vous pouvez demander de renvoyer uniquement des références aux entités associées ou simplement un nombre d’entités associées.

L’exemple suivant retourne des références aux tâches liées à un compte spécifique en ajoutant /$ref à la requête.

Requête :

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$ref HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Réponse:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
  
{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.2/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.2/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)" }
  ]
}

L’exemple suivant renvoie le nombre de tâches relatives à un compte spécifique avec la propriété de navigation avec une valeur de collection Account_Tasks avec /$count en annexe :

Requête :

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse:

2

Note

La valeur retournée inclut les caractères de marque d’ordre d’octet UTF-8 (BOM), qui indique qu’il s’agit d’un document UTF-8.

Utilisez l’option de requête système $expand pour contrôler quelles données des entités associées sont renvoyées. Plus d’informations : Tables de jointure

Détecter si un enregistrement a changé depuis sa récupération

En guise de meilleure pratique en matière de performances, vous devez uniquement demander des données dont vous avez besoin. Si vous avez précédemment récupéré un enregistrement d’entité, vous pouvez utiliser l’ETag associé à un enregistrement précédemment récupéré pour effectuer des récupérations conditionnelles sur cet enregistrement. Plus d’informations : récupérations conditionnelles.

Récupérer les valeurs mises en forme

Demander des valeurs mises en forme pour les récupérations d’enregistrements individuelles de la même façon que vous interrogez les jeux d’entités.

Voir aussi

Effectuer des opérations à l’aide de l’API Web
Composer des requêtes HTTP et gérer les erreurs
Interroger des données à l’aide de l’API web

  • Last updated on