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 webEntitySet.
• Collections filtrées : un ensemble d’entités renvoyées par une propriété de navigation avec une valeur de collection pour un enregistrement spécifique.
• Une propriété de navigation avec une valeur de collection étendue.
• Collection renvoyée par une fonction.

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

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 :

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

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 :

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

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

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

• Vous ne pouvez pas utiliser de $expand imbriquées avec des relations N :N.

• 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 d’une même ligne, mais elles doivent se trouver dans la même table.

• Vous ne devez pas 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 à 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 :

• OData version 4.0. Partie 1 : Protocol Plus Errata 03 11.2 Demande de données
• OData version 4.0. Partie 2 : Conventions URL Plus 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ée par l’API web Dataverse et comment vous pouvez l’utiliser pour récupérer des données commerciales depuis Dataverse.

Étapes suivantes

Découvrez comment sélectionner les colonnes.