Mettre à jour le contenu de page OneNote

  • Article

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

Pour mettre à jour le contenu d’une page OneNote, vous envoyez une requête PATCH au point de terminaison content de la page :

PATCH ../notes/pages/{id}/content

Envoyez un objet de modification JSON dans le corps du message. Si la requête réussit, Microsoft Graph renvoie un code d’état HTTP 204.

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 content de la page :

  • Obtenez la page HTML et toutes les valeurs data-id

    ../pages/{id}/content

  • Obtenez la page HTML, toutes les valeurs data-id et toutes les valeurs id générées

    ../pages/{page-id}/content?includeIDs=true

Les valeurs data-id et id sont utilisées comme identificateurs cible pour les éléments à mettre à jour.

L’URI complète de votre requête ressemble à ceci :

https://graph.microsoft.com/v1.0/me/onenote/pages/{id}/content

En savoir plus sur l’URL racine du service.

Construction du corps du message

Le code HTML d’une page OneNote contient du texte, des images et d’autres contenus organisés en structures comme les éléments div, img et ol. Pour mettre à jour le contenu d’une page OneNote, vous ajoutez et remplacez des éléments HTML sur la page.

Vos modifications sont envoyées sous forme de tableau d’objets de modification JSON dans le corps du message. Chaque objet spécifie l’élément cible, le nouveau contenu HTML et l’action à effectuer sur le contenu.

Le tableau suivant définit deux modifications. La première insère une image au-dessus d’un paragraphe en tant que frère, et la seconde ajoute un élément à une liste en tant que dernier enfant.

Remarque

Lors de la mise à jour d’une image sur une page OneNote, vous ne pouvez pas utiliser les liens www. Le service n’essaiera pas de télécharger des ressources aléatoires. Au lieu de cela, l’image doit faire partie de la requête, soit par image-data-URL, soit par partie-nom d’une requête en plusieurs parties.

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-data-url-or-part-name" alt="Image above the target paragraph" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the end of the list</li>'
  }
]

Consultez d’autres exemples.

Attributs pour les objets de modification JSON

Utilisez les attributs target, action, position et content pour définir des objets JSON pour des requêtes PATCH.

target

Élément à mettre à jour. La valeur doit être un des identificateurs suivants :

Identifier Description
#{data-id}

Cet ID (facultatif) est défini sur des éléments dans le code d’entrée HTML lors de la création d’une page ou de la mise à jour d’une page. Ajoutez le préfixe # à la valeur.

Exemple :
'target':'#intro' cible l’élément <div data-id="intro" ...>
id

Il s’agit de l’ID généré à partir de Microsoft Graph qui est requis pour la plupart des opérations de remplacement. N’ajoutez pas le préfixe #.

Exemple :
'target':'div:{33f8a2...}{37}' cible l’élément <div id="div:{33f8a2...}{37}" ...>

Ne les confondez pas avec les valeurs id définies dans le code d’entrée HTML. Toutes les valeurs id envoyées dans le code d’entrée HTML sont abandonnées.
body Mot clé qui cible le premier élément div sur la page. N’ajoutez pas le préfixe #.
title Mot clé qui cible le titre de page. N’ajoutez pas le préfixe #.

action

Action à effectuer sur l’élément cible. Voir les actions prises en charge pour les éléments.

Opération Description
append

Ajoute le contenu fourni à la cible en tant que premier ou dernier enfant, tel que déterminé par l’attribut position.

S’applique uniquement aux éléments body, div, ol et ul.
insert Ajoute le contenu fourni en tant que frère avant ou après la cible, tel que déterminé par l’attribut position.
prepend

Ajoute le contenu fourni à la cible en tant que premier enfant. Raccourci pour append + before.

S’applique uniquement aux éléments body, div, ol et ul.
replace

Remplace la cible avec le contenu fourni.

La plupart des actions replace requièrent l’utilisation de l’ID généré pour la cible (à l’exception des éléments img et object dans un div, qui prennent aussi en charge l’utilisation de data-id).

Position

Emplacement où ajouter le contenu fourni, par rapport à l’élément cible. S’il n’est pas défini, la valeur par défaut est after.

Position Description
after (par défaut)

Avec append : le dernier enfant de l’élément cible.

Avec insert : le frère suivant de l’élément cible.
before

Avec append : le premier enfant de l’élément cible.

Avec insert : le frère précédent de l’élément cible.

contenu

Chaîne de code HTML bien formé à ajouter à la page et toutes les données binaires image ou fichier. Si le contenu contient des données binaires, la requête doit être envoyée à l’aide du type de contenu multipart/form-data avec un composant « Commandes » (consultez un exemple).

Identifiants générés

Microsoft Graph génère des valeurs id pour les éléments sur la page qui peuvent être mis à jour. Pour obtenir des ID générés, utilisez l’expression de chaîne de requête includeIDs=true dans votre requête GET :

GET ../notes/pages/{page-id}/content?includeIDs=true

Remarque

L’API ignore toutes les valeurs d’ID définies dans le code HTML d’entrée des requêtes create-page et update-page.

L’exemple suivant affiche les identifiants générés pour un paragraphe et une image dans le code HTML de sortie d’une page.

<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>
<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />

Les valeurs id peuvent changer après la mise à jour d’une page, donc vous devez obtenir les valeurs actuelles avant de créer une requête PATCH qui les utilise.

Vous pouvez spécifier les éléments cibles en utilisant la valeur de data-id ou id, comme suit :

  • Pour les actions append et insert, vous pouvez utiliser indifféremment l’un des deux identifiants en tant que valeur cible.
  • Pour les actions replace, vous devez utiliser l’ID généré pour tous les éléments à l’exception du titre de page et des images et des objets dans un élément div.
    • Pour remplacer un titre, utilisez le mot clé titre.
    • Pour remplacer des images et des objets dans un élément div, utilisez data-id ou id.

L’exemple suivant utilise la valeur id pour la cible. N’utilisez pas le préfixe # avec un ID généré.

[
   {
    'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
    'action':'insert',
    'position':'before',
    'content':'<p>This paragraph goes above the target paragraph.</p>'
  }
]

Actions et éléments pris en charge

De nombreux éléments sur la page peuvent être mis à jour, mais chaque type d’élément prend en charge des actions spécifiques. Le tableau suivant répertorie les éléments cible pris en charge et les actions de mise à jour qu’ils prennent en charge.

Élément Remplacement Ajouter un enfant Insérer un frère
body
(cible la première balise div de la page)		 Non oui Non
div
(avec une position absolue)		 Non oui Non
div
(dans une balise div)		 oui
(id uniquement)		 oui oui
img, object
(dans une balise div)		 oui Non oui
ol, ul oui
(id uniquement)		 oui oui
table oui
(id uniquement)		 Non oui
p, li, h1-h6 oui
(id uniquement)		 Non oui
title oui Non Non

Les éléments suivants ne prennent pas en charge les actions de mise à jour.

Exemples de requête

Une requête de mise à jour contient une ou plusieurs modifications représentées par des objets de modification JSON. Ces objets peuvent définir des cibles différentes sur la page et des actions et du contenu différents pour les cibles.

Les exemples suivants incluent des objets JSON utilisés dans les requêtes PATCH et exécutent des requêtes PATCH :

Ajouter des éléments enfant

L’action append ajoute un enfant à un élément body, div (à l’intérieur d’une balise div), ol ou ul. L’attribut position détermine si l’enfant doit être ajouté avant ou après la cible. La position par défaut est after.

Ajouter un élément à une balise div

L’exemple suivant ajoute deux nœuds enfant à l’élément div1. Il ajoute une image en tant que premier enfant et un paragraphe comme dernier enfant.

[
 {
    'target':'#div1',
    'action':'append',
    'position':'before',
    'content':'<img data-id="first-child" src="image-url-or-part-name" />'
  },
  {
    'target':'#div1',
    'action':'append',
    'content':'<p data-id="last-child">New paragraph appended to the div</p>'
  }
]

Ajouter un élément à l’élément body

Vous pouvez utiliser la cible body comme un raccourci pour ajouter un élément enfant à l’intérieur de la première balise div sur n’importe quelle page.

L’exemple suivant ajoute deux paragraphes en tant que premier enfant et le dernier enfant à la première balise div sur la page. N’utilisez pas de # avec la cible body. Cet exemple utilise l’action prepend comme raccourci pour append + before.

[
  {
    'target':'body',
    'action':'prepend',
    'content':'<p data-id="first-child">New paragraph as first child in the first div</p>'
  },
  {
    'target':'body',
    'action':'append',
    'content':'<p data-id="last-child">New paragraph as last child in the first div</p>'
  }
]

Ajouter un élément à une liste

L’exemple suivant ajoute un élément de liste en tant que dernier enfant de la liste de cibles. La propriété list-style-type est définie, car l’élément utilise un style de liste qui n’est pas celui par défaut.

[
  {
    'target':'#circle-ul',
    'action':'append',
    'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
  }
]

Insérer des éléments frère

L’action insert ajoute un frère à l’élément cible. L’attribut position détermine si le frère est inséré avant ou après la cible. La position par défaut est after. Consultez les éléments qui prennent en charge insert.

Insérer des frères

L’exemple suivant ajoute deux nœuds frères et sœurs à la page. Il ajoute une image au-dessus de l’élément para1 et un paragraphe en dessous de l’élément para2.

[
  {
     'target':'#para1',
     'action':'insert',
     'position':'before',
     'content':'<img src="image-data-url-or-part-name" alt="Image inserted above the target" />'
  },
  {
    'target':'#para2',
     'action':'insert',
     'content':'<p data-id="next-sibling">Paragraph inserted below the target</p>'
  }
]

Remplacer des éléments

Vous pouvez utiliser soit data-id, soit l’id généré en tant que valeur cible pour remplacer les éléments img et object qui se trouvent dans une balise div. Pour remplacer un titre de page, utilisez le mot clé titre. Pour tous les autres éléments qui prennent en charge replace, vous devez utiliser l’ID généré.

Remplacer une image

L’exemple suivant remplace une image par une balise div en utilisant la valeur data-id de l’image comme cible.

[
  {
    'target':'#img1',
    'action':'replace',
    'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
  }
]

Mettre à jour un tableau

Cet exemple montre comment mettre à jour un tableau en utilisant son identifiant généré. Le remplacement des éléments tr et td n’est pas pris en charge, mais vous pouvez remplacer l’intégralité du tableau.

[
  {
    'target':'table:{de3e0977-94e4-4bb0-8fee-0379eaf47486}{11}',
    'action':'replace',
    'content':'<table data-id="football">
      <tr><td><p><b>Brazil</b></p></td><td><p>Germany</p></td></tr>
      <tr><td><p>France</p></td><td><p><b>Italy</b></p></td></tr>
      <tr><td><p>Netherlands</p></td><td><p><b>Spain</b></p></td></tr>
      <tr><td><p>Argentina</p></td><td><p><b>Germany</b></p></td></tr></table>'
  }
]

Modifier le titre

Cet exemple illustre comment modifier le titre d’une page. Pour modifier le titre, utilisez le mot clé titre en tant que valeur cible. N’utilisez pas de # avec la cible de titre.

[
  {
    'target':'title',
    'action':'replace',
    'content':'New title'
  }
]

Mettre à jour un élément de tâche

L’exemple suivant utilise l’action replace pour définir l’élément d’une case à cocher de tâche sur Terminé.

[
  {
    'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
    'action':'replace',
    'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
  }
]

Consultez Utiliser les balises de note pour en savoir plus sur l’utilisation de l’attribut data-tag.

Exemples de requêtes PATCH complètes

Les exemples suivants illustrent des requêtes PATCH complètes.

Requête avec du contenu texte uniquement

L’exemple suivant illustre une requête PATCH qui utilise le type de contenu application/json. Vous pouvez utiliser ce format lorsque votre contenu ne contient pas de données binaires.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-data-url" alt="New image from a URL" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

Demande en plusieurs parties avec contenu binaire

L’exemple suivant illustre une requête PATCH en plusieurs parties qui inclut des données binaires. Les requêtes en plusieurs parties requièrent un composant « Commandes » qui spécifie le type de contenu application/json et contient le tableau des objets de modification JSON. D’autres composants de données peuvent contenir des données binaires. Les noms des composants sont généralement des chaînes ajoutés avec l’heure actuelle en millisecondes ou un GUID aléatoire.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: multipart/form-data; boundary=PartBoundary123
Authorization: Bearer {token}

--PartBoundary123
Content-Disposition: form-data; name="Commands"
Content-Type: application/json

[
  {
    'target':'img:{2998967e-69b3-413f-a221-c1a3b5cbe0fc}{42}',
    'action':'replace',
    'content':'<img src="name:image-part-name" alt="New binary image" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

--PartBoundary123
Content-Disposition: form-data; name="image-part-name"
Content-Type: image/png

... binary image data ...

--PartBoundary123--

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

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

application/json pour le tableau des objets de modification JSON, qu’il soit envoyé directement dans le corps du message ou dans le composant « Commandes » requis 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.

Données de réponse Description
Code de succès Un code d'état HTTP 204. Aucune donnée JSON renvoyée pour une requête PATCH.
Erreurs Consultez l’article Codes d’erreur pour les API OneNote dans Microsoft Graph pour en savoir plus sur les erreurs OneNote renvoyées par Microsoft Graph.

Construction de l’URL racine du service Microsoft Graph

L’URL racine du service OneNote utilise le format suivant pour tous les appels à OneNote API :

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 changer. 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é). users/{id} est pour le contenu OneNote que l’utilisateur spécifié (dans l’URL) a partagé avec l’utilisateur actuel. Utilisez l’API utilisateurs.

Remarque

Vous pouvez obtenir des ID utilisateur en effectuant une requête GET sur https://graph.microsoft.com/v1.0/users.

Autorisations

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

  • Notes.ReadWrite
  • Notes.ReadWrite.All

Pour en savoir plus sur les étendues d’autorisation et leur fonctionnement, consultez la section relative aux étendues d’autorisation dans OneNote.

Contenu connexe