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

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

• Ressources EntitySet : l’une des collections de l’API Web EntitySet .
• Collections filtrées : un ensemble d’entités renvoyées par une propriété de navigation à valeur de collection pour un enregistrement spécifique.
• Une propriété de navigation à valeur de collection étendue.
• Une collection renvoyée par une fonction.

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

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 :

• Pour toutes les tables et relations de Dataverse, vous pouvez vérifier le Web API Entity Type Reference
• Pour toutes les tables personnalisées ou Relations, recherchez les propriétés de navigation à valeur de collection dans le document de service $metadata

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 :

• Limitation des colonnes renvoyées à l’aide de $select. En savoir plus sur la sélection des colonnes
• Tri des résultats à l’aide de $orderby. En savoir plus sur la commande des colonnes
• Limitation des lignes renvoyées à l’aide de $top. En savoir plus sur la limitation du nombre de lignes
• Affichage des valeurs formatées à l’aide de l’en-tête de requête : Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue". En savoir plus sur les valeurs formatées

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.

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.

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.

• Vous ne pouvez pas joindre des tables sans aucune relation. OData permet uniquement d’utiliser l’option de requête pour joindre des tables à l’aide des propriétés de navigation qui font partie du Relations dans le modèle de données. $expand

• Limitations d’agrégation répertorie les limitations suivantes pour les agrégations utilisant OData :

  • Obtenez un numéro distinct avec CountColumn
  • Fuseau horaire lors du regroupement par date
  • Agrégation de lignes
  • Limite par requête

• Effectuez des comparaisons croisées de colonnes de tableaux. OData prend en charge le filtrage sur les valeurs de colonne de la même ligne, mais elles doivent se trouver dans la même table.

• Vous n’avez pas besoin de remplacer l’ordre de tri par défaut pour les colonnes de choix. Le comportement par défaut lors du tri des colonnes de choix consiste à utiliser les valeurs entières plutôt que la valeur d’étiquette localisée.

• Vous ne pouvez pas utiliser l’optimisation des performances de la requête Late Materialise .

Outils de la communauté

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 :

• OData version 4.0. Partie 1 : Protocole plus Errata 03 11.2 Demande de données
• OData version 4.0. Partie 2 : Conventions d’URL et errata 03 5 Options de requête

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.

Étapes suivantes

Découvrez comment sélectionner les colonnes.