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

Gérer les autorisations sur les entités OneNote

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

Vous pouvez utiliser le point de terminaison des autorisations pour gérer les autorisations de lecture ou d'écriture des blocs-notes, groupes de sections et sections.

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

La gestion des permissions 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 requête

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/


Ajoutez ensuite le chemin d'accès au bloc-notes, groupe de sections ou entité de section cible, suivi des autorisations ou du point de terminaison des autorisations / {id}.

Votre requête URI complète ressemblera à ces exemples :

https://www.onenote.com/api/v1.0/me/notes/notebooks/{id}/permissions/{id}

https://www.onenote.com/api/v1.0/users/{id}/notes/sectiongroups/{id}/permissions

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

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/sections/{id}/permissions/{id}

En savoir plus sur l’URL racine du service.

Créer ou mettre à jour les autorisations

Pour créer ou mettre à jour les autorisations d'un bloc-notes, d'un groupe de sections ou d'une section, envoyez une requête POST au point de terminaison approprié. Vous pouvez créer ou mettre à jour une seule autorisation par requête.

Les autorisations sont appliquées à toutes les entités OneNote le long de la chaîne d'héritage.

Vous pouvez mettre à jour les autorisations pour accorder un accès plus permissif. Pour restreindre l'accès, vous devez cependant supprimer l'autorisation existante et créer une nouvelle autorisation. Voir Héritage d'autorisation et précédence.

Créer ou mettre à jour les autorisations pour un bloc-notes

POST ../notebooks/{notebook-id}/permissions

Créer ou mettre à jour les autorisations pour un groupe de sections

POST ../sectiongroups/{sectiongroup-id}/permissions

Créer ou mettre à jour les autorisations pour une section

POST ../sections/{section-id}/permissions

Dans le corps du message, envoyez un objet JSON avec les paramètres requis.

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}
ParamètreDescription
userRoleLe type d' autorisation : Owner, Contributor, ou Reader.
userIdLe nom de connexion de l'utilisateur ou du groupe auquel attribuer l'autorisation. L'API accepte le format de revendications qui inclut le nom du fournisseur d'appartenance (*i: 0 # .f

Exemples

La requête suivante crée une autorisation pour le bloc-notes spécifié.

Requête

POST ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "userRole": "Owner", 
    "userId": "i:0#.f|membership|alexd@domainname.com"
}

Réponse

HTTP/1.1 201 Created

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions/$entity",
  "userRole":"Owner",
  "userId":"i:0#.f|membership|alexd@domainname.com",
  "name":"Alex Darrow",
  "id":"1-23",
  "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
}

Informations sur les requêtes et les réponses

Les informations suivantes s'appliquent aux requêtes POST /permissions.

Données des requêtesDescription
ProtocoleToutes les demandes utilisent le protocole HTTPS SSL/TLS.
En-tête d’autorisation

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

S'il est manquant ou non valide, la demande échoue avec un code d'état 401. Voir Authentification avec Azure AD (applications d'entreprise).

Étendue d’autorisationNotes.ReadWrite.CreatedByApp, Notes.ReadWrite ou Notes.ReadWrite.All
Données de réponseDescription
Code de succèsUn code d'état HTTP 201.
Corps de la réponseUne représentation OData de l'autorisation au format JSON. Voir Obtenir des autorisations pour une description d'un objet d'autorisation.
ErreursSi la requête échoue, l'API renvoie les erreurs dans le corps de la réponse.
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 faites appel au support Microsoft pour résoudre les problèmes.

Obtenir des autorisations

Pour obtenir les autorisations d'un bloc-notes, d'un groupe de sections ou d'une section, envoyez une requête GET au point de terminaison approprié.

Obtenir des autorisations pour un bloc-notes

GET ../notebooks/{notebook-id}/permissions

Obtenir une autorisation spécifique pour un bloc-notes

GET ../notebooks/{notebook-id}/permissions/{permission-id}

Obtenir des autorisations pour un groupe de sections

GET ../sectiongroups/{sectiongroup-id}/permissions

Obtenir une autorisation spécifique pour un groupe de sections

GET ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Obtenir des autorisations pour une section

GET ../sections/{section-id}/permissions

Obtenir une autorisation spécifique pour une section

GET ../sections/{section-id}/permissions/{permission-id}


Les requêtes GET renvoient l'autorisation la plus élevée pour un rôle d'utilisateur sur l'entité cible. Pour plus d'informations, voir Héritage d'autorisation et précédence.

GET /permissions les requêtes prennent en charge les options de requête OData, comme suit :

GET ../permissions[?filter,orderby,select,top,skip,count]

GET ../permissions/{permission-id}[?select]

Le point de terminaison des autorisations ne prend pas en charge l'option de requête expand.

Pour en savoir plus sur l'obtention d'entités OneNote, y compris les options de chaînes de requête prises en charge et des exemples, voir Obtenir le contenu et la structure OneNote.

Objet d'autorisation

Une autorisation contient les propriétés suivantes.

PropriétéDescription
nomReprésente le nom d'affichage de l’utilisateur ou de l'entité de sécurité. Exemple : "name":"Everyone"
identifiantL'identifiant unique de l'autorisation, dans le formulaire 1-{principal-member-id}. Exemple : "id":"1-4"
selfL'URL de l'objet d'autorisation.
userIdLe nom de connexion de l'utilisateur ou du groupe auquel l'autorisation est attribuée. Cette valeur est toujours renvoyée dans le format des revendications, par exemple : *i:0 #.f
userRoleLe type d' autorisation : Owner, Contributor, ou Reader.

Exemples

La requête suivante obtient toutes les autorisations pour le bloc-notes spécifié.

Requête

GET ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Accept: application/json

Réponse

HTTP/1.1 200

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions",
  "value":[
  {
    "userRole":"Owner",
    "userId":"c:0(.s|true",
    "name":"Everyone",
    "id":"1-4",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/1-4"
  },
  {
    "userRole":"Owner",
    "userId":"c:0-.f|rolemanager|spo-grid-all-users/8461cbdd-15a6-45c8-b177-ac24f48a8bee",
    "name":"Everyone except external users",
    "id":"1-5",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-5"
  },
  {
    "userRole":"Owner",
    "userId":"i:0#.f|membership|alexd@domainname.com",
    "name":"Alex Darrow",
    "id":"1-23",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
  }]
}

Informations sur les requêtes et les réponses

Les informations suivantes s'appliquent aux requêtes GET /permissions.

Données des requêtesDescription
ProtocoleToutes les demandes utilisent le protocole HTTPS SSL/TLS.
En-tête d’autorisation

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

S'il est manquant ou non valide, la demande échoue avec un code d'état 401. Voir Authentification avec Azure AD (applications d'entreprise).

Étendue d’autorisationNotes.ReadWrite.CreatedByApp, Notes.ReadWrite, ou Notes.ReadWrite.All
Données de réponseDescription
Code de succèsUn code d'état HTTP 200 et les autorisations demandées.
Corps de la réponseUne représentation OData des autorisations au format JSON.
ErreursSi la requête échoue, l'API renvoie les erreurs dans le corps de la réponse.
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 faites appel au support Microsoft pour résoudre les problèmes.

Supprimer les autorisations

Pour supprimer une autorisation pour un bloc-notes, un groupe de sections ou une section, envoyez une requête DELETE au point de terminaison approprié. Vous pouvez supprimer une autorisation par requête.

Lorsque vous supprimez une autorisation, elle est supprimée de toutes les entités OneNote dans la chaîne d'héritage.

Supprimer une autorisation pour un bloc-notes

DELETE ../notebooks/{notebook-id}/permissions/{permission-id}

Supprimer une autorisation pour le groupe de sections

DELETE ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Supprimer une autorisation pour une section

DELETE ../sections/{section-id}/permissions/{permission-id}

Exemples

La requête suivante supprime une autorisation pour le bloc-notes spécifié.

DELETE ../v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23
Authorization: Bearer {token}
Accept: application/json

Informations sur les requêtes et les réponses

Les informations suivantes s'appliquent aux requêtes DELETE /permissions.

Données des requêtesDescription
ProtocoleToutes les demandes utilisent le protocole HTTPS SSL/TLS.
En-tête d’autorisation

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

S'il est manquant ou non valide, la demande échoue avec un code d'état 401. Voir Authentification avec Azure AD (applications d'entreprise).

Étendue d’autorisationNotes.ReadWrite.CreatedByApp, Notes.ReadWrite ou Notes.ReadWrite.All
Données de réponseDescription
Code de succèsUn code d'état HTTP 204.
ErreursSi la requête échoue, l'API renvoie les erreurs dans le corps de la réponse.
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 faites appel au support Microsoft pour résoudre les problèmes.

Autorisations, héritage et précédence

Vous pouvez définir les autorisations suivantes sur les blocs-notes, les groupes de sections et les sections.

AutorisationDescription
LecteurAccès en lecture seule aux blocs-notes, aux groupes de sections et aux sections.
ContributeurPeut ajouter, modifier et supprimer des blocs-notes, des groupes de sections et des sections.
PropriétaireDispose de toutes les autorisations ci-dessus, peut aussi gérer les autorisations (obtenir, créer et supprimer).

Pour gérer les autorisations sur les entités OneNote, il faut comprendre l'héritage et la précédence des autorisations.

  • Héritage. Les entités héritent des autorisations de leur parent. Ainsi, les blocs-notes héritent des autorisations de la bibliothèque de documents qui contient le bloc-notes. Et à leur tour, ces autorisations sont héritées par les groupes de sections et les sections enfants dans le bloc-notes. Lorsque vous définissez des autorisations explicites sur un bloc-notes, un groupe de sections ou une section, les autorisations sont également propagées à ses objets enfants.

  • Précédence. Lorsque des autorisations conflictuelles sont définies sur une entité OneNote, la permission la plus élevée (la plus permissive) est honorée. Les utilisateurs et les groupes peuvent recevoir des niveaux d'accès conflictuels lorsque plusieurs autorisations sont appliquées à une entité (explicitement ou par héritage) ou lorsque l'utilisateur ou le groupe appartient à plusieurs rôles.

Ces principes déterminent comment l'API OneNote gère les autorisations. Par exemple :

  • Lorsque vous créez une autorisation pour un bloc-notes ou un groupe de sections, l'autorisation est transmise à tous les enfants.

  • Lorsque vous supprimez une autorisation pour un bloc-notes ou un groupe de sections, l'autorisation est supprimée de tous les enfants.

  • Lorsque vous obtenez des autorisations, l'API OneNote renvoie uniquement l'autorisation la plus élevée pour les rôles qui ont des autorisations conflictuelles.

  • Vous pouvez mettre à jour les autorisations pour accorder un accès plus permissif à un utilisateur ou un groupe. Mais si vous souhaitez restreindre l'accès, vous devez d'abord supprimer l'autorisation la plus permissive, puis créer une nouvelle autorisation avec l'accès restrictif. En effet, une requête POST /permissions ajoute en fait un rôle d'utilisateur à la collection d'autorisations pour l'entité, et l'accès le plus permissif est honoré. En d'autres termes, vous pouvez mettre à jour une autorisation Lecteur pour avoir un accès Contributeur ou Propriétaire, mais vous ne pouvez pas mettre à jour une autorisation Contributeur pour autoriser uniquement l'accès Lecteur.

Construction de l’URL racine du service OneNote

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

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


Le segment version dans l’URL représente la version de l’API OneNote 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.


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

Ressources supplémentaires

© 2018 Microsoft