Obtenir la structure et le contenu OneNote

  • Article

S’applique à : blocs-notes consommateur sur OneDrive | Blocs-notes d’entreprise sur Microsoft Office 365

Pour obtenir du contenu et une structure OneNote à l’aide de l’API Microsoft Graph OneNote, vous envoyez une requête GET au point de terminaison cible. Par exemple :

GET ../onenote/pages/{id}

Si la demande réussit, Microsoft Graph renvoie un code d’état HTTP 200 OK et les entités ou le contenu que vous avez demandés. Les entités OneNote sont renvoyées sous forme d’objets JSON conformes à la spécification de la version 4.0 de OData.

Vous pouvez filtrer vos requêtes et améliorer les performances à l’aide des options de chaîne de requête.

Remarque

Si vous créez une solution qui prend en charge l’un des scénarios suivants, vous atteignez les limites de l’API OneNote :

  • Sauvegarder/restaurer des sections OneNote
  • Sauvegarder/restaurer des blocs-notes OneNote

Pour les opérations de sauvegarde et de restauration, consultez Meilleures pratiques pour la découverte des fichiers et la détection des modifications à grande échelle.

Construire l’URI de la requête

Pour construire l’URI de la requête, commencez avec l’URL racine du service :

https://graph.microsoft.com/v1.0/me/onenote

Ajoutez ensuite le point de terminaison de la ressource que vous souhaitez récupérer. (Les chemins d’accès aux ressources sont indiqués dans la section suivante.)

L’URI complète de votre requête ressemble à l’un de ces exemples :

  • https://graph.microsoft.com/v1.0/me/onenote/notebooks/{id}/sections
  • https://graph.microsoft.com/v1.0/me/onenote/notes/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?select=title,self

Remarque

En savoir plus sur l’URL racine du service.

Chemins d’accès aux ressources pour les requêtes GET

Utilisez les chemins d’accès aux ressources suivants pour obtenir des pages, sections, groupes de sections, blocs-notes et ressources d’image ou de fichier.

Collection de pages

Recherchez des pages (métadonnées) sur tous les blocs-notes.

../pages[?filter,orderby,select,expand,top,skip,count]

Recherchez des pages (métadonnées) dans une section spécifique.

../sections/{section-id}/pages[?filter,orderby,select,expand,top,skip,count,pagelevel]

L’ordre de tri par défaut pour les pages est lastModifiedTime desc.

La requête par défaut développe la section parent et sélectionne les propriétés id, name et self de la section.

Par défaut, seules les 20 premières entrées sont renvoyées pour les requêtes Obtenir des pages. Les requêtes qui ne spécifient pas une option de chaîne de requête top renvoient un lien @odata.nextLink dans la réponse que vous pouvez utiliser pour obtenir les 20 entrées suivantes.

Pour la collection de pages dans une section, utilisez pagelevel pour renvoyer le niveau de retrait des pages et leur ordre dans la section.

Exemple

GET ../sections/{section-id}/pages?pagelevel=true

Entité Page

Obtenez les métadonnées pour une page spécifique.

../pages/{page-id}[?select,expand,pagelevel]

Les pages peuvent développer les propriétés parentNotebook et parentSection.

La requête par défaut développe la section parent et sélectionne les propriétés id, name et self de la section.

Utilisez pagelevel pour renvoyer le niveau de retrait de la page et son ordre dans sa section parent.

Exemple

GET ../pages/{page-id}?pagelevel=true

Aperçu de la page

Recherchez le contenu texte et image de prévisualisation pour une page.

../pages/{page-id}/preview

La réponse JSON contient le contenu de prévisualisation, que vous pouvez utiliser pour aider les utilisateurs à identifier les éléments contenus dans la page.

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.PagePreview",
  "previewText":"text-snippet",
  "links":{
    "previewImageUrl":{
      "href":"https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png"
    }
  }
}

La propriété previewText contient un extrait de texte de la page. Microsoft Graph renvoie des phrases complètes, jusqu’à un maximum de 300 caractères.

Si la page comporte une image qui peut être utilisée pour créer une interface utilisateur de prévisualisation, la propriété href dans l’objet previewImageUrl contient un lien vers une ressource image publique. Vous pouvez utiliser ce lien dans du code HTML. Sinon, href renvoie la valeur null.

Exemple

<img src="https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png" />

Contenu HTML de la page

Recherchez le contenu HTML d’une page.

../pages/{page-id}/content[?includeIDs]

(en savoir plus sur le contenu HTML renvoyé)

Utilisez l’option de chaîne de requête includeIDs = true pour obtenir des ID générés utilisés pour mettre à jour la page.

Collection de sections

Recherchez toutes les sections de tous les blocs-notes appartenant à l’utilisateur, y compris les sections contenues dans des groupes de sections imbriqués.

../sections[?filter,orderby,select,top,skip,expand,count]

Recherchez toutes les sections qui sont directement sous un groupe de sections spécifique.

../sectionGroups/{sectiongroup-id}/sections[?filter,orderby,select,top,skip,expand,count]

Recherchez toutes les sections qui sont directement sous un bloc-notes spécifique.

../notebooks/{notebook-id}/sections[?filter,orderby,select,top,skip,expand,count]

Les sections peuvent développer les propriétés parentNotebook et parentSectionGroup.

L’ordre de tri par défaut pour les sections est name asc.

La requête par défaut développe le bloc-notes parent et le groupe de sections parent et sélectionne les propriétés id, name et self.

Entité Section

Recherchez une section spécifique.

../sections/{section-id}[?select,expand]

Les sections peuvent développer les propriétés parentNotebook et parentSectionGroup.

La requête par défaut développe le bloc-notes parent et le groupe de sections parent et sélectionne les propriétés id, name et self.

Collection de groupes de sections

Recherchez tous les groupes de sections de tous les blocs-notes appartenant à l’utilisateur, y compris les groupes de sections imbriqués.

../sectionGroups[?filter,orderby,select,top,skip,expand,count]

Recherchez tous les groupes de sections qui sont directement sous un bloc-notes spécifique.

../notebooks/{notebook-id}/sectionGroups[?filter,orderby,select,top,skip,expand,count]

Les groupes de sections peuvent développer les propriétés sections, sectionGroups, parentNotebook et parentSectionGroup.

L’ordre de tri par défaut pour les groupes de sections est name asc.

La requête par défaut développe le bloc-notes parent et le groupe de sections parent et sélectionne les propriétés id, name et self.

Entité SectionGroup

Recherchez un groupe de sections spécifique.

../sectionGroups/{sectiongroup-id}[?select,expand]

Les groupes de sections peuvent développer les propriétés sections, sectionGroups, parentNotebook et parentSectionGroup.

La requête par défaut développe le bloc-notes parent et le groupe de sections parent et sélectionne les propriétés id, name et self.

Collection de blocs-notes

Recherchez tous les blocs-notes appartenant à l’utilisateur.

../notebooks[?filter,orderby,select,top,skip,expand,count]

Les blocs-notes peuvent développer les propriétés sections et sectionGroups.

L’ordre de tri par défaut pour les bloc-notes est name asc.

Entité Notebook

Recherchez un bloc-notes spécifique.

../notebooks/{notebook-id}[?select,expand]

Les blocs-notes peuvent développer les propriétés sections et sectionGroups.

Ressource image ou autre ressource de fichier

Recherchez les données binaires d’une ressource spécifique.

../resources/{resource-id}/$value

Vous pouvez trouver l’URI de ressource du fichier dans le code HTML de sortie de la page.

Par exemple, une balise img inclut des points de terminaison pour l’image d’origine dans l’attribut data-fullres-src et l’image optimisée dans l’attribut src.

Exemple

<img 
    src="https://www.onenote.com/api/v1.0/me/notes/resources/{image-id}/$value"  
    data-src-type="image/png"
    data-fullres-src="https://www.onenote.com/api/v1.0/resources/{image-id}/$value"  
    data-fullres-src-type="image/png" ... />

Une balise object inclut le point de terminaison pour la ressource de fichier dans l’attribut data.

Exemple

<object
    data="https://www.onenote.com/api/v1.0/me/notes/resources/{file-id}/$value"
    data-attachment="fileName.pdf" 
    type="application/pdf" ... />

Remarque

L’obtention d’une collection de ressources n’est pas prise en charge.

Lorsque vous obtenez une ressource de fichier, vous n’avez pas besoin d’inclure un type de contenu Acceptdans la requête.

Pour plus d’informations sur les demandes GET, consultez les ressources suivantes dans la référence Microsoft Graph API REST :

Exemple de requêtes GET

Vous pouvez rechercher des entités OneNote pour obtenir uniquement les informations dont vous avez besoin. Les exemples suivants présentent certaines façons d’utiliser des options de chaîne de requête prises en charge dans des requêtes GET à Microsoft Graph.

Rappel :

  • toutes les requêtes GET commencent par l’URL racine du service.

    Exemples : https://www.onenote.com/api/v1.0/me/notes et https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

  • Les espaces dans la chaîne de requête d’URL doivent utiliser le codage %20.

    Exemple : filter=title%20eq%20'biology'

  • Les noms de propriété et les comparaisons de chaînes OData sont sensibles à la casse. Nous vous recommandons d’utiliser la fonction tolower OData pour les comparaisons de chaînes.

    Exemple : filter=tolower(name) eq 'spring'

filtre

Obtient toutes les pages créées par une application spécifique.

[GET] ../pages?filter=createdByAppId eq 'WLID-000000004C12821A'

select

Obtenez le titre, les liens du client OneNote et le lien contentUrl pour toutes les pages.

[GET] ../pages?select=title,links,contentUrl

expand

Obtenez tous les blocs-notes, puis développez les sections et les groupes de sections.

[GET] ../notebooks?expand=sections,sectionGroups

Obtenez un groupe de sections spécifique, puis développez les sections et les groupes de sections.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections,sectionGroups

Obtenez une page, puis développez sa section parent et son bloc-notes parent.

[GET] ../pages/{page-id}?expand=parentSection,parentNotebook

expand (plusieurs niveaux)

Obtenez tous les blocs-notes et développez leurs sections et groupes de sections, puis développez toutes les sections dans chaque groupe de sections.

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections)

Remarque

Le développement des parents d’entités enfant ou le développement d’enfants d’entités parent crée une référence circulaire et n’est pas pris en charge.

expand & select (plusieurs niveaux)

Obtenez le nom et le lien self d’un groupe de sections spécifique, puis obtenez le nom et les liens self de toutes ses sections.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections(select=name,self)&select=name,self

Obtenez le nom et le lien self de toutes les sections, puis obtenez le nom et l’heure de création du bloc-notes parent de chaque section.

[GET] ../sections?expand=parentNotebook(select=name,createdTime)&select=name,self

Obtenez le titre et l’ID de toutes les pages ; obtenez le nom de la section parent et du bloc-notes parent. 
[GET] ../pages?select=id,title&expand=parentSection(select=name),parentNotebook(select=name)

expand & levels (plusieurs niveaux)

Obtenez tous les blocs-notes, sections et groupes de sections.

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections,sectionGroups(levels=max;expand=sections))

filtre

Obtenez toutes les sections créées en octobre 2014.

[GET] ../sections?filter=createdTime ge 2014-10-01 and createdTime le 2014-10-31

Obtenez les pages créées par une application spécifique depuis le 1er janvier 2015.

[GET] ../pages?filter=createdByAppId eq 'WLID-0000000048118631' and createdTime ge 2015-01-01

filter et expand

Obtenez toutes les pages dans un bloc-notes spécifique. L’API renvoie 20 entrées par défaut.

[GET] ../pages?filter=parentNotebook/id eq '{notebook-id}'&expand=parentNotebook

Obtenez le nom et le lien pagesUrl de toutes les sections dans le bloc-notes School. Les comparaisons de chaînes OData sont sensibles à la casse, par conséquent, il est recommandé d’utiliser la fonction tolower.

[GET] ../notebooks?filter=tolower(name) eq 'school'&expand=sections(select=name,pagesUrl)

filter, select et orderby

Obtenez le nom et le lien pagesUrl de toutes les sections dont le nom contient le terme spring. Classez les sections par date de dernière modification.

[GET] ../sections?filter=contains(tolower(name),'spring')&select=name,pagesUrl&orderby=lastModifiedTime desc

orderby

Obtenez les 20 premières pages classées selon la propriété createdByAppId et par date de création la plus récente. L’API renvoie 20 entrées par défaut.

[GET] ../pages?orderby=createdByAppId,createdTime desc

filtre & haut

Obtenez les cinq pages les plus récentes créées depuis le 1er janvier 2015. L’API renvoie 20 entrées par défaut avec un maximum de 100. L’ordre de tri par défaut pour les pages est lastModifiedTime desc.

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5

filtre & & supérieur ignorer

Obtenez les cinq pages suivantes dans le jeu de résultats .

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=5

Et les cinq suivantes.

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=10

Remarque

Si top et filter sont appliqués à la même requête, les résultats incluent uniquement les entités qui correspondent aux deux critères.

select

Obtenez le nom, l’heure de création et le lien self de toutes les sections dans les blocs-notes de l’utilisateur.

[GET] ../sections?select=name,createdTime,self

Obtenez le titre, l’heure de création et les liens de client OneNote pour une page spécifique.

[GET] ../pages/{page-id}?select=title,createdTime,links

select & expand & filter (plusieurs niveaux)

Obtenez le nom et le lien pagesUrl de toutes les sections dans le bloc-notes par défaut de l’utilisateur.

[GET] ../notebooks?select=name&expand=sections(select=name,pagesUrl)&filter=isDefault eq true

top, select et orderby

Obtenez le titre et le lien self pour les 50 premières pages, classées par titre, par ordre alphabétique. L’API renvoie 20 entrées par défaut avec un maximum de 100. L’ordre de tri par défaut pour les pages est lastModifiedTime desc.

[GET] ../pages?top=50&select=title,self&orderby=title

skip, top, select et orderby

Obtenez les pages 51 à 100. L’API renvoie 20 entrées par défaut avec un maximum de 100.

[GET] ../pages?skip=50&top=50&select=title,self&orderby=title

Remarque

Les demandes GET pour les pages qui récupèrent le nombre d’entrées par défaut (autrement dit, elles ne spécifient pas d’expression supérieure ) retournent un lien @odata.nextLink dans la réponse que vous pouvez utiliser pour obtenir les 20 entrées suivantes.

Options de chaîne de requête OData prises en charge

Lorsque vous envoyez des requêtes GET à Microsoft Graph, vous pouvez utiliser les options de chaîne de requête OData pour personnaliser votre requête et obtenir simplement les informations dont vous avez besoin. Elles peuvent également améliorer les performances en réduisant le nombre d’appels au service et la taille de la charge utile de la réponse.

Remarque

Pour des raisons de lisibilité, les exemples de cet article n’utilisent pas l’encodage de %20 pour cent requis pour les espaces dans la chaîne de requête d’URL : filter=isDefault%20eq%20true

Option de requête Exemple et description
count

count=true

Décompte des entités de la collection. La valeur est renvoyée dans la propriété @odata.count de la réponse.
expand

expand=sections,sectionGroups

Les propriétés de navigation à renvoyer incorporées dans la réponse. Les propriétés suivantes sont prises en charge pour les expressions expand :
- Pages : parentNotebook, parentSection
- Sections : parentNotebook, parentSectionGroup
- Groupes de sections : sections, sectionGroups, parentNotebook, parentSectionGroup
- Blocs-notes : sections, sectionGroups

Par défaut, les requêtes GET de pages développent parentSection et sélectionnent les propriétés id, name et self de la section. Les requêtes GET par défaut pour les sections et groupes de sections développent à la fois parentNotebook et parentSectionGroup, puis sélectionnent les propriétés id, name et self des parents.

Utilisable pour une seule entité ou collection.
Séparez les propriétés multiples à l’aide de virgules.
Les noms des propriétés sont sensibles à la casse.
filtre

filter=isDefault eq true

Expression booléenne indiquant d’inclure ou non une entrée dans le jeu de résultats. Prend en charge les fonctions et opérateurs OData suivants :
- Opérateurs de comparaison : eq, ne, gt, ge, lt, le
- Opérateurs logiques : and, or, not
- Fonctions de chaîne : contains, endswith, startswith, length, indexof, substring, tolower, toupper, trim, concat

Les noms de propriété et les comparaisons de chaînes OData sont sensibles à la casse. Nous vous recommandons d’utiliser la fonction tolower OData pour les comparaisons de chaînes.

Exemple : filter=tolower(name) eq 'spring'
orderby

orderby=title,createdTime desc

Propriétés régissant l’ordre de tri, avec un ordre de tri facultatif asc (défaut) ou desc. Vous pouvez trier selon n’importe quelle propriété de l’entité dans la collection demandée.

L’ordre de tri par défaut pour les blocs-notes, les groupes de sections et les sections est name asc. Pour les pages, il s’agit de lastModifiedTime desc (en partant de la dernière page modifiée).

Séparez les propriétés par des virgules et indiquez-les dans l’ordre dans lequel vous souhaitez les appliquer. Les noms des propriétés sont sensibles à la casse.
select

select=id,title

Les propriétés à renvoyer. Utilisable pour une seule entité ou collection. Séparez les propriétés multiples à l’aide de virgules. Les noms des propriétés sont sensibles à la casse.
skip

skip=10

Nombre d’entrées à ignorer dans le jeu de résultats. Généralement utilisé pour obtenir des résultats de pagination.
top

top=50

Nombre d’entrées à renvoyer dans le jeu de résultats, jusqu’à un maximum de 100. La valeur par défaut est 20.

Microsoft Graph fournit également l’option de chaîne de requête pagelevel que vous pouvez utiliser pour obtenir le niveau et l’ordre des pages dans la section parent. S’applique uniquement aux requêtes pour les pages d’une section spécifique ou aux requêtes d’une page spécifique.

Exemples

  • GET ../sections/{section-id}/pages?pagelevel=true
  • GET ../pages/{page-id}?pagelevel=true

Fonctions et opérateurs OData pris en charge

Microsoft Graph prend en charge les fonctions et opérateurs OData suivants dans les expressions filter. Lorsque vous utilisez des expressions OData, gardez à l’esprit les points suivants :

  • Les espaces dans la chaîne de requête d’URL doivent être remplacés par le codage %20.

                  Exemple :filter=isDefault%20eq%20true

  • Les noms de propriété et les comparaisons de chaînes OData sont sensibles à la casse. Nous vous recommandons d’utiliser la fonction tolower OData pour les comparaisons de chaînes.

                  Exemple :filter=tolower(name) eq 'spring'

Opérateur de comparaison Exemple
eq
(égal à)		 createdByAppId eq '{app-id}'
ne
(différent de)		 userRole ne 'Owner'
gt
(supérieur à)		 createdTime gt 2014-02-23
ge
(supérieur ou égal à)		 lastModifiedTime ge 2014-05-05T07:00:00Z
lt
(inférieur à)		 createdTime lt 2014-02-23
le
(inférieur ou égal à)		 lastModifiedTime le 2014-02-23

Opérateur logique Exemple
et createdTime le 2014-01-30 and createdTime gt 2014-01-23
ou createdByAppId eq '{app-id}' or createdByAppId eq '{app-id}'
not not contains(tolower(title),'school')

Fonction de chaîne Exemple
contains contains(tolower(title),'spring')
endswith endswith(tolower(title),'spring')
startswith startswith(tolower(title),'spring')
length length(title) eq 19
indexof indexof(tolower(title),'spring') eq 1
substring substring(tolower(title),1) eq 'spring'
tolower tolower(title) eq 'spring'
toupper toupper(title) eq 'SPRING'
trim trim(tolower(title)) eq 'spring'
concat concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp'

Propriétés de l’entité OneNote

Les expressions de requête filter, select, expand et orderby peuvent inclure des propriétés des entités OneNote.

Exemple

../sections?filter=createdTime ge 2015-01-01&select=name,pagesUrl&orderby=lastModifiedTime desc

Les noms des propriétés sont sensibles à la casse dans les expressions de requête.

Pour la liste des propriétés et les types de propriété, consultez les ressources suivantes dans la référence Microsoft Graph API REST :

L’option de chaîne de requête expand peut être utilisée avec les propriétés de navigation suivantes :

  • Pages : parentNotebook, parentSection
  • Sections : parentNotebook, parentSectionGroup
  • Groupes de sections : sections, sectionGroups, parentNotebook, parentSectionGroup
  • Blocs-notes : sections, sectionGroups

Informations de la requête et de la réponse pour les requêtes GET

Données des requêtes Description
Protocole Toutes les demandes utilisent le protocole HTTPS SSL/TLS.
En-tête Authorization

Bearer {token}, où {token} est un jeton d’accès OAuth 2.0 valide pour votre application inscrite.

En cas de jeton manquant ou non valide, la requête échoue et le code d’état 401 s’affiche. Consultez l’article relatif à l’authentification et aux autorisations.
En-tête Accept

application/json pour les entités OneNote et les ensembles d’entités

text/html pour le contenu de page

Données de réponse Description
Code de succès Code d’état HTTP 200.
Corps de la réponse Une représentation OData de l’entité ou de l’ensemble d’entités défini au format JSON, la page HTML ou les données binaires de la ressource de fichier.
Erreurs En cas d’échec de la requête, l’API renvoie des erreurs dans l’objet @api.diagnostics dans le corps de la réponse.
En-tête X-CorrelationId GUID qui permet d’identifier la requête de manière unique. Vous pouvez utiliser cette valeur, ainsi que la valeur de l’en-tête Date, quand vous travaillez avec le Support Microsoft pour résoudre des problèmes.

Construction de l’URL racine du service des notes Microsoft Graph

L’URL racine des notes Microsoft Graph utilise le format suivant pour tous les appels effectués aux notes Microsoft Graph :

https://graph.microsoft.com/{version}/me/onenote/

Le segment version dans l’URL représente la version de Microsoft Graph que vous souhaitez utiliser. Utilisez v1.0 pour le code de production stable. Utilisez beta pour tester une fonctionnalité en cours de développement. Les fonctions et fonctionnalités en version bêta peuvent être sujettes à des modifications. Nous vous recommandons donc de ne pas les utiliser dans votre code de production.

Utilisez me pour le contenu OneNote auquel l’utilisateur actuel peut accéder (contenu propriétaire et partagé). Utilisez users/{id} pour le contenu OneNote que l’utilisateur spécifié (dans l’URL) a partagé avec l’utilisateur actuel. Utilisez Microsoft Graph pour obtenir les identifiants utilisateur.

Autorisations pour les requêtes GET

Pour obtenir créer la structure ou le contenu OneNote, demandez les autorisations appropriées.

Les étendues suivantes autorisent les requêtes GET à Microsoft Graph. Choisissez le niveau d’autorisation le plus faible requis par votre application pour faire son travail.

Choisissez parmi les autorisations suivantes :

  • Notes.read
  • Notes.ReadWrite
  • Notes.ReadWrite.All

Pour en savoir plus sur les étendues d’autorisation et leur fonctionnement, consultez l’article Référence des autorisations de Microsoft Graph.

Contenu connexe