Partager via

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

  • Article

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

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

Cette requête 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.

Cette approche fonctionne (avec quelques allers-retours séquentiels supplémentaires vers le service) ; Toutefois, une meilleure approche consiste à utiliser le paramètre de $expand requête.

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

Cette approche produit les mêmes résultats en un seul 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

Microsoft Graph expose un point de terminaison pour récupérer toutes les pages ; Toutefois, nous vous déconseillons d’utiliser ce point de terminaison pour obtenir toutes les pages à laquelle l’utilisateur a accès. Lorsque l’utilisateur a trop de sections et qu’une tentative d’obtention de toutes les pages est effectuée, l’appel génère un code 400 d’état HTTP et le message suivant : « Le nombre maximal de sections est dépassé pour cette requête. Pour obtenir des pages pour les comptes comportant un nombre élevé de sections, nous vous recommandons d’obtenir des pages pour une section à la fois. » Pour plus d’informations sur ce code d’erreur, consultez Codes d’erreur OneNote.

Pour obtenir toutes les pages auxquelles un utilisateur a accès, la meilleure pratique consiste à effectuer des appels distincts pour obtenir les pages de chaque section.

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 (surtout 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 rapide d’obtenir des 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