Meilleures pratiques d’utilisation de l’API OneNote dans Microsoft Graph

Cet article fournit des recommandations pour utiliser les API OneNote dans Microsoft Graph. Ces recommandations sont basées sur les réponses aux questions courantes sur Microsoft Q&A et Twitter.

Utiliser $select pour sélectionner l’ensemble minimal de propriétés dont vous avez besoin

Lorsque vous exécutez une requête pour une ressource (par exemple, des sections à l’intérieur d’un bloc-notes), vous faites une requête semblable à celle qui se trouve ci-dessous.

GET ~/notebooks/{id}/sections

Elle récupère toutes les propriétés des sections. Cependant, vous n’avez pas forcément besoin de toutes les propriétés. Vous pouvez utiliser le paramètre de requête $select pour renvoyer uniquement les propriétés de votre choix, comme illustré dans l’exemple suivant.

GET ~/notebooks/{id}/sections?$select=id,displayName

La même approche s’applique aux autres API OneNote.

Utiliser $expand au lieu d’effectuer plusieurs appels d’API

Supposons que vous souhaitiez récupérer l’ensemble des blocs-notes, sections et groupes de sections d’un utilisateur dans une vue hiérarchique. Vous pouvez procéder ainsi :

• Appelez GET ~/notebooks pour obtenir la liste de blocs-notes.

• Pour chaque bloc-notes récupéré, appelez GET ~/notebooks/{notebookId}/sections pour récupérer la liste des sections.

• Pour chaque bloc-notes récupéré, appelez GET ~/notebooks/{notebookId}/sectionGroups pour récupérer la liste des groupes de sections.

• Vous pouvez éventuellement parcourir de manière récursive les groupes de sections.

Bien que cette méthode fonctionne (avec quelques allers-retours réguliers supplémentaires vers le service), il existe une meilleure approche, qui consiste à utiliser le paramètre de requête $expand.

GET ~/notebooks?$expand=sections,sectionGroups($expand=sections)

Cela produit les mêmes résultats en un aller-retour réseau, avec de meilleures performances.

Après avoir obtenu toutes les pages pour un utilisateur, répéter l’opération pour chaque section séparément

Même si Microsoft Graph fournit un point de terminaison pour récupérer toutes les pages, il existe un meilleur moyen d’obtenir toutes les pages auxquelles l’utilisateur a accès. Lorsque l’utilisateur a trop de sections, il peut rencontrer des délais d’expiration ou des mauvaises performances. Il est préférable de parcourir chaque section, et d’obtenir les pages pour chacune d’entre elles séparément.

Par exemple, au lieu d’utiliser cet appel (cette API est appelée, vous ne pourrez donc pas récupérer toutes les pages à la fois) :

GET ~/pages

Il est préférable d’utiliser l’appel suivant plusieurs fois (en particulier si vous n’avez pas besoin de toutes les sections) :

GET ~/sections/{id}/pages

Lorsque vous obtenez les métadonnées de la page, remplacez le classement lastModifiedDateTime par défaut. Il est plus facile d’obtenir les pages lorsque vous n’avez pas besoin de les trier par lastModifiedDateTime. Pour ce faire, vous pouvez les trier par n’importe quelle autre propriété. Par exemple :

GET ~/sections/{id}/pages?$select=id,title,createdDateTime&$orderby=createdDateTime