Récupérer une entité à l'aide de l'API Web

Article
10/31/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Utilisez une requête GET pour récupérer des données pour une entité spécifiée en tant que ressource avec un identifiant unique. Lorsque vous récupérez une 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 d'entités associées.

Notes

Pour plus d'informations sur la récupération des métadonnées d'entité, voir Interroger les métadonnées à l'aide de l'API Web.

Contenu de la rubrique

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 une valeur de propriété unique

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

Extraire les entités associées pour une entité en développant les propriétés de navigation

Options à appliquer aux entités développées

Détecter si une entité a changé depuis qu'elle a été récupérée

Récupérer des valeurs mises en forme

Exemple de récupération de base

Cet exemple renvoie des données pour une instance d'entité de compte avec la valeur de clé primaire égale à 00000000-0000-0000-0000-000000000001.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)

Pour récupérer plusieurs entités à 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 renvoie toutes les propriétés pour les enregistrements de compte, ce qui est contraire aux meilleures pratiques en matière de performances pour la récupération de données. Cet exemple sert juste à illustrer comment procéder à une récupération de base d'une instance d'entité dans Dynamics 365. 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 cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$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.Pour plus d'informations :5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes.

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 cc_WebAPI_ServiceURI/contacts(firstname='Joe',emailaddress1='abc@example.com')

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

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é à 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é de nom d'une entité de compte.

Demande

GET cc_WebAPI_ServiceURI/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":"cc_WebAPI_ServiceURI/$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 à URI faisant référence à une entité individuelle.

L'exemple suivant renvoie le nom complet du contact principal d'un compte avec la propriété de navigation à valeur unique primarycontactid.

Demande

GET cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$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 cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#Collection($ref)",
"value": [
{
"@odata.id": "cc_WebAPI_ServiceURI/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)"
},
{
"@odata.id": "cc_WebAPI_ServiceURI/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 cc_WebAPI_ServiceURI/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 les entités associées pour un ensemble d'entités, voir Extraire les entités associées en développant les propriétés de navigation.

Récupérer 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 extraire 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 cc_WebAPI_ServiceURI/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

Réponse

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$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 instances 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 cc_WebAPI_ServiceURI/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":"cc_WebAPI_ServiceURI/$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":"cc_WebAPI_ServiceURI/contacts(c59648c3-68f7-e511-80d3-00155db53318)"
}
}

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

Demande

GET cc_WebAPI_ServiceURI/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

Réponse

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

{
"@odata.context":"cc_WebAPI_ServiceURI/$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"
}
]
}

Notes

Si vous développez des paramètres de navigation avec une valeur de collection pour récupérer les entités associées pour des ensembles d'entités, une propriété @odata.nextLink est retournée à la place pour les entités associées. Utilisez la valeur de la propriété @odata.nextLink à une nouvelle demande GET pour renvoyer les données requises.Pour plus d'informations :Extraire les entités associées en développant les propriétés de navigation

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 cc_WebAPI_ServiceURI/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
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":"cc_WebAPI_ServiceURI/$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 entités 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 et $top.

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

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$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.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

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

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($top=1;$select=subject)

Notes

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 OData Version 4.0 Part 1: Protocol Plus Errata 02. Les options $skip, $count, $search, $expand et $levels ne sont pas prises en charge pour l'API Web.

Détecter si une entité a changé depuis qu'elle a été récupérée

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, voir 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

Microsoft Dynamics 365

Récupérer une entité à l'aide de l'API Web

Contenu de la rubrique

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 une valeur de propriété unique

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

Extraire les entités associées pour une entité en développant les propriétés de navigation

Options à appliquer aux entités développées

Détecter si une entité a changé depuis qu'elle a été récupérée

Récupérer des valeurs mises en forme

Voir aussi

Ressources supplémentaires