Interroger les données à 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

Si vous souhaitez récupérer les données d'un ensemble d'entités, utilisez une requête GET. Lors de la récuperation des données, vous pouvez appliquer des options de recherche pour définir les critères pour les données de votre choix et les propriétés de l'entité devant être retournées.

Contenu de la rubrique

Exemple de requête de base

Limite le nombre d'entités renvoyées

Spécifiez le nombre d'entités à renvoyer dans une page

Appliquer des options de requête système

Propriétés spécifiques de la demande

Filtrer les résultats

Classer les résultats

Utiliser des alias de paramètre avec des options de requête système

Limiter les résultats

Récupérer un nombre d'entités

Inclure des valeurs mises en forme

Extraire les données sur les propriétés de recherche

Filtrer les enregistrements en fonction de la propriété de navigation à valeur unique

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

Exemple de requête de base

Cet exemple interroge l'entité accounts définie et utilise les options de requête système $select et $toppour renvoyer la propriété name pour les trois premiers comptes :

Demande

GET cc_WebAPI_ServiceURI/accounts?$select=name&$top=3 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": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
 "value": [
  {
   "@odata.etag": "W/\"501097\"",
   "name": "Fourth Coffee (sample)",
   "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501098\"",
   "name": "Litware, Inc. (sample)",
   "accountid": "8b390c24-9c72-e511-80d4-00155d2a68d1"
  },
  {
   "@odata.etag": "W/\"501099\"",
   "name": "Adventure Works (sample)",
   "accountid": "8d390c24-9c72-e511-80d4-00155d2a68d1"
  }
 ]
}

Limite le nombre d'entités renvoyées

Sauf si vous spécifiez une taille de page inférieure, jusqu'à 5 000 entités sont renvoyées par demande. S'il existe plusieurs d'entités qui correspondent aux critères de filtre de requêtes, la propriété @odata.nextLink sera renvoyée avec les résultats. Utilisez la valeur de la propriété @odata.nextLink à une nouvelle demande GET pour renvoyer la page suivante de données.

Notes

Les requêtes sur les entités de modèles ne sont pas limitées ni paginées.Pour plus d'informations :Interroger les métadonnées à l'aide de l'API Web

Spécifiez le nombre d'entités à renvoyer dans une page

Utilisez la valeur de préférence odata.maxpagesize pour demander le nombre d'entités renvoyées dans la réponse.

Notes

Vous ne pouvez pas utiliser une valeur de préférence odata.maxpagesize supérieure à 5 000.

L'exemple suivant interroge l'entité accounts définie et renvoie la propriété name pour les trois premiers comptes.

Demande

GET cc_WebAPI_ServiceURI/accounts?$select=name HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

Réponse

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 402
Preference-Applied: odata.maxpagesize=3

{
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name)",
  "value": [
    {
      "@odata.etag": "W/\"437194\"",
      "name": "Fourth Coffee (sample)",
      "accountid": "7d51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"437195\"",
      "name": "Litware, Inc. (sample)",
      "accountid": "7f51925c-cde2-e411-80db-00155d2a68cb"
    },
    {
      "@odata.etag": "W/\"468026\"",
      "name": "Adventure Works (sample)",
      "accountid": "8151925c-cde2-e411-80db-00155d2a68cb"
    }
  ],
  "@odata.nextLink": "cc_WebAPI_ServiceURI/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b8151925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520first%253d%2522%257b7D51925C-CDE2-E411-80DB-00155D2A68CB%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20/%3E"
}

Utilisez la valeur de la propriété @odata.nextLink pour demander l'ensemble d'enregistrements suivant. Ne modifiez ou n'ajoutez aucune option de requête système supplémentaires à la valeur. Pour chaque demande de pages supplémentaires consécutive, vous devez utiliser la même valeur de préférence odata.maxpagesize que celle utilisée dans la demande d'origine. En outre, placez les résultats renvoyés ou la valeur de la propriété @odata.nextLink dans le cache de sorte que les pages récupérées précédemment puissent être renvoyées.

Notes

La valeur @odata.nextLink de la propriété est encodée URI. Si vous encodez URI la valeur avant de l'envoyer, les informations des cookies XML dans l'URL entraîneront erreur.

Appliquer des options de requête système

Chacune des options de requête système que vous ajoutez à l'URL de l'ensemble d'entités est ajoutée à la syntaxe des chaînes de requête. La première est ajoutée après [?] et les options de requête suivantes sont séparées à l'aide d'un [&]. Toutes les options de requête respectent la casse comme illustré dans l'exemple suivant.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3&$filter=revenue gt 100000

Propriétés spécifiques de la demande

Utilisez l'option de requête système $select pour limiter les propriétés renvoyées comme illustré dans l'exemple suivant.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue

Important

C'est une pratique recommandée. Si des propriétés ne sont pas spécifiées à l'aide de $select, toutes les propriétés sont renvoyées.

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.

Filtrer les résultats

Utilisez l'option de requête système $filter pour définir les critères pour lesquels les entités sont renvoyées.

Opérateurs de filtre standard

L'API Web prend en charge les opérateurs de filtre OData standard répertoriées dans le tableau suivant.

Opérateur	Description	Exemple
Opérateurs de comparaison
eq	Égal à	$filter=revenue eq 100000
ne	Différent de	$filter=revenue ne 100000
gt	Supérieur(e) à	$filter=revenue gt 100000
ge	Supérieur ou égal à	$filter=revenue ge 100000
lt	Inférieur(e) à	$filter=revenue lt 100000
le	Inférieur ou égal à	$filter=revenue le 100000
Opérateurs logiques
and	ET logique	$filter=revenue lt 100000 and revenue gt 2000
or	OU logique	$filter=contains(name,'(sample)') or contains(name,'test')
not	Négation logique	$filter=not contains(name,'sample')
Opérateurs de groupement
( )	Groupement de priorité	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Notes

C'est un sous-ensemble des Opérations de filtre intégré 11.2.5.1.1. Les opérateurs arithmétiques et de comparaison ne sont pas pris en charge dans l'API Web.

Fonctionnalités de requête standard

L'API Web prend en charge ces fonctions de requête de chaîne OData standard.

Fonction	Exemple
contains	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Notes

C'est un sous-ensemble des Fonctions de requête intégré 11.2.5.1.2.Date, Math, Type, Geo et autres fonctions de chaîne ne sont pas pris en charge dans l'API Web.

Fonctions de requête de l'API Web Microsoft Dynamics 365

Microsoft Dynamics 365 fournit un certain nombre de fonctionnalités spéciales qui acceptent des paramètres, des valeurs booléennes de retour, et peuvent être utilisées comme critères de filtre dans une requête. Pour obtenir une liste de ces fonctionnalités, voir Web API Query Function Reference. L'exemple suivant présente la recherche de comptes avec un nombre d'employés allant de 5 à 2 000 Between Function.

GET cc_WebAPI_ServiceURI/accounts?$select=name,numberofemployees&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Pour plus d'informations :Composer une requête avec des fonctions.

Classer les résultats

Spécifiez l'ordre dans lequel les éléments sont renvoyés à l'aide de l'option de requête système $orderby. Utilisez le suffixe asc ou desc pour spécifier l'ordre croissant ou décroissant respectivement. La valeur par défaut est croissant si le suffixe n'est pas appliqué. L'exemple suivant présente la récupération des propriétés de nom et de revenu des comptes contrôlées par le revenu croissant et par le nom décroissant.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Utiliser des alias de paramètre avec des options de requête système

Vous pouvez utiliser des alias de paramètre pour les options de requête système $filter et $orderby. Les alias de paramètre permettent que la même valeur soit utilisée plusieurs fois dans une requête. Si l'alias ne dispose pas d'une valeur, le système suppose qu'il est nul.

Sans alias de paramètre

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=revenue asc,name desc&$filter=revenue ne null

Avec alias de paramètre

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue,&$orderby=@p1 asc,@p2 desc&$filter=@p1 ne @p3&@p1=revenue&@p2=name

Vous pouvez également utiliser des alias de paramètre lorsque vous utilisez des fonctionnalités.Pour plus d'informations :Utiliser des fonctions API Web

Limiter les résultats

Vous pouvez limiter le nombre de résultats renvoyés à l'aide de l'option de requête système $top. L'exemple suivant renverra seulement les trois premières entités de compte.

GET cc_WebAPI_ServiceURI/accounts?$select=name,revenue&$top=3

Notes

La limitation des résultats à l'aide de $top permet d'empêcher que la préférence odata.maxpagesize soit appliquée. Vous pouvez utiliser les préférences odata.maxpagesize ou $top, mais pas les deux à la fois. Pour plus d’informations sur odata.maxpagesize, voir Spécifiez le nombre d'entités à renvoyer dans une page.

Vous ne devez pas également utiliser $top avec $count.

Récupérer un nombre d'entités

Utilisez l'option de requête système $count contenant une valeur de true pour inclure un nombre d'entités correspondant aux critères de filtre jusqu'à 5 000.

Notes

La valeur du nombre ne représente pas le nombre total d'entités dans le système. Il est limité par le nombre maximal d'entités pouvant être renvoyées.Pour plus d'informations :Limite le nombre d'entités renvoyées

La propriété @odata.count** de réponse contiendra le nombre d'entités qui correspondent aux critères de filtre quelle que soit la limite de préférence **odata.maxpagesize.

Notes

Vous ne devez pas utiliser $top avec $count.

L'exemple suivant indique que dix comptes correspondent aux critères dont le nom contient « exemple », mais seulement les trois premiers comptes sont renvoyés.

Demande

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$count=true HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=3

Réponse

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

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name)",
"@odata.count":10,
"value":[
    {
      "@odata.etag":"W/\"502482\"","name":"Fourth Coffee (sample)","accountid":"655eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502483\"","name":"Litware, Inc. (sample)","accountid":"675eaf89-f083-e511-80d3-00155d2a68d3"
    },{
      "@odata.etag":"W/\"502484\"","name":"Adventure Works (sample)","accountid":"695eaf89-f083-e511-80d3-00155d2a68d3"
    }
  ],"@odata.nextLink":"cc_WebAPI_ServiceURI/accounts?$select=name&$filter=contains(name,'sample')&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b695EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520first%253d%2522%257b655EAF89-F083-E511-80D3-00155D2A68D3%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}

Si vous ne souhaitez renvoyer aucune donnée sauf le nombre, vous pouvez appliquer $count à un ensemble pour obtenir uniquement la valeur.

Demande

GET cc_WebAPI_ServiceURI/accounts/$count 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

10

Inclure des valeurs mises en forme

Lorsque vous souhaitez recevoir des valeurs mises en forme pour des propriétés avec les résultats, utilisez la préférence odata.include-annotations avec la valeur OData.Community.Display.V1.FormattedValue. La réponse contiendra ces valeurs avec les propriétés correspondant à la convention d'appellation suivante :

<propertyname>@OData.Community.Display.V1.FormattedValue

L'exemple suivant interroge l'entité comptes définie et renvoie le premier enregistrement, notamment les propriétés qui prennent en charge les valeurs formatées.

Demande

GET cc_WebAPI_ServiceURI/accounts?$select=name,donotpostalmail,accountratingcode,numberofemployees,revenue&$top=1 HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Réponse

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name,donotpostalmail,accountratingcode,numberofemployees,revenue)",
 "value": [
 {
  "@odata.etag": "W/"502170"",
  "name": "Fourth Coffee (sample)",
  "donotpostalmail@OData.Community.Display.V1.FormattedValue": "Allow",
  "donotpostalmail": false,
  "accountratingcode@OData.Community.Display.V1.FormattedValue": "Default Value",
  "accountratingcode": 1,
  "numberofemployees@OData.Community.Display.V1.FormattedValue": "9,500",
  "numberofemployees": 9500,
  "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
  "revenue": 100000,
  "accountid": "89390c24-9c72-e511-80d4-00155d2a68d1",
  "transactioncurrencyid_value": "50b6dd7b-f16d-e511-80d0-00155db07cb1" } ]
}

Extraire les données sur les propriétés de recherche

Si votre requête contient des propriétés de recherche demandez des annotations qui fourniront des informations supplémentaires sur les données dans ces propriétés. La plupart du temps, ces mêmes données peuvent être dérivées avec des propriétés de navigation à valeur unique et les données incluses dans les entités associées. Toutefois, dans les cas où la propriété représente un attribut de recherche qui peut se référer à plusieurs types d'entités, ces informations peuvent vous indiquer le type d'entité référencé par la propriété de recherche.Pour plus d'informations :d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_lookupProperties

Il existe deux types d'autres annotations disponibles pour ces propriétés,

Annotation	Description
Microsoft.Dynamics.CRM.associatednavigationproperty	Nom de la propriété de navigation à valeur unique qui inclut une référence à l'entité.
Microsoft.Dynamics.CRM.lookuplogicalname	Nom logique de l’entité référencée par la recherche.

Ces propriétés peuvent également contenir des valeurs mises en forme comme décrit dans Inclure des valeurs mises en forme. Comme les valeurs mises en forme, vous pouvez renvoyer les autres annotations avec la préférence odata.include-annotations définie au type spécifique d'annotation souhaité, ou vous pouvez définir la valeur "*" et renvoyer les trois. Cet exemple explique la demande et la réponse pour récupérer des informations sur la propriété de recherche _customerid_value de l'entité incident avec des annotations incluses.

Demande

GET cc_WebAPI_ServiceURI/incidents(39dd0b31-ed8b-e511-80d2-00155d2a68d4)?$select=title,customerid_value&$expand=customerid_contact($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="*"

Réponse

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
   "@odata.context":"cc_WebAPI_ServiceURI/$metadata#incidents(title,_customerid_value,customerid_contact(fullname))/$entity",
   "@odata.etag":"W/\"504696\"",
   "_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty":"customerid_contact",
   "_customerid_value@Microsoft.Dynamics.CRM.lookuplogicalname":"contact",
   "_customerid_value@OData.Community.Display.V1.FormattedValue":"Susanna Stubberod (sample)",
   "_customerid_value":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4",
   "incidentid":"39dd0b31-ed8b-e511-80d2-00155d2a68d4",
   "customerid_contact":{
      "@odata.etag":"W/\"503587\"",
      "fullname":"Susanna Stubberod (sample)",
      "contactid":"7ddd0b31-ed8b-e511-80d2-00155d2a68d4"
   }
}

Les propriétés de navigation vous permettent d'accéder aux données relatives à l'entité actuelle. 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é.Pour plus d'informations :d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_navprops

Vous pouvez filtrer vos enregistrements d'ensembles d'entités en fonction des valeurs de propriété de navigation à valeur unique. Par exemple, vous pouvez extraire les comptes enfants pour le compte spécifié. Vous pouvez uniquement utiliser la valeur d'attribut principale de l'entité référencée par la propriété de navigation à valeur unique pour filtrer les enregistrements. Par exemple :

Extraire tous les comptes correspondants à un ID de contact spécifié

Demande

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=primarycontactid/contactid%20eq%20a0dbf27c-8efb-e511-80d2-00155db07c77 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)",
     "value":[
    {
      "@odata.etag":"W/\"513479\"",
      "name":"Adventure Works (sample)",
      "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514057\"",
      "name":"Blue Yonder Airlines (sample)",
      "accountid":"3edbf27c-8efb-e511-80d2-00155db07c77"
    }
  ]
}

Extraire les comptes enfants pour l'ID du compte spécifié.

Demande

GET cc_WebAPI_ServiceURI/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
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)",
    "value":[
    {
      "@odata.etag":"W/\"514058\"",
      "name":"Sample Child Account 1",
      "accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
    },{
      "@odata.etag":"W/\"514061\"",
      "name":"Sample Child Account 2",
      "accountid":"03312500-2afc-e511-80d2-00155db07c77"
    }
  ]
}

Utilisez l'option de requête système $expand dans les propriétés de navigation 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 extraire les entités associées pour une instance d'entité, voir Extraire les entités associées pour une entité en développant les propriétés de navigation.

Extraire les entités associées en développant les propriétés de navigation à valeur unique : L'exemple suivant montre comment extraire le contact pour tous les enregistrements de compte. Pour les enregistrements de contact associés, nous récupérons uniquement l'identifiant de contact et le nom complet.

Demande

GET cc_WebAPI_ServiceURI/accounts?$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))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9cdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Yvonne McKay (sample)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"9edbf27c-8efb-e511-80d2-00155db07c77","fullname":"Susanna Stubberod (sample)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a2dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Maria Campbell (sample)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a0dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Nancy Anderson (sample)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a6dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Scott Konersmann (sample)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"a8dbf27c-8efb-e511-80d2-00155db07c77","fullname":"Robert Lyon (sample)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aadbf27c-8efb-e511-80d2-00155db07c77","fullname":"Paul Cannon (sample)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"acdbf27c-8efb-e511-80d2-00155db07c77","fullname":"Rene Valdes (sample)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "contactid":"aedbf27c-8efb-e511-80d2-00155db07c77","fullname":"Jim Glynn (sample)"
      }
    }
  ]
}

Au lieu de retourner les entités associées pour les ensembles 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 les enregistrements de contact pour tous les comptes.

Demande

GET cc_WebAPI_ServiceURI/accounts?$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)","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","_primarycontactid_value":"9cdbf27c-8efb-e511-80d2-00155db07c77","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9cdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","_primarycontactid_value":"9edbf27c-8efb-e511-80d2-00155db07c77","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(9edbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513479\"","name":"Adventure Works (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","_primarycontactid_value":"a2dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a2dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","_primarycontactid_value":"a0dbf27c-8efb-e511-80d2-00155db07c77","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a0dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513485\"","name":"City Power & Light (sample)","_primarycontactid_value":"a6dbf27c-8efb-e511-80d2-00155db07c77","accountid":"40dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a6dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513487\"","name":"Contoso Pharmaceuticals (sample)","_primarycontactid_value":"a8dbf27c-8efb-e511-80d2-00155db07c77","accountid":"42dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(a8dbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513489\"","name":"Alpine Ski House (sample)","_primarycontactid_value":"aadbf27c-8efb-e511-80d2-00155db07c77","accountid":"44dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aadbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513491\"","name":"A. Datum Corporation (sample)","_primarycontactid_value":"acdbf27c-8efb-e511-80d2-00155db07c77","accountid":"46dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(acdbf27c-8efb-e511-80d2-00155db07c77)"
      }
    },{
      "@odata.etag":"W/\"513493\"","name":"Coho Winery (sample)","_primarycontactid_value":"aedbf27c-8efb-e511-80d2-00155db07c77","accountid":"48dbf27c-8efb-e511-80d2-00155db07c77","primarycontactid":{
        "@odata.id":"cc_WebAPI_ServiceURI/contacts(aedbf27c-8efb-e511-80d2-00155db07c77)"
      }
    }
  ]
}

Extraire les entités associées en développant les propriétés de navigation avec une valeur de collection : Si vous développez les paramètres de navigation avec une valeur de collection (pour extraire les entités associées pour des ensembles d'entités, une propriété @odata.nextLink sera retournée 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.

L'exemple suivant récupère les tâches attribuées aux 5 enregistrements de compte principaux.

Demande

GET cc_WebAPI_ServiceURI/accounts?$top=5&$select=name&$expand=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":"cc_WebAPI_ServiceURI/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"513475\"","name":"Fourth Coffee (sample)","accountid":"36dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(36dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513477\"","name":"Litware, Inc. (sample)","accountid":"38dbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(38dbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514074\"","name":"Adventure Works (sample)","accountid":"3adbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3adbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"513481\"","name":"Fabrikam, Inc. (sample)","accountid":"3cdbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3cdbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    },{
      "@odata.etag":"W/\"514057\"","name":"Blue Yonder Airlines (sample)","accountid":"3edbf27c-8efb-e511-80d2-00155db07c77","Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(3edbf27c-8efb-e511-80d2-00155db07c77)/Account_Tasks?$select%20=%20subject,%20scheduledstart"
    }
  ]
}

Extraire les entités associées 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 des ensembles d'entités en utilisant les propriétés de navigation à valeur unique et avec une valeur de collection. Comme expliqué précédemment, le développement des propriétés de navigation avec une valeur de collection pour extraire les entités associées pour des ensembles d'entités renvoie une propriété @odata.nextLink 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.

Dans cet exemple, nous récupérons le contact et les tâches attribués aux 3 comptes principaux.

Demande

GET cc_WebAPI_ServiceURI/accounts?$top=3&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)  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,Account_Tasks,primarycontactid(contactid,fullname),Account_Tasks(subject,scheduledstart))","value":[
    {
      "@odata.etag":"W/\"550614\"",
          "name":"Fourth Coffee (sample)",
          "accountid":"5b9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c19648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Yvonne McKay (sample)"
      },
      "Account_Tasks":[

       ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5b9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550615\"",
          "name":"Litware, Inc. (sample)",
          "accountid":"5d9648c3-68f7-e511-80d3-00155db53318",
          "primarycontactid":{
              "contactid":"c39648c3-68f7-e511-80d3-00155db53318",
              "fullname":"Susanna Stubberod (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5d9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    },{
      "@odata.etag":"W/\"550616\"",
      "name":"Adventure Works (sample)",
      "accountid":"5f9648c3-68f7-e511-80d3-00155db53318",
      "primarycontactid":{
        "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
        "fullname":"Nancy Anderson (sample)"
      },"Account_Tasks":[

      ],"Account_Tasks@odata.nextLink":"cc_WebAPI_ServiceURI/accounts(5f9648c3-68f7-e511-80d3-00155db53318)/Account_Tasks?$select=subject,scheduledstart"
    }
  ]
}

Voir aussi

Microsoft Dynamics 365

Partager via

Interroger les données à l'aide de l'API Web

Contenu de la rubrique

Exemple de requête de base

Limite le nombre d'entités renvoyées

Spécifiez le nombre d'entités à renvoyer dans une page

Appliquer des options de requête système

Propriétés spécifiques de la demande

Filtrer les résultats

Opérateurs de filtre standard

Fonctionnalités de requête standard

Fonctions de requête de l'API Web Microsoft Dynamics 365

Classer les résultats

Utiliser des alias de paramètre avec des options de requête système

Limiter les résultats

Récupérer un nombre d'entités

Inclure des valeurs mises en forme

Extraire les données sur les propriétés de recherche

Filtrer les enregistrements en fonction de la propriété de navigation à valeur unique

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

Voir aussi

Ressources supplémentaires