Créer des pages OneNote

  • Article

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

Quand vous créez une page OneNote, vous envoyez une requête POST au point de terminaison pages: Par exemple :

POST ../notes/sections/{id}/pages

Envoyez le code HTML qui définit la page dans le corps du message. Si la requête réussit, Microsoft Graph renvoie un code d’état HTTP 201.

Remarque

Pour en savoir plus sur les demandes POST que vous pouvez envoyer pour créer des sections, des groupes de sections et des blocs-notes, consultez notre référence REST interactive.

Construction de l’URI de la requête

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

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

Ensuite, ajoutez le point de terminaison pages :

  • Créer une page dans n’importe quelle section (spécifiée par son nom)

    .../pages?sectionName=DefaultSection

  • Créer une page dans n’importe quelle section (spécifiée par son ID)

    .../sections/{section-id}/pages

Si vous créez des pages dans le bloc-notes personnel de l’utilisateur, Microsoft Graph fournit également des points de terminaison que vous pouvez utiliser pour créer des pages dans le bloc-notes par défaut :

  • Créer une page dans la section par défaut du bloc-notes par défaut

    ../pages

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

  • https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework

En savoir plus sur l’URL racine du service.

Utiliser le paramètre d’URL sectionName

Les règles suivantes s’appliquent quand vous utilisez le paramètre sectionName pour créer une page dans une section nommée dans le bloc-notes par défaut :

  • Seules les sections de niveau supérieur peuvent être référencées (pas les sections dans les groupes de sections).

  • Si une section avec le nom spécifié n’existe pas dans le bloc-notes par défaut, l’API la crée. Ces caractères ne sont pas autorisés pour les noms de section : ? * \ / : < > | & # " % ~

  • Les noms de section ne respectent pas la casse pendant la mise en correspondance, mais la casse est respectée pour la création des sections. Ainsi, « Ma Nouvelle Section » sera affichée tel quel, alors que « ma nouvelle section » devra correspondre dans les requêtes POST suivantes.

  • Les noms de section doivent être encodés au format URL. Par exemple, les espaces doivent être encodés sous la forme %20.

  • Le paramètre sectionName est uniquement valide avec l’itinéraire ../notes/pages (et non, ../notes/sections/{id}/pages).

Comme les sections sont créées quand elles n’existent pas, il est plus sûr d’utiliser cet appel pour les pages créées par votre application. Les utilisateurs peuvent renommer les sections. Toutefois, l’API crée une section avec le nom de section spécifié.

Remarque

Les liens retournés par l’API pour les pages d’une section renommée continueront d’atteindre ces pages plus anciennes.

Construction du corps du message

Le code HTML qui définit le contenu de la page est appelé Code HTML d’entrée. Le code HTML d’entrée prend en charge un sous-ensemble de code HTML et CSS standard, ainsi que des attributs personnalisés. (Les attributs personnalisés, tels que data-id et data-render-src, sont décrits dans l’article relatif au code HTML d’entrée et de sortie.)

Envoyez le code HTML d’entrée dans le corps du message de la requête POST. Vous pouvez envoyer le code HTML d’entrée directement dans le corps du message à l’aide du application/xhtml+xml type de contenu ou text/html , ou vous pouvez l’envoyer dans la partie « Présentation » d’une requête en plusieurs parties.

L’exemple suivant envoie le code HTML d’entrée directement dans le corps du message.

POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: application/xhtml+xml

<!DOCTYPE html>
<html>
  <head>
    <title>A page with a block of HTML</title>
    <meta name="created" content="2015-07-22T09:00:00-08:00" />
  </head>
  <body>
    <p>This page contains some <i>formatted</i> <b>text</b> and an image.</p>
    <img src="https://..." alt="an image on the page" width="500" />
  </body>
</html>

Si vous envoyez des données binaires, utilisez une requête en plusieurs parties.

Remarque

Pour simplifier la programmation et la cohérence dans votre application, vous pouvez utiliser les requêtes en plusieurs parties pour créer toutes les pages. Nous vous recommandons d’utiliser une bibliothèque pour construire des messages en plusieurs parties. Cela vous évite de créer des charges utiles incorrectes.

Exigences et limitations concernant le code HTML d’entrée dans les requêtes de pages POST

Quand vous envoyez le code HTML d’entrée, tenez compte de ces exigences et limitations :

  • Le code HTML d’entrée doit être du XHTML bien formé et encodé au format UTF-8. Toutes les balises de début du conteneur doivent avoir des balises de fermeture correspondantes. Toutes les valeurs d’attribut doivent être entourées de guillemets doubles ou simples.

  • Le code JavaScript, les fichiers inclus et le code CSS sont supprimés.

  • Les formulaires HTML sont supprimés dans leur intégralité.

  • Microsoft Graph prend en charge un sous-ensemble d’éléments HTML.

  • Microsoft Graph prend en charge un sous-ensemble d’attributs HTML courants et un ensemble d’attributs personnalisés, tel que l’attribut data-id utilisé pour mettre à jour des pages. Consultez l’article relatif au code HTML d’entrée et de sortie pour connaître les attributs pris en charge.

Code HTML et CSS pris en charge dans les pages OneNote

Seuls certains éléments, attributs et propriétés sont pris en charge (au format HTML4, XHTML, CSS, HTML5, etc.). Microsoft Graph accepte un ensemble limité de codes HTML mieux adaptés à l’utilisation qui est faite de OneNote. Pour en savoir plus, consultez la page relative à la prise en charge des balises HTML dans les pages. Si une balise n’est pas répertoriée, elle sera probablement ignorée.

La liste suivante décrit les types d’élément de base pris en charge par Microsoft Graph :

  • <head> et <body>
  • <title> et <meta> qui définissent le titre de la page et la date de création
  • <h1> à <h6> pour les en-têtes de section
  • <p> pour les paragraphes
  • <ul>, <ol> et <li> pour les listes et éléments de liste
  • <table>, <tr> et <td>, y compris les tableaux imbriqués
  • <pre> pour le texte déjà mis en forme (conserve les espaces et les sauts de ligne)
  • <b> et <i> pour les styles de caractères gras et italique

Microsoft Graph conserve la structure sémantique et la structure de base du code HTML d’entrée quand il crée des pages, mais il convertit le code HTML d’entrée pour utiliser l’ensemble pris en charge de codes HTML et CSS. Les fonctionnalités qui n’existent pas dans OneNote ne peuvent pas être converties. Ainsi, elles risquent de ne pas être reconnues dans le code HTML source.

Exemple de requête

Cet exemple de requête en plusieurs parties crée une page qui contient des images et un fichier incorporé. La partie Présentation requise contient le code HTML d’entrée qui définit la page. La partie imageBlock1 contient les données d’image binaires et fileBlock1 contient les données de fichier binaires. Les parties de données peuvent également contenir du code HTML. Dans ce cas, Microsoft Graph restitue le code HTML sous forme d’image sur la page OneNote.

POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: multipart/form-data; boundary=MyPartBoundary198374

--MyPartBoundary198374
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html

<!DOCTYPE html>
<html>
  <head>
    <title>A page with rendered images and an attached file</title>
    <meta name="created" content="2015-07-22T09:00:00-08:00" />
  </head>
  <body>
    <p>Here's an image from an <i>online source</i>:</p>
    <img src="https://..." alt="an image on the page" width="500" />
    <p>Here's an image uploaded as <b>binary data</b>:</p>
    <img src="name:imageBlock1" alt="an image on the page" width="300" />
    <p>Here's a file attachment:</p>
    <object data-attachment="FileName.pdf" data="name:fileBlock1" type="application/pdf" />
  </body>
</html>

--MyPartBoundary198374
Content-Disposition:form-data; name="imageBlock1"
Content-Type:image/jpeg

... binary image data ...

--MyPartBoundary198374
Content-Disposition:form-data; name="fileBlock1"
Content-Type:application/pdf

... binary file data ...

--MyPartBoundary198374--

Pour consulter d’autres exemples qui vous montrent comment créer des pages contenant des images et d’autres fichiers, consultez l’article relatif à l’ajout d’images et de fichiers, nos didacticiels et nos exemples. Découvrez également comment créer des éléments ayant une position absolue, utiliser des balises de note et extraire des données pour des captures de carte de visite, des recettes en ligne et des listes de produits.

Microsoft Graph est strict concernant certains formats, notamment les sauts de ligne CRLF présents dans le corps d’un message en plusieurs parties. Pour éviter de créer des charges utiles incorrectes, utilisez une bibliothèque pour construire des messages en plusieurs parties.

Si vous recevez un code d’état 400 pour une charge utile incorrecte, consultez la mise en forme des sauts de ligne et des espaces, et vérifiez qu’il n’y ait aucun problème de codage. Par exemple, essayez d’utiliser charset=utf-8 (exemple : Content-Type: text/html; charset=utf-8).

Consultez les sections relatives aux exigences et limitations concernant le code HTML d’entrée et aux limites de taille des requêtes POST.

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

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 Content-Type

text/html ou application/xhtml+xml pour le contenu HTML, pour indiquer s’il est envoyé directement dans le corps du message ou dans la partie « Présentation » requise des requêtes en plusieurs parties.

Utilisez des requêtes en plusieurs parties quand vous envoyez des données binaires, et utilisez le type de contenu multipart/form-data; boundary=part-boundary, où {part-boundary} est une chaîne qui signale le début et la fin de chaque partie de données.
En-tête Accept application/json

Données de réponse Description
Code de succès Code d’état HTTP 201
Corps de la réponse Représentation OData de la nouvelle page au format JSON.
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 Location URL de ressource pour la nouvelle page.
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 Microsoft Graph

L’URL racine du service Microsoft Graph utilise le format suivant pour tous les appels à 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.

Limitations de taille de section OneNote

Il existe une limite au nombre de pages que vous pouvez ajouter à une section à l’aide de l’API OneNote. Lorsque cette limite est atteinte dans une section et qu’une tentative est effectuée pour créer une page dans cette section, une réponse avec le code d’état HTTP 507 et le message « A dépassé le nombre maximal de pages autorisé par section » s’affichent. Pour plus d'informations sur ce code d'erreur, consultez les Codes d'erreur OneNote.

Vous pouvez utiliser l'une des solutions de contournement suivantes :

  • Créez une section et y ajouter de nouvelles pages.
  • Supprimer les pages inutilisées d’une section existante ayant atteint la limite de pages.

Autorisations

Pour créer des pages OneNote, demandez les autorisations appropriées. Choisissez le niveau d’autorisation le plus faible requis par votre application pour faire son travail.

Choisissez parmi les autorisations suivantes :

  • Notes.Create
  • 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