Table of contents
TOC
Réduire la table des matières
Développer la table des matières
Dernière mise à jour: 25/07/2018

Mettez à jour le contenu de la page OneNote

S’applique à : blocs-notes consommateur sur OneDrive | Blocs-notes d’entreprise sur 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 aboutit, OneNote API renvoie un code de statut HTTP 204.

Construisez l’URI de la requête

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

Blocs-notes sur OneDrive
https://www.onenote.com/api/v1.0/me/notes/

Blocs-notes sur OneDrive Entreprise
https://www.onenote.com/api/v1.0/me/notes/
https://www.onenote.com/api/v1.0/users/{id}/notes/

Blocs-notes de site SharePoint
https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

Blocs-notes de groupe unifiés
https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/


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

L' id de données et les valeurs d' id sont utilisés comme identifiants cible pour les éléments que vous souhaitez mettre à jour.


Votre URI de requête complet ressemblera à l'un de ceux-ci :

https://www.onenote.com/api/v1.0/me/notes/pages/{id}/content

https://www.onenote.com/api/v1.0/myorganization/sitecollections/{id}/sites/{id}/notes/pages/{id}/content

https://www.onenote.com/api/v1.0/myorganization/groups/{id}/notes/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.

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-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.

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

IdentificateurDescription
#{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

C'est l' ID généré à partir de OneNote API, et est requis pour la plupart des opérations de remplacement. Ne pas préfixer avec un #.

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.

bodyMot clé qui cible le premier élément div sur la page. N’ajoutez pas le préfixe #.
titreMot 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.

ActionDescription
ajoutez

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.

insérezAjoute le contenu fourni en tant que frère avant ou après la cible, tel que déterminé par l’attribut position.
ajoutez avant

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.

remplacez

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).

poste
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 est après.

PosteDescription
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.

avant

- 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

OneNote API génère des valeurs d' id pour les éléments de 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

L'API rejette toutes les valeurs id définies dans l' entrée HTML des requêtes de création et de mise à jour de 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émentRemplacementAjouter un enfantInsérer un frère
body
(cible la première balise div de la page)
NonouiNon
div
(avec une position absolue)
NonouiNon
div
(dans une balise div)
oui (id uniquement)ouioui
img, objet
(dans une balise div)
ouiNonoui
ol, uloui (id uniquement)ouioui
tableoui (id uniquement)Nonoui
p, li, h1-h6oui (id uniquement)Nonoui
titreouiNonNon

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  |  Insérer des éléments frères  |  Remplacer des éléments  |  Exécuter 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>'
  }
]

Ajoutez à l'élément corps

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 préfixer comme un raccourci pour ajouter + avant.

[
  {
    '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ères

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-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 le remplacement, 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 montre comment changer 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 titre.

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

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

L'exemple suivant utilise l'action de remplacement pour remplacer un élément de boîte de contrôle de tâche par un état terminé.

[
  {
    'target':'#task1',
    '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://www.onenote.com/api/v1.0/me/notes/pages/{page-id}/content

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

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

Requête multi-parties avec contenu binaire
L'exemple suivant montre une requête PATCH multi-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://www.onenote.com/api/v1.0/me/notes/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êtesDescription
ProtocoleToutes 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 enregistrée.

S’il est absent ou non valide, la requête échoue avec un code d’état 401. Consultez Authentification et 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 composant de données.

Données de réponseDescription
Code de succèsCode d’état HTTP 204. Aucune donnée JSON renvoyée pour une requête PATCH.
ErreursSi la requête de mise à jour échoue, l'API renvoie des erreurs dans l'objet @api.diagnostics dans le corps de la réponse. La requête échouera si :
- L'objet JSON contient des attributs non valides ou est mal formé.
- Les attributs cible, action, ou contenu sont manquants.
- L’élément cible n’existe pas.
- Le format de la valeur cible est non valide. Exemple, un id de données n'est pas préfixé avec un #.
- L’élément cible ne prend pas en charge l’action spécifiée.
- La valeur action ou poste est non valide.
En-tête X-CorrelationIdUn GUID qui identifie la requête de manière unique. Vous pouvez utiliser cette valeur avec la valeur de l'en-tête Date lorsque vous utilisez le support Microsoft pour résoudre les problèmes.

Construction de l'URL racine du service OneNote

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

https://www.onenote.com/api/{version}/{location}/notes/


Le segment version dans l’URL représente la version de OneNote API que vous souhaitez utiliser.

  • Utilisez v1.0 pour du 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.


Le segment location dans l’URL représente la localisation des blocs-notes auxquels vous souhaitez accéder.

Blocs-notes sur OneDrive (grand public)
Utilisez me pour le contenu OneNote auquel l’utilisateur actuel peut accéder (contenu propriétaire et partagé).

Blocs-notes sur OneDrive Entreprise
Utilisez me pour le contenu OneNote appartenant à l’utilisateur actuel.

Utilisez users/{id} pour le contenu OneNote que l’utilisateur spécifié (dans l’URL) a partagé avec l’utilisateur actuel. Utilisez l’API de Azure AD Graph pour obtenir les ID utilisateurs.

Blocs-notes de sites SharePoint
Les sites d’équipe et d’autres sites SharePoint peuvent contenir des blocs-notes OneNote dans leurs bibliothèques de documents.

Utilisez myOrganization/siteCollections/{id}/sites/{id} pour le contenu OneNote sur un site du client auquel l’utilisateur actuel est connecté. Seul le client actuel est pris en charge et accessible en utilisant le mot-clé myOrganization. En savoir plus sur l’obtention des ID de sites.

Blocs-notes de groupe Office 365
Les groupes Office 365 font partie de l’expérience connectée Office 365. Les membres du groupe peuvent partager des blocs-notes, des fichiers et des e-mails.

Utilisez myOrganization/groups/{id} pour le contenu OneNote dans le groupe spécifié dont l’utilisateur actuel est membre. Seul le type de groupe Office 365 (qui renvoie le groupType unified) est pris en charge. Utilisez l’API de Azure AD Graph pour obtenir les ID de groupes.


Utilisez la méthode FromUrl pour obtenir la collection de sites et les ID de sites

Vous pouvez utiliser la méthode FromUrl pour obtenir la collection de sites et les ID de sites pour une URL de site absolue spécifiée. Vous devez effectuer cet appel uniquement lorsque cela est nécessaire, puis stocker les valeurs pour une utilisation ultérieure.

Le format de l’URL de site dépend de votre configuration, par exemple https://domain.sharepoint.com/site-a ou https://domain.com/sites/site-a.

Exemple de demande :

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')
Authorization: Bearer {token}
Accept: application/json

Exemple de réponse :

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata",
  "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5",
  "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"
}

Conditions préalables à l’utilisation de FromUrl et pour travailler avec des blocs-notes de sites SharePoint :

  • Vous pouvez uniquement créer des blocs-notes, des groupes de sections, des sections et des pages OneNote sur des sites disposant d’une bibliothèque de documents par défaut. (Certains modèles de sites ne créent pas de bibliothèque de documents par défaut.) Toutefois, les demandes GET renvoient le contenu OneNote de toutes les bibliothèques de documents sur le site.
  • L’URL racine du service OneNote n’est pas modifiable, ce qui signifie que vous ne pouvez pas utiliser un chemin d’accès au site de l’API REST SharePoint et ensuite y coller le point de terminaison notes.
  • L’utilisateur au nom duquel vous appelez doit être membre du site.
  • FromUrl fonctionne uniquement avec les sites qui ont été indexés. L’indexation d’un nouveau site peut prendre plusieurs heures.

Autorisations

Pour mettre à jour des pages OneNote, demandez les autorisations appropriées. Choisissez le niveau d’autorisations le plus bas dont votre application a besoin pour faire son travail.

PlateformeÉtendue d’autorisation
Grand publicoffice.onenote_update_by_app, office.onenote_update
EntrepriseNotes.ReadWrite.CreatedByApp, 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.

Ressources supplémentaires

© 2018 Microsoft