Partager via

Interroger des données à l’aide d’OData

  • Article

Chaque requête commence par une collection d’entités. Les collections d’entités peuvent être :

EntitySet ressources

Pour trouver toutes les EntitySet ressources disponibles dans votre environnement, envoyez une GET requête au document de service Web API :

Demande :

GET [Organization URI]/api/data/v9.2/
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",
    "value": [
        {
            "name": "aadusers",
            "kind": "EntitySet",
            "url": "aadusers"
        },
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
      ... <Truncated for brevity>
   [
}

Conseil

Ces valeurs sont généralement le nom pluriel de la table, mais elles peuvent être différentes. Utilisez les résultats de cette demande pour confirmer que vous utilisez le nom de ressource correct. EntitySet

Par exemple, commencez par la ressource accounts EntitySet pour récupérer les données du type d’entité de compte.

GET [Organization URI]/api/data/v9.2/accounts

Collections filtrées

Vous pouvez interroger n’importe quelle collection d’entités représentée par une propriété de navigation avec une valeur de collection d’un enregistrement donné. Par exemple, si vous souhaitez récupérer des données à partir du type d’entité de compte où un utilisateur spécifique est le OwningUser , vous pouvez utiliser la propriété de navigation à valeur de collection de l’enregistrement systemuser spécifié. user_accounts ...

GET [Organization URI]/api/data/v9.2/systemusers(<systemuserid value>)/user_accounts?$select=name

Pour trouver le nom de la propriété de navigation avec une valeur de collection :

Récupérer des données

Pour récupérer des données d’une collection, envoyez une GET requête à la ressource de collection. L’exemple suivant montre la récupération de données à partir du type d’entité de compte.

Cet exemple démontre également :

Demande :

GET [Organization URI]/api/data/v9.2/accounts?$select=name,statecode,statuscode&$orderby=name&$top=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": "[Organization URI]/api/data/v9.2/$metadata#accounts(name,statecode,statuscode)",
   "value": [
      {
         "@odata.etag": "W/\"112430907\"",
         "name": "A. Datum Corporation (sample)",
         "statecode@OData.Community.Display.V1.FormattedValue": "Active",
         "statecode": 0,
         "statuscode@OData.Community.Display.V1.FormattedValue": "Active",
         "statuscode": 1,
         "accountid": "4b757ff7-9c85-ee11-8179-000d3a9933c9"
      }
   ]
}

Affiner votre requête

Après avoir sélectionné la table avec laquelle démarrer votre requête, affinez la requête pour obtenir les données nécessaires. Les articles suivants expliquent comment compléter votre requête.

Article Tâche
Sélectionner des colonnes Spécifiez les colonnes de données à renvoyer.
Joindre des tables Spécifiez les tables associées à renvoyer dans les résultats.
Trier des lignes Spécifiez l’ordre de tri des lignes à renvoyer.
Filtrer des lignes Spécifiez les lignes de données à renvoyer.
Paginer les résultats Spécifiez le nombre de lignes de données à renvoyer avec chaque requête.
Agréger des données Découvrez comment regrouper et agréger les données renvoyées.
Compter le nombre de lignes Découvrez comment obtenir un décompte du nombre de lignes renvoyées.
Optimisations des performances Découvrez comment optimiser les performances

Options de requête OData

Utilisez ces options pour modifier les résultats renvoyés par une collection. La table suivante décrit les options de requête OData prises en charge par l’API web Dataverse.

Option Utilisation Plus d’informations
$select Demandez un ensemble spécifique de propriétés pour chaque entité ou type de complexe. Sélectionner des colonnes
$expand Spécifiez les ressources connexes à inclure dans la liste des ressources extraites. Joindre des tables
$orderby Demandez des ressources dans un ordre particulier. Trier des lignes
$filter Filtrez une collection de ressources. Filtrer des lignes
$apply Agrégez et regroupez vos données. Agréger des données
$top Spécifiez le nombre d’éléments de la collection interrogée à inclure dans le résultat. Limiter le nombre de lignes
$count Demandez un décompte des ressources correspondantes incluses dans les ressources de la réponse. Compter le nombre de lignes

Pour appliquer plusieurs options, séparez les options de requête du chemin de la ressource par un point d’interrogation (?). Séparez chaque option après la première par une esperluette (&). Les noms des options respectent la casse.

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

Vous pouvez utiliser des alias de paramètres pour les options de requête $filter et $orderby, mais 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. Apprenez à utiliser les fonctions de l’API Web

Options de requête OData non prises en charge

L’ Dataverse API Web ne prend pas en charge les options de requête OData suivantes : $skip,$search,$format.

Limitations de longueur d’URL

La longueur d’une URL dans une GET requête est limitée à 32 Ko (32 768 caractères). L’inclusion de nombreuses options de requête OData complexes en tant que paramètre dans l’URL peut atteindre la limite. Vous pouvez exécuter une opération à l’aide d’une requête afin de déplacer les options de requête OData hors de l’URL et dans le corps de la requête où la limite est deux fois plus longue. $batch POST L’envoi d’une requête GET dans $batch autorise les URL d’une longueur maximale de 64 Ko (65 536 caractères). En savoir plus sur les opérations par lots à l’aide de l’API Web.

Limiter le nombre de lignes

Pour limiter le nombre de lignes renvoyées, utilisez l’option de requête OData. $top Sans cette limite, Dataverse renvoie jusqu’à 5 000 lignes.

Sinon, spécifiez un certain nombre d’enregistrements à renvoyer en utilisant la pagination. Ne pas utiliser $top lorsque vous demandez des pages de données. Découvrez comment demander des résultats paginés

Limitations

Il y a certaines choses que vous pouvez faire en utilisant FetchXml mais qu’OData ne prend pas en charge.

Outils de la communauté

Notes

Les outils créés par la communauté ne sont pas pris en charge par Microsoft. Si vous avez des questions ou des problèmes avec les outils de la communauté, contactez l’éditeur de l’outil.

Le Dataverse REST Builder est un projet open source qui fournit une interface utilisateur qui vous aide à faire de nombreuses choses à l’aide de l’ Dataverse API Web, notamment la composition de requêtes.

Le XrmToolBox FetchXMLBuilder est un outil gratuit pour composer et tester des requêtes FetchXml, mais il génère également du code pour les requêtes OData en utilisant la même expérience de conception.

Fonctionnalités de la version OData 4.0

L’API Web est un service OData version 4.0. Dataverse Ces sections de la spécification OData 4.0 décrivent comment récupérer des données :

Cet article et les autres articles de cette section décrivent les parties de la spécification OData 4.0 implémentées par l’ Dataverse API Web et comment vous pouvez l’utiliser pour récupérer des données métier à partir de Dataverse.

Notes

La version OData 4.01 est la dernière version. Il inclut des améliorations et des fonctionnalités supplémentaires non disponibles dans la version 4.0 et donc actuellement non disponibles dans l’API Web. Dataverse

Étapes suivantes

Découvrez comment sélectionner les colonnes.

Sélectionner des colonnes

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