API web de tables virtuelles

Lorsque vous utilisez l’API web Dataverse pour récupérer plusieurs enregistrements d’une table virtuelle, des paramètres de requête supplémentaires peuvent être inclus pour prendre en charge le tri, le filtrage et la pagination. Ces fonctionnalités ne sont pas prises en charge de manière uniforme dans les tables virtuelles des contrôles de collaboration, car elles s’appuient sur la prise en charge fournie par microsoft API Graph. Pour plus d’informations sur la prise en charge de chaque table virtuelle, consultez Informations de référence sur les entités de tables virtuelles.

Remarque

Actuellement, les contrôles collaboration sont disponibles uniquement dans la préversion publique pour les développeurs.

Tri de table virtuelle

Avec les tables virtuelles, vous pouvez utiliser le paramètre de requête OData $orderby pour définir des critères de tri du jeu de résultats. Utilisez le suffixe asc ou desc pour spécifier respectivement l’ordre croissant ou décroissant. La valeur par défaut est croissant si le suffixe n’est pas appliqué.

Tables prises en charge : chaque table virtuelle prend en charge la même fonctionnalité de tri que sa ressource Graph respective. Les tables virtuelles qui prennent en charge le tri sont les suivantes :

  • Élément de lecteur de graphe
  • Événement Graph

Remarque

Le tri n’est pas pris en charge sur tous les attributs des ressources Graph respectives. Si un utilisateur tente de trier sur une table virtuelle avec un attribut non pris en charge, ce jeu de résultats a son ordre par défaut. Il s’agit du même comportement que l’API web Dataverse sur les colonnes qui ne prennent pas en charge le tri.

Exemples :

  • GET [URI d’organisation]/api/data/v9.2/m365_graphdriveitems ?$filter=m365_collaborationrootid eq '0000000-0000-0000-0000-0000000000'&$orderby=m365_name desc
  • GET [URI d’organisation]/api/data/v9.2/m365_graphevents ?$filter=m365_groupid eq '0000000-0000-0000-0000-000000000000'$orderby=m365_subject asc

Filtrage de table virtuelle

Avec les tables virtuelles, vous pouvez utiliser le paramètre de requête OData $filter pour définir les critères pour lesquels les lignes sont retournées. Les tables virtuelles sont interrogées à l’aide des mêmes opérateurs OData pris en charge par l’API web Dataverse.

  • Opérateurs de comparaison

    Opérateur Description Exemple
    eq Égal $filter=m365_name eq 'Contoso'
    ne N’est pas égal à $filter=m365_name ne 'Contoso'
    gt Supérieur à $filter=m365_price gt 50.0
    ge Supérieur ou égal à $filter=m365_price ge 50.0
    lt Inférieur à $filter=m365_price lt 50.0
    le Inférieur ou égal à $filter=m365_price le 50.0
  • Opérateurs logiques

    Opérateur Description Exemple
    et AND logique $filter=m365_name eq 'Contoso' et m365_price eq 50.0
    ou OR logique $filter=m365_name ne 'Contoso' ou m365_price eq 50.0
    not Négociation logique $filter=not contains(m365_name,'Contoso')
  • Opérateurs de regroupement

    Opérateur Description Exemple
    ( ) Regroupement des priorités $filter=(m365_name eq 'Contoso' et m365_price eq 50.0) ou contains(m365_subject,'Team Sync')
  • Fonctions de requête

    Fonction Exemple
    contains $filter=contains(m365_name,'Contoso')
    endswith $filter=endswith(m365_name,'Contoso')
    startswith $filter=startswith(m365_name,'Contoso')

Tables prises en charge : chaque table virtuelle prend en charge la même fonctionnalité de filtrage que sa ressource Graph respective. Les tables virtuelles qui prennent en charge le filtrage sont les suivantes :

  • Rendez-vous de réservation de graphe
  • Élément de lecteur de graphe
  • Événement Graph

Remarque

Le filtrage n’est pas pris en charge sur tous les attributs des ressources Graph respectives. Si un utilisateur tente de filtrer sur une table virtuelle avec un attribut non pris en charge, ce filtre est ignoré. Il s’agit du même comportement que l’API web Dataverse sur les colonnes qui ne prennent pas en charge le filtrage.

Exemples :

  • GET [URI de l’organisation]/api/data/v9.2/m365_graphbookingappointments ?$filter=m365_bookingbusinessid eq 'ContosoBank@Contoso.onmicrosoft.com' et m365_price eq 100.0
  • GET [URI d’organisation]/api/data/v9.2/m365_graphdriveitems ?$filter=m365_collaborationrootid eq '0000000-0000-0000-0000-000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 m365_name eq 'Meeting Notes.docx'
  • GET [URI d’organisation]/api/data/v9.2/m365_graphevents ?$filter=m365_groupid eq '0000000-0000-0000-0000-000000000000000000000000000000000000000000000 m365_subject 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

Pagination de table virtuelle

La pagination est une ressource utile pour extraire un grand ensemble d’enregistrements. La pagination de table virtuelle peut être obtenue de trois manières différentes.

Vous pouvez spécifier la taille de page à l’aide de la valeur de odata.maxpagesize préférence dans l’en-tête de requête. Si le jeu de résultats s’étend sur plusieurs pages, la réponse inclut la @odata.nextLink propriété . Voici des exemples de demande et de réponse :

  GET [Organization URI]/api/data/v9.2/m365_graphdriveitems 
  Accept: application/json 
  Prefer: odata.maxpagesize=2 

Actuellement, les tables virtuelles suivantes prennent en charge la odata.maxpagesize préférence :

  • Rendez-vous de réservation de graphe
  • Événement de calendrier Graph
  • Lecteur de graphe
  • Élément de lecteur de graphe

Vous pouvez spécifier le nombre d’enregistrements à retourner en passant l’option $top dans l’URL. Si vous devez également spécifier le numéro de page, vous pouvez le faire en passant un cookie de pagination en tant qu’option $skiptoken sous forme de chaîne encodée xml. Pour extraire un numéro de page spécifique, vous pouvez passer le cookie de pagination au format suivant :

<cookie pagenumber=3 />

     GET [Organization URL]/api/data/v9.2/m365_graphevents?$top=2&$skiptoken=<cookie pagenumber='3' /> 

Remarque

La réponse n’inclut pas la @nextLink propriété . Si votre cas d’usage nécessite le renvoi du lien de page suivante, vous pouvez utiliser l’en-tête de préférence odata.maxpagesize décrit dans la section 1 au lieu de passer le paramètre URI $top.

Actuellement, les tables virtuelles suivantes prennent en charge l’extraction d’une page spécifique :

  • Rendez-vous de réservation de graphe
  • Événement de calendrier Graph

Vous pouvez passer un code XML d’extraction en tant que chaîne encodée au format XML. Avec l’option fetch XML, vous pouvez spécifier plusieurs préférences de requête. Les options spécifiques à la pagination sont page (numéro de page) et count (taille de page). Le code XML suivant spécifie le numéro et la taille de la page :

<fetch version="1.0" mapping="logical" returntotalrecordcount="true" page="<Page Number>" count="<Page Size>"></fetch>

GET [Organization URL]/api/data/v9.2/m365_graphevents?$fetchXml=<fetch version="1.0" mapping="logical" returntotalrecordcount="true" page="3" count="2"></fetch> 

Les tables virtuelles suivantes prennent en charge la propriété count à passer dans le cadre de l’option fetchXml :

  • Lecteur de graphe
  • Élément de lecteur de graphe

Les tables virtuelles suivantes prennent en charge la propriété page dans le cadre de l’option fetchXml :

  • Rendez-vous de réservation de graphe
  • Événement de calendrier Graph

Voir aussi