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

  • Article

Utilisez une requête GET pour récupérer les données d’un enregistrement spécifié comme ressource avec un identifiant unique. Pendant 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 renvoyer les enregistrements associées vers différentes tables.

Notes

Pour plus d’informations sur la récupération des définitions de table, voir Interroger les définitions de table à l’aide de l’API web.

Récupération de base

Cet exemple renvoie des données pour un enregistrement d’entité de compte avec la valeur de clé primaire égale à 00000000-0000-0000-0000-000000000001 :

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 de requête système $select pour limiter les propriétés retournées lorsque vous récupérez des données. Ceci 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 renvoyées lorsque vous récupérez des données avec une requête GET, utilisez l’option de requête système $select avec une liste de noms de propriété séparés par des virgules. Demander uniquement les propriétés dont vous avez besoin est une bonne pratique offrant d’excellentes performances. Si vous ne précisez pas de propriétés à renvoyer, toutes les propriétés sont renvoyées.

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

Demande :

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"  
}

Quand vous demandez certains types de propriétés, vous pouvez vous attendre à ce que davantage de propriétés en lecture seule soient renvoyé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 utiliser cette valeur pour récupérer des informations sur la devise danstransactioncurrency EntityType. Par ailleurs, en demandant des annotations vous pouvez également obtenir des données supplémentaires dans la même requête.

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

Récupérer l’enregistrement avec une clé secondaire

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

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

Par exemple, si l’entité Contact possède une définition de clé secondaire incluant les propriétés firstname et emailaddress1, vous pouvez récupérer le contact à l’aide d’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 clé secondaire contient un champ de type de recherche (par exemple, la propriété primarycontactid pour l’entité account), vous pouvez récupérer le 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 les documents dans des partitions de stockage

Si vous récupérez des données dans une table élastique stockées dans une partition, assurez-vous de spécifier la clé de partition lors de la récupération de ces données.

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

Si vous ne souhaitez que récupérer la valeur de la propriété unique, vous pouvez modifier le nom de la propriété avec l’URI de l’entité. La réduction de la quantité de données renvoyées est une bonne pratique en matière de performances.

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

Demande :

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 :

Demande :

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 les données de fichier ou d’image. Plus d’informations : Télécharger un fichier en une seule requête à l’aide de l’API Web.

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

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

L’exemple suivant renvoie le fullname du contact principal d’un account avec la propriété de navigation à valeur unique primarycontactid :

Demande :

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 avec une valeur de collection, vous pouvez demander de retourner uniquement les références aux entités associées ou à un nombre d’entités associées.

L’exemple suivant renverra les références aux tâches relatives à un compte spécifique en ajoutant /$ref à la demande.

Demande :

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 :

Demande :

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

Notes

La valeur retournée contient des caractères BOM UTF-8 () indiquant 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

Les meilleures pratiques en matière de performances recommandent de demander uniquement les données dont vous avez besoin. Si vous avez déjà récupéré un enregistrement d’entité, vous pouvez utiliser ETAG associé à un enregistrement récupéré précédemment pour effectuer des récupérations conditionnelles sur cet enregistrement. Pour plus d’informations : Récupérations conditionnelles.

Récupérer des valeurs mises en forme

Demandez des valeurs mises en forme pour les récupérations d’enregistrement individuel se fait de la même manière que la demande d’ensembles d’entités.

Voir aussi

Effectuer des opérations à l’aide de l’API Web
Composer des demandes HTTP et traiter les erreurs
Interroger les données à l’aide de l’API web

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