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

Article
06/22/2022
5 minutes de lecture

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

Utilisez une requête GET pour récupérer les données d’une table spécifiée comme ressource avec un identifiant 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 renvoyer les propriétés des tables associées.

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.

Exemple de 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.0/accounts(00000000-0000-0000-0000-000000000001)

Pour récupérer plusieurs enregistrements d’entité à la fois, voir Exemple de requête de base dans la rubrique Interroger les données à l’aide de l’API Web.

Attention

L’exemple ci-dessus renverra toutes les propriétés de l’enregistrement de compte, ce qui n’est pas une bonne pratique de récupération de données en termes de performances. Cet exemple n’avait pour but que d’illustrer comment réaliser une récupération de base d’un enregistrement d’entité dans Microsoft Dataverse. Comme toutes les propriétés ont été retournées, nous n’avons pas inclus les informations de réponse pour la demande dans cet exemple.

Les meilleures pratiques en matière de performances recommandent de 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. Consultez la section suivante, Récupérer des propriétés spécifiques pour des informations à ce sujet.

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

Utilisez l’option de requête système $select pour limiter les propriétés retournées en incluant une liste de noms de propriété séparés par des virgules. C’est une pratique recommandée importante. Si des propriétés ne sont pas spécifiées à l’aide de $select, 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.0/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.0/$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 supplémentaires 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 dans transactioncurrency EntityType /. Par ailleurs, en demandant des annotations vous pouvez également obtenir des données supplémentaires dans la même requête. Pour plus d’informations : Extraire les données sur les propriétés de recherche

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 avec une clé secondaire

Si une entité a une clé secondaire définie, vous pouvez également utiliser la clé secondaire pour récupérer l’entité au lieu de l’identificateur unique pour l’entité. 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 comme indiqué ici.

GET [Organization URI]/api/data/v9.0/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 indiqué ici.

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

Chaque fois que vous devez identifier de façon unique une entité à récupérer, mettre à jour ou supprimer, vous pouvez utiliser les clés secondaires configurées 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.

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

Si vous récupérez des données d’entité stockées dans des partitions, veillez à spécifier la clé de partition lors de la récupération de ces données.

Plus d’information : Accéder plus rapidement aux données de table à l’aide de partitions de stockage

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

Lorsque vous ne devez récupérer que la valeur d’une propriété unique pour une entité, vous pouvez ajouter le nom de la propriété à l’URI pour qu’une entité renvoie uniquement la valeur de cette propriété. Il s’agit d’une meilleure pratique en matière de performances car moins de données doivent être renvoyées dans la réponse.

Cet exemple renvoie uniquement la valeur de la propriété name d’une entité account.

Demande

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

Response

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

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

De la même manière que vous pouvez récupérer les valeurs des propriétés individuelles, vous pouvez également accéder aux valeurs des propriétés de navigation (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.0/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

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

{  
"@odata.context": "[Organization URI]/api/data/v9.0/$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 avez la possibilité de 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 uniquement les références aux tâches relatives à un compte spécifique en ajoutant /$ref à la demande.

Demande

GET [Organization URI]/api/data/v9.0/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.0/$metadata#Collection($ref)",
    "value":
  [
    { "@odata.id": "[Organization URI]/api/data/v9.0/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)" },
    { "@odata.id": "[Organization URI]/api/data/v9.0/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.0/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. Il existe deux types de propriétés de navigation :

Les propriétés de navigation à valeur unique correspondent aux attributs de recherche qui prennent en charge les relation plusieurs-à-un et permettent de définir une référence à une autre entité.
Les propriétés de navigation avec une valeur de collection correspondent aux relations un-à-plusieurs ou plusieurs-à-plusieurs.

Si vous incluez uniquement le nom de la propriété de navigation, vous recevrez toutes les propriétés des enregistrements associés. Vous pouvez limiter les propriétés retournées pour les enregistrements associés à l’aide de l’option de requête système $select entre parenthèses après le nom de propriété de navigation. Utilisez cette procédure pour les propriétés de navigation à valeur unique et valeur de collection.

Notes

Pour récupérer des entités associées pour des ensembles d’entités, voir Récupérer des enregistrements de table liés avec une requête.

Récupérez les entités associées pour une instance d’entité en développant les propriétés de navigation à valeur unique :
L’exemple suivant montre comment récupérer le contact pour une entité de compte. Pour l’enregistrement de contact associé, nous récupérons uniquement l’identifiant de contact et le nom complet.

Demande

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

Response

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

{  
  "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))/$entity",  
  "@odata.etag":"W/\"550616\"",  
  "name":"Adventure Works (sample)",  
  "accountid":"00000000-0000-0000-0000-000000000001",  
  "primarycontactid":
  {  
  "@odata.etag":"W/\"550626\"",  
  "contactid":"c59648c3-68f7-e511-80d3-00155db53318",  
  "fullname":"Nancy Anderson (sample)"  
  }
}

Au lieu de retourner les entités associées pour les enregistrements d’entités, vous pouvez également retourner des références (liens) aux entités associées en développant la propriété de navigation à valeur unique avec l’option $ref. L’exemple suivant retourne des liens vers l’enregistrement de contact pour l’entité de compte.

Demande

GET [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid/$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.0/$metadata#accounts(name,primarycontactid)/$entity",  
  "@odata.etag":"W/\"550616\"",  
  "name":"Adventure Works (sample)",  
  "accountid":"00000000-0000-0000-0000-000000000001",  
  "_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",  
  "primarycontactid": { "@odata.id":"[Organization URI]/api/data/v9.0/contacts(c59648c3-68f7-e511-80d3-00155db53318)" }
}

Récupérez les entités associées pour une instance d’entité en développant les propriétés de navigation avec une valeur de collection :
L’exemple suivant montre comment récupérer toutes les tâches affectées à un enregistrement de compte.

Requête

GET [Organization URI]/api/data/v9.0/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name
&$expand=Account_Tasks($select=subject,scheduledstart)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

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

{
  "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))/$entity",
  "@odata.etag": "W/\"514069\"",
  "name": "Sample Child Account 1",
  "accountid": "915e89f5-29fc-e511-80d2-00155db07c77",
  "Account_Tasks":
   [
    {
      "@odata.etag": "W/\"514085\"",
      "subject": "Sample Task 1",
      "scheduledstart": "2016-04-11T15:00:00Z",
      "activityid": "a983a612-3ffc-e511-80d2-00155db07c77"
    },
    {
      "@odata.etag": "W/\"514082\"",
      "subject": "Sample Task 2",
      "scheduledstart": "2016-04-13T15:00:00Z",
      "activityid": "7bcc572f-3ffc-e511-80d2-00155db07c77"
    }
   ]
}

Récupérer les entités associées pour une instance d’entité en développant les propriétés de navigation à valeur unique et avec une valeur de collection : L’exemple suivant montre comment vous pouvez développer les entités associées pour une instance d’entité en utilisant les propriétés de navigation à valeur unique et avec une valeur de collection.

Demande

GET [Organization URI]/api/data/v9.0/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid
&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) 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.0/$metadata#accounts(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity",
"@odata.etag": "W/\"514069\"",
"accountid": "915e89f5-29fc-e511-80d2-00155db07c77",
"parentaccountid": 
    {
      "@odata.etag": "W/\"514074\"",
      "createdon": "2016-04-06T00:29:04Z",
      "name": "Adventure Works (sample)",
      "accountid": "3adbf27c-8efb-e511-80d2-00155db07c77"
    },
  "Account_Tasks":
    [
      {
        "@odata.etag": "W/\"514085\"",
        "subject": "Sample Task 1",
        "scheduledstart": "2016-04-11T15:00:00Z",
        "activityid": "a983a612-3ffc-e511-80d2-00155db07c77"
      },
      {
        "@odata.etag": "W/\"514082\"",
        "subject": "Sample Task 2",
        "scheduledstart": "2016-04-13T15:00:00Z",
        "activityid": "7bcc572f-3ffc-e511-80d2-00155db07c77"
      }
    ]
}

Notes

Vous ne pouvez pas utiliser les segments de chemin /$ref ou /$count pour retourner uniquement l’URI pour l’entité associée ou un nombre d’entités associées.

Options à appliquer aux tables développées

Vous pouvez appliquer certaines options de requête système sur les entités retournées pour une propriété de navigation à valeur de collection. Utilisez une liste d’options de requête système séparées par un point-virgule jointes entre parenthèses après le nom de la propriété de navigation à valeur de collection. Vous pouvez utiliser $select, $filter, $orderby, $top et $expand.

L’exemple suivant filtre les résultats des entités de tâches liées à un account à celles avec un objet qui se termine par « 1 ».

?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

L’exemple suivant indique les tâches associées qui doivent être retournées dans l’ordre croissant selon la propriété createdon.

?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

L’exemple suivant renvoie uniquement la première tâche associée.

?$expand=Account_Tasks($top=1;$select=subject)

L’exemple suivant applique des options $expand imbriquées pour renvoyer des détails sur le systemuser qui a modifié en dernier le compte et le nom de la businessunit à laquelle cet utilisateur appartient.

?$select=name&$expand=modifiedby($select=fullname;$expand=businessunitid($select=name))

Notes

Les options $expand imbriquées ne peuvent être appliquées qu’aux propriétés de navigation à valeur unique.
Chaque requête peut comprendre un maximum de 15 options $expand. Il n’y a pas de limite à la profondeur de l’imbrication des options $expand, mais la limite de 15 options $expand s’y applique aussi.
Il s’agit d’un sous-ensemble des options de requête système décrites dans la section « 11.2.4.2.1 Développer les options » de Partie 1 de la version 4.0 d’OData : Protocol Plus Errata 02. Les options $skip, $count, $search et $levels ne sont pas prises en charge pour l’API Web.

Pour plus d’informations sur l’utilisation de l’option $expand imbriquée : Extension à plusieurs niveaux des propriétés de navigation à valeur unique

Détecter si une table 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

La demande de 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. Pour plus d’informations :Inclure des valeurs mises en forme.

Voir aussi

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

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

Exemple de récupération de base

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

Récupérer avec une clé secondaire

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

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

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

Options à appliquer aux tables développées

Détecter si une table a changé depuis sa récupération

Récupérer des valeurs mises en forme

Voir aussi

Commentaires

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

Exemple de récupération de base

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

Récupérer avec une clé secondaire

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

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

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

Extraire les tables associées à une table en développant des propriétés de navigation

Options à appliquer aux tables développées

Détecter si une table a changé depuis sa récupération

Récupérer des valeurs mises en forme

Voir aussi

Commentaires