Copier les blocs-notes, sections et pages

  • Article

S'applique aux : Bloc-notes d'entreprise sur Office 365 uniquement

Pour copier un bloc-notes, une section ou une page OneNote, vous envoyez une requête POST au point final d'action respectif de la copie. Par exemple :

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

Envoyez un objet de modification JSON dans le corps du message. Si la demande aboutit, l'API OneNote renvoie un code d'état 202 HTTP et une en-tête Opération-Localisation. Ensuite, vous pouvez interroger le point de terminaison de l'opération pour le résultat.

Notes

La fonctionnalité de copie est actuellement prise en charge pour les bloc-notes personnels, de site et de groupe Office 365, mais pas pour les ordinateurs portables grand public sur OneDrive.

Construire l’URI de la requête

  1. Pour construire l'URI de requête, commencez par l'URL racine du service pour votre plateforme :

    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/

  2. Ajouter le point de terminaison de lacopie respective :

    Copier une page dans une section

    ../pages/{id}/copyToSection

    Copier une section vers un bloc-notes

    ../sections/{id}/copyToNotebook

    Copier une section vers un groupe de sections

    ../sections/{id}/copyToSectionGroup

    Copier un bloc-notes

    ../notebooks/{id}/copyNotebook

Le bloc-notes est copié dans le dossier Notebooks de la bibliothèque Documents de destination. Le dossier Notebooks est créé s'il n'existe pas.

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

https://www.onenote.com/api/v1.0/me/notes/sections/{id}/copyToNotebook

https://www.onenote.com/api/v1.0/users/{id}/notes/sections/{id}/copytosectiongroup

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/pages/{id}/copyToSection

https://www.onenote.com/api/v1.0/groups/{id}/notes/notebooks/{id}/copyNotebook

Notes

En savoir plus sur l’URL racine du service.

Construction du corps du message

Dans le corps du message, envoyez un objet JSON contenant les paramètres dont votre opération a besoin. Il est possible d'envoyer un corps vide si aucun paramètre n'est nécessaire.

Paramètre Description
id L'ID du bloc-notes ou du groupe de sections de destination (pour les sections) ; ou l'ID de la section de destination (pour les pages).

Utilisé avec copyToNotebook, copyToSectionGroup, et copyToSection seulement.
siteCollectionId L'ID de la collection de sites SharePoint qui contient le site sur lequel copier l'élément.

Utilisé avec ID du siteet utilisé uniquement lors de la copie sur un site SharePoint.
siteId L'ID du site SharePoint dans lequel copier l'élément.

Utilisé avec siteCollectionIdet utilisé uniquement lors de la copie sur un site SharePoint.
groupId L'ID du groupe vers lequel copier l'élément.

Utilisé uniquement lors de la copie à un groupe unifié.
renameAs Le nom de la copie.

Utilisé avec copyNotebook, copyToNotebook, et copyToSectionGroup seulement. Par défaut, le nom de l'élément existant.

Apprendre à obtenir un cahier, un groupe de sections et des identifiants de section et obtenir la collection de sites et les ID de site. Pour plus d'informations sur l'obtention des ID de groupe, voir Documentation de l'API Azure AD Graph.

Exemple de flux pour une opération de copie

Vous envoyez d'abord une requête PUBLICATION à l'actioncopie sur l'élément que vous voulez copier. Vous pouvez copier à partir de blocs-notes auxquels l'utilisateur a accès (possédés ou partagés) tant que la source et la destination sont dans le même client.

L'exemple suivant copie un bloc-notes personnel sur un site d'équipe SharePoint. La demande ne comprend pas le paramètre renameAs, de sorte que le nouveau bloc-notes utilise le nom existant.

POST https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copyNotebook
Authorization: Bearer {token}
Content-Type: application/json 

{
  "siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
  "siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}

Notes

Les opérations de copie respectent les autorisations du bloc-notes source, de sorte que l'utilisateur authentifié doit pouvoir accéder au bloc-notes source afin de le copier. Cependant, les copies ne conservent pas les autorisations de la source. La copie a des autorisations comme si l'utilisateur venait de le créer.

Si la demande aboutit, l'API OneNote renvoie un code d'état 202 HTTP et une entête Opération-Emplacement. Voici un extrait de la réponse :

HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
...

Ensuite, vous interrogez le point de terminaison Opération-Emplacement pour obtenir le statut de l'opération de copie :

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
Authorization: Bearer {token}
Accept: application/json

L'API OneNote renvoie un objet OperationModel qui montre l'état actuel. L'exemple de réponse suivant est renvoyé lorsque l'état est terminé.

{
  "@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
  "id":"copy-1c5be75c-e7db-4219-8145-a2d6c3f171a33ec9f3da-2b24-4fb1-a776-fe8c8cd1410f",
  "status":"completed",
  "createdDateTime":"2015-09-16T17:32:07.048Z",
  "lastActionDateTime":"2015-09-16T17:32:17.7777639Z",
  "resourceLocation":"https://www.onenote.com/api/v1.0/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
  "resourceId":null,"
  "error":null
}

Le statut peut être terminé, en fonctionnement, ou échoué.

  • Si terminé, la propriété resourceLocation contient le point de terminaison de ressource pour la nouvelle copie.
  • Si en fonctionnement, la propriétépercentComplete affiche le pourcentage approximatif complété.
  • Si échoué, les propriétésErreur et @ api.diagnostics fournissent des informations d'erreur.

Vous pouvez interroger le point de terminaison de l'opération jusqu'à ce que l'opération soit terminée ou échouée.

Informations sur les requêtes et les réponses

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 enregistrée.

S’il est absent ou non valide, la requête échoue avec un code d’état 401. Consultez l’article relatif à l’authentification et aux autorisations.
En-tête Content-Type application/json
En-tête Accept application/json


Données de réponse Description
Code de succès Un code d'état HTTP de statut 202.
En-tête Operation-Localisation L'URL à interroger pour le statut de l'opération.

L'interrogation du point de terminaison de l'opération renvoie un objet OperationModel qui contient le statut de l'opération et d'autres informations.
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.

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

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

  • 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 du contenu OneNote dans un site au niveau du client auquel est connecté l’actuel utilisateur. 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 unifiés

    • Les groupes unifiés (également appelés 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. Les groupes unifiés sont le seul type de groupe 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 requête

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 requêtes 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 copier des bloc-notes, des sections et des pages OneNote, vous devez demander les autorisations appropriées. Choisissez le niveau d’autorisations le plus bas dont votre application a besoin pour faire son travail.

Plate-forme Étendue d’autorisation
Grand public office.onenote_create, office.onenote_update_by_app, office.onenote_update
Entreprise Notes.Create, Notes.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.

Voir aussi