Commentaires

Interroger les données à l’aide de l’API web

  • Article
  • 9 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.

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 entités (table) pour les données de votre choix et les propriétés de l’entité (colonnes) devant être retournées.

Exemple de requête de base

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

Demande

GET [Organization URI]/api/data/v9.2/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":"[Organization URI]/api/data/v9.2/$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 de lignes de table (entités) renvoyées

Sauf si vous spécifiez une taille de page inférieure, jusqu’à 5 000 lignes sont renvoyées par demande. S’il existe plusieurs lignes 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 lignes.

Notes

Les requêtes sur les définitions d’entité (table) ne sont ni limitées ni paginées. Pour plus d’informations : consultez Interroger les définitions de table à l’aide de l’API Web

Utiliser l’option de requête $top

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 lignes de compte.

GET [Organization URI]/api/data/v9.2/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écifier le nombre de lignes à renvoyer dans une page.

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

Spécifier le nombre de lignes à renvoyer dans une page

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

Notes

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

S’il y a plus d’enregistrements qui correspondent à vos critères, la propriété @odata.nextLink sera renvoyée avec une URL que vous pourrez utiliser dans une prochaine demande GET pour obtenir la page suivante des enregistrements correspondant à vos critères.

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

Demande

GET [Organization URI]/api/data/v9.2/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":"[Organization URI]/api/data/v9.2/$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":"[Organization URI]/api/data/v9.2/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 de la propriété @odata.nextLink est encodée URI. Si vous encodez par l’URI la valeur avant de l’envoyer, les informations des cookies XML dans l’URL entraîneront une 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 [Organization URI]/api/data/v9.2/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 [Organization URI]/api/data/v9.2/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.

Quand 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.

Filtrer les résultats

Utilisez l’option de requête système $filter pour définir les critères pour lesquels les lignes 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.

Toutes les conditions de filtre pour les valeurs de chaîne sont insensibles à la casse.

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

Utilisez des caractères génériques dans les conditions à l’aide de valeurs de chaîne

Vous pouvez utiliser des caractères génériques lorsque vous créez des requêtes utilisant ces fonctions de requête standard sur des valeurs de chaîne. Plus d’informations : Utilisez des caractères génériques dans les conditions pour les valeurs de chaîne

Fonctions de requête de l’API Web Microsoft Dataverse

Dataverse 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 [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
&$filter=Microsoft.Dynamics.CRM.Between(PropertyName='numberofemployees',PropertyValues=["5","2000"])

Pour plus d’informations, voir :Composer une requête avec des fonctions.

Utiliser les opérateurs lambda

L’API web vous permet d’utiliser deux opérateurs lambda, qui sont any et all pour évaluer une expression booléenne sur une collection.

Opérateur any

L’opérateur any renvoie la valeur true si l’expression booléenne appliquée est true pour n’importe quel membre de la collection, sinon il renvoie la valeur false. L’opérateur any sans argument renvoie la valeur true si la collection n’est pas vide.

Exemple

L’exemple fourni ci-dessous vous montre comment récupérer tous les enregistrements de l’entité de compte qui possèdent au moins un courrier électronique avec « sometext » dans l’objet.

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(o:contains(o/subject,'sometext')) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Opérateur all

L’opérateur all renvoie la valeur true si l’expression booléenne appliquée est true pour tous les membres de la collection, sinon il renvoie la valeur false.

Exemple

L’exemple fourni ci-dessous vous montre comment récupérer tous les enregistrements de l’entité de compte disposant de toutes les tâches associées fermées.

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Tasks/all(o:o/statecode eq 1) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

L’exemple fourni ci-dessous vous montre comment récupérer tous les enregistrements de l’entité de compte qui possèdent au moins un courrier électronique avec « sometext » dans l’objet et dont le codeétat est actif.

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=Account_Emails/any(o:contains(o/subject,'sometext') and 
o/statecode eq 0) HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

L’exemple fourni ci-dessous vous montre comment vous pouvez également créer la requête imbriquée à l’aide des opérateurs any et all.

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and 
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and 
endswith(name,'{0}') HTTP/1.1
Prefer: odata.include-annotations="*"
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Filtrer les lignes parents (enregistrements) selon les valeurs des enregistrements enfants

L’exemple fourni ci-dessous vous montre comment utiliser l’opérateur /any pour récupérer tous les enregistrements de compte qui ont :

  • le budget de l’un de leurs enregistrements d’opportunité associés est supérieur ou égal à 300, et
  • l’enregistrement d’opportunité n’a aucune description, ou
  • la description de l’enregistrement d’opportunité contient le terme bad.

Demande

GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=not opportunity_customer_accounts/any(o:o/description eq null and 
o/budgetamount le 300 or 
contains(o/description, 'bad')) and 
opportunity_customer_accounts/any() and 
endswith(name,'{0}') HTTP/1.1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

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

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é. Informations complémentaires : Propriétés de navigation.

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

Par exemple :

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

    Demande

    GET [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=primarycontactid/contactid eq a0dbf27c-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":"[Organization URI]/api/data/v9.2/$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 [Organization URI]/api/data/v9.2/accounts?$select=name
&$filter=parentaccountid/accountid eq 3adbf27c-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":"[Organization URI]/api/data/v9.2/$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"
       }
    ]
}

Filtrer des valeurs de résultats en fonction des propriétés de navigation avec une valeur de collection

Notes

Il est possible d’utiliser $filter dans $expand pour filtrer des résultats pour des enregistrements associés dans une opération Récupérer. Vous pouvez utiliser 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. Les options de requête prises en charge dans $expand sont $select, $filter, $top et $orderby. Plus d’informations : Options à appliquer aux tables développées

Les deux options de filtrage des valeurs de résultats en fonction des propriétés de navigation avec une valeur de collection sont :

  1. Créer une requête en utilisant les opérateurs lambda

    Les opérateurs lambda vous permettent d’appliquer un filtre sur les valeurs des propriétés de collection pour une entité de lien. L’exemple ci-dessous récupère les enregistrements du type d’entité systemuser lié aux types d’entités team et teammembership, ce signifie qu’il récupère des enregistrements systemuser qui sont également administrateurs d’une équipe dont le nom est « CITTEST ».

    GET [Organization URI]/api/data/v9.2/systemusers?$filter=(teammembership_association/any(t:t/name eq 'CITTEST'))
&$select=fullname,businessunitid,title,address1_telephone1,systemuserid
&$orderby=fullname
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

    Informations complémentaires : Utiliser les opérateurs lambda.

  2. Itérer sur des résultats filtrant les entités individuelles en fonction des valeurs dans la collection en utilisant des opérations multiples

    Pour obtenir les mêmes résultats que l’exemple ci-dessus, vous pouvez extraire des enregistrements de deux types d’entités et itérativement faire correspondre les valeurs dans la collection d’une entité à la valeur de l’autre entité, en filtrant ainsi les entités en fonction des valeurs de la collection.

    Suivez les étapes de l’exemple ci-dessous pour savoir comment nous pouvons filtrer les résultats à l’aide de la méthode d’itération :

    1. Obtenez une liste distincte de valeurs team._administratorid_value.
      • GET [OrganizationURI]/api/data/v9.2/teams?$select=_administratorid_value&$filter=_administrator_value ne null
      • Effectuez une boucle ensuite via les valeurs retournées pour supprimer les doublons et obtenir une liste distincte. c’est-à-dire créez un tableau, effectuez une boucle via les résultats de la requête, et vérifiez chaque fois s’ils sont déjà dans le nouvel tableau, sinon, ajoutez-les. Vous devez vous retrouver avec une liste de valeurs systemuserid séparées
      • La façon dont procédez dans JavaScript par rapport à C# sera différente, mais essentiellement vous pouvez procéder pour obtenir les mêmes résultats.
    2. Interrogez systemuser à l’aide de ContainValues Query Function pour comparer les valeurs systemuserid avec la liste collectée à l’étape 1.

Gérer les guillemets simples dans les valeurs de filtre de chaîne

Lorsque vous spécifiez des valeurs à comparer dans des filtres qui acceptent un tableau de valeurs de chaîne, telles que In Query Function, qui contiennent des guillemets simples (apostrophe), tels que O'Brian ou alors Men's clothes, vous devez utiliser des guillemets doubles autour des valeurs. Par exemple :

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=Microsoft.Dynamics.CRM.In(PropertyName=@p1,PropertyValues=@p2)
&@p1='lastname'
&@p2=["OBrian","OBryan","O'Brian","O'Bryan"]

Sinon, vous obtiendrez l’erreur suivante : Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.

Si le filtre est pour une valeur unique, remplacez le guillemet simple par deux guillemets simples consécutifs. Par exemple :

GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
&$filter=lastname eq 'O''Bryan'

Sinon, vous obtiendrez une erreur comme la suivante : There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.

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 [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Agréger et regrouper les résultats

À l’aide de $apply vous pouvez agréger et regrouper vos données de manière dynamique. Cas d’utilisation possibles avec $apply :

Cas d’utilisation Exemple
Liste de statuts uniques dans la requête accounts?$apply=groupby((statuscode))
Somme agrégée de la valeur estimée opportunities?$apply=aggregate(estimatedvalue with sum as total)
Taille moyenne de la transaction basée sur la valeur et le statut estimés opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Somme de la valeur estimée selon le statut opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Revenu total d’opportunités par nom de compte opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Noms du contact principal pour les comptes dans « WA » accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Date et heure de l’enregistrement créé en dernier accounts?$apply=aggregate(createdon with max as lastCreate)
Date et heure de l’enregistrement créé en premier accounts?$apply=aggregate(createdon with min as firstCreate)

Les fonctions agrégées sont limitées à un ensemble de 50 000 enregistrements. Des informations supplémentaires sur l’utilisation de la fonctionnalité agrégée avec Dataverse se trouvent ici : Utiliser FetchXML pour créer une requête.

Des informations supplémentaires sur l’agrégation de données OData se trouvent ici : Extension OData pour la version 4.0 de l’agrégation de données. Notez que Dataverse prend en charge uniquement un sous-ensemble de ces méthodes agrégées.

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

Vous pouvez utiliser des alias de paramètres pour les options de requête système $filter et $orderby, mais actuellement pas à l’intérieur de l’option $expand. 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 [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
&$orderby=revenue asc,name desc
&$filter=revenue ne null

Avec alias de paramètre :

GET [Organization URI]/api/data/v9.2/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, consultez Utiliser les fonctions de l’API Web

Récupérer un nombre de lignes

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 de lignes dans le système. Il est limité par le nombre maximal de lignes pouvant être renvoyées. Pour plus d’informations : Limite le nombre de lignes renvoyées

Si vous souhaitez récupérer le nombre total de lignes pour une table au-delà de 5 000, utilisez la RetrieveTotalRecordCount Function.

L’annotation @odata.count de réponse contiendra le nombre de lignes jusqu’à 5 000 qui correspondent aux critères de filtre quelle que soit la limite de préférence odata.maxpagesize.

Si la valeur de comptage est 5 000 et que vous voulez savoir si le comptage est exactement de 5 000 ou supérieure à 5 000, vous pouvez ajouter l’en-tête Prefer``odata.include-annotations="Microsoft.Dynamics.CRM.*". Cela ajoutera les annotations suivantes au résultat : @Microsoft.Dynamics.CRM.totalrecordcount et @Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded.

Quand il est utilisé avec l’option de requête $count, et qu’il y a plus de 5 000 enregistrements, vous verrez ces valeurs :

"@odata.count": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,

S’il y a moins de 5 000 enregistrements, le nombre réel sera renvoyé.

"@odata.count": 58,
"@Microsoft.Dynamics.CRM.totalrecordcount": 58,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,

Si vous n’incluez pas l’option de requête $count, la valeur @Microsoft.Dynamics.CRM.totalrecordcount totale sera -1.

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.

Requête

GET [Organization URI]/api/data/v9.2/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
Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*"

Réponse

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.maxpagesize=3
Preference-Applied: odata.include-annotations="Microsoft.Dynamics.CRM.*"
  
{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(name)",
   "@odata.count":10,
   "@Microsoft.Dynamics.CRM.totalrecordcount": 5000,
   "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": true,
   "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":"[Organization URI]/api/data/v9.2/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 retourner aucune donnée sauf le nombre, vous pouvez appliquer $count à un ensemble pour obtenir uniquement la valeur. Vous ne pouvez pas appliquer l’en-tête Prefer: odata.include-annotations="Microsoft.Dynamics.CRM.*" dans ce cas, car le résultat est un nombre, pas une collection.

Requête

GET [Organization URI]/api/data/v9.2/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

Quand 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 [Organization URI]/api/data/v9.2/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"

Response

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":"[Organization URI]/api/data/v9.2/$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"
      }
   ]
}

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. Informations complémentaires : Extraire des tables associées avec une requête.

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. Informations complémentaires : Propriétés de recherche.

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é d’incident avec des annotations incluses.

Requête

GET [Organization URI]/api/data/v9.2/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="*"

Response

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
Preference-Applied: odata.include-annotations="*"  
  
{  
    "@odata.context":"[Organization URI]/api/data/v9.2/$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"
    }
}

Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes

La fonctionnalité de suivi des modifications vous permet de préserver la synchronisation des données efficacement en détectant les données qui ont changé depuis leur extraction initiale ou leur dernière synchronisation. Les modifications apportées aux entités peuvent être suivies à l’aide de requêtes de l’API Web en ajoutant odata.track-changes comme en-tête de préférence. L’en-tête de préférence odata.track-changes demande le renvoi d’un lien delta qui peut ultérieurement être utilisé pour récupérer les modifications d’entité.

Plus d’informations : Utiliser le suivi des modifications pour synchroniser les données avec les systèmes externes.

Comparaison de colonnes à l’aide de l’API Web

L’exemple suivant montre comment comparer des colonnes à l’aide de l’API Web :

https://<environment-root>/contacts?$select=firstname&$filter=firstname eq lastname

En savoir plus : Utiliser la comparaison des colonnes dans les requêtes

Voir aussi

Rechercher dans les données de la table à l’aide de la recherche Dataverse
Utilisation de la limite d’élément de recherche de la Recherche rapide
Exemples de données de requête d’API web (C#)
Exemple de données de requête de l’API web (Javascript côté client)
Effectuer des opérations à l’aide de l’API web
Composer des demandes Http et gérer les erreurs
Créer une table à l’aide de l’API web
Récupérer une table à l’aide de l’API web
Mettre à jour et supprimer des tables à l’aide de l’API Web
Associer et dissocier les tables à l’aide de l’API Web
Utiliser des fonctions API Web
Utiliser des actions API Web
Exécuter des opérations par lots à l’aide de l’API Web
Emprunter l’identité d’un autre utilisateur à l’aide de l’API Web
Effectuer les opérations conditionnelles à 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é).