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 :

Ressources EntitySet

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

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>
   [
}

Astuce

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

Par exemple, commencez par la ressource accounts EntitySet pour récupérer des données à partir du type de l’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 les données depuis le type d’entité du compte lorsqu’un utilisateur spécifique est le OwningUser, vous pouvez utiliser la user_accounts propriété de navigation à valeur de collection depuis l’enregistrement systemuser spécifié.

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 les données d’une collection, envoyez une GET demande à la ressource de la collection. L’exemple suivant illustre la récupération des données depuis le type d’entité de compte.

Cet exemple illustre é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.
Tables de jointure Spécifiez les tables associées à renvoyer dans les résultats.
Lignes de commande Spécifiez l’ordre de tri des lignes à renvoyer.
Lignes de filtre Spécifiez les lignes de données à renvoyer.
Résultats sur la page Spécifiez le nombre de lignes de données à renvoyer avec chaque requête.
Données agrégé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. Tables de jointure
$orderby Demandez des ressources dans un ordre particulier. Lignes de commande
$filter Filtrez une collection de ressources. Lignes de filtre
$apply Agrégez et regroupez vos données. Données agrégé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 d’accès 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. Découvrir comment utiliser les fonctions de l’API web

Options de requête OData non compatibles

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

Limites de longueur d’URL

La longueur d’une URL dans une requête GET 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 effectuer une opération $batch à l’aide d’une demande POST comme un moyen de déplacer les options de demande OData hors de l’URL et dans le corps de la demande où cette limite est deux fois plus longue. 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 limitez le nombre de lignes renvoyées, utilisez l’option de demande OData $top. Sans cette limite, Dataverse renvoie jusqu’à 5 000 lignes.

Sinon, spécifiez un certain nombre d’enregistrements à renvoyer en utilisant la pagination. N’utilisez pas $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 que OData ne prend pas en charge.

Outils de la communauté

Note

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 à effectuer de nombreuses opérations à l’aide de l’API web Dataverse, notamment la composition de requêtes.

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

Fonctionnalités d’OData version 4.0

L’API web Dataverse est un service OData version 4.0. 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ée par l’API web Dataverse et comment vous pouvez l’utiliser pour récupérer des données commerciales depuis Dataverse.

Note

La version 4.01 d’OData est la dernière version. Elle inclut des améliorations et des fonctionnalités supplémentaires qui ne sont pas disponibles dans la version 4.0 et qui ne sont donc pas actuellement disponibles dans l’API web Dataverse.

Étapes suivantes

Découvrez comment sélectionner les colonnes.

Sélectionner des colonnes