Table of contents
TOC
Collapse the table of content
Expand the table of content
Última actualización: 20/06/2018

Administrar permisos en entidades de OneNote

Se aplica a: Blocs de notas empresariales en Office 365

Puedes usar el punto de conexión de permisos para administrar permisos de lectura o escritura en blocs de notas, grupos de secciones y secciones.

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

La administración de permisos es compatible con blocs de notas personales, de sitio y grupales de Office 365, pero no con blocs de notas de consumo en OneDrive.

Crear el URI de la solicitud

Para crear el URI de solicitud, comienza con la URL raíz del servicio para tu plataforma:

Blocs de notas en OneDrive para la Empresa
https://www.onenote.com/api/v1.0/me/notes/
https://www.onenote.com/api/v1.0/users/{id}/notes/

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

Blocs de notas de grupos unificados
https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/


Luego añade la ruta al bloc de notas, grupo de sección o entidad de sección en la base de datos de destino, seguida del punto de conexión de lospermisos o permisos/{id} .

Tu URI de solicitud completa se verá más o menos como estos ejemplos:

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}

Obtenga más información sobre service root URL.

Crear o actualizar permisos

Para crear o actualizar permisos para un bloc de notas, grupo de sección o sección, envía una solicitud POST al punto de conexión apropiado. Puedes crear o actualizar sólo un permiso por solicitud.

Los permisos se aplican a todas las entidades de OneNote de la parte baja de la cadena de herencia.

Puedes actualizar los permisos para conceder un acceso más permisivo. Pero para restringir el acceso, debes eliminar el permiso actual y crear un nuevo permiso. Ver Permiso de herencia y precedencia.

Crear o actualizar permisos para un bloc de notas

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

Crear o actualizar permisos para un grupo de sección

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

Crear o actualizar permisos para una sección

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

Envía un objeto JSON con los parámetros requeridos en el cuerpo del mensaje.

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}
ParámetroDescripción
rolDelUsuarioEl tipo de permiso: Owner, Contributor, o Reader.
idDeUsuarioEl inicio de sesión del usuario o grupo a quien asignar el permiso. La API acepta el formato de notificaciones que incluye el nombre del proveedor de servicios de suscripción (*i:0#.f

Ejemplo

La siguiente solicitud crea un permiso para el bloc de notas especificado.

Solicitud

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"
}

Respuesta

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",
}

Información de la solicitud y respuesta

La siguiente información se aplica a POST /permissions solicitudes.

Datos de solicitudDescripción
ProtocoloTodas las solicitudes usan el protocolo HTTPS SSL/TLS.
Encabezado Authorization

Bearer {token}, donde {token} es un token de acceso de OAuth 2.0 válido para la aplicación registrada.

Si falta o no es válido, se produce un error en la solicitud con un código de estado 401. Consultar Autenticar con Azure AD (apps empresariales).

Ámbito de permisosNotas.LecturaEscritura.CreadoPorApp, Notas.LecturaEscritura o Notas.LecturaEscrituraTodo
Datos de respuestaDescripción
Código correctoUn código de estado HTTP 201.
Cuerpo de la respuestaUna representación de OData del permiso en formato JSON. Ver obtener permisos para una descripción de un objeto de permiso.
ErroresSi se produce un error en la solicitud, la API devuelve errores en el cuerpo de la respuesta.
Encabezado X-CorrelationIdGUID que identifica la solicitud de manera única. Puede usar este valor junto con el valor del encabezado de fecha al trabajar con el soporte técnico de Microsoft para solucionar problemas.

Obtener permisos

Para obtener permisos para un bloc de notas, grupo de sección o sección, envía una solicitud GET al punto de conexión apropiado.

Obtener permisos para un bloc de notas

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

Obtener un permiso específico para un bloc de notas

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

Obtener permisos para un grupo de sección

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

Obtener un permiso específico para un grupo de sección

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

Obtener permisos para una sección

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

Obtener un permiso específico para una sección

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


Las solicitudes GET devuelven el permiso más alto para un rol de usuario en la entidad objetivo. Para más información, ver Permiso de herencia y precedencia.

GET /permissions las solicitudes admiten las opciones de consulta de OData, de la siguiente manera:

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

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

El punto de conexión de los permisos no admite la expand opción de consulta.

Para más información sobre cómo obtener entidades de OneNote, incluidas las opciones y ejemplos de cadenas de consulta compatibles, ver Obtener contenido y estructura de OneNote.

Objeto de Permiso

Un permiso contiene las siguientes propiedades.

PropiedadDescripción
nombreEl nombre para mostrar de la entidad principal de seguridad del usuario o grupo. Ejemplo: "name":"Everyone"
idEl identificador único del permiso, en la forma 1-{principal-member-id}. Ejemplo: "id":"1-4"
selfLa URL del objeto de permiso.
idDeUsuarioEl inicio de sesión del usuario o grupo al que se le asigna el permiso. Este valor siempre se devuelve con el formato de las notificaciones, por ejemplo: *i:0#.f
rolDelUsuarioEl tipo de permiso: Owner, Contributor, o Reader.

Ejemplo

La siguiente solicitud obtiene todos los permisos para el bloc de notas especificado.

Solicitud

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

Respuesta

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",
  }]
}

Información de la solicitud y respuesta

La siguiente información se aplica a GET /permissions solicitudes.

Datos de solicitudDescripción
ProtocoloTodas las solicitudes usan el protocolo HTTPS SSL/TLS.
Encabezado Authorization

Bearer {token}, donde {token} es un token de acceso de OAuth 2.0 válido para la aplicación registrada.

Si falta o no es válido, se produce un error en la solicitud con un código de estado 401. Consultar Autenticar con Azure AD (apps empresariales).

Ámbito de permisosNotas.Lectura, Notas.LecturaEscritura.CreadoPorApp, Notas.LecturaEscritura o Notas.LecturaEscrituraTodo
Datos de respuestaDescripción
Código correctoUn código de estado HTTP 200 y los permisos solicitados.
Cuerpo de la respuestaUna representación de OData de los permisos en formato JSON.
ErroresSi se produce un error en la solicitud, la API devuelve errores en el cuerpo de la respuesta.
Encabezado X-CorrelationIdGUID que identifica la solicitud de manera única. Puede usar este valor junto con el valor del encabezado de fecha al trabajar con el soporte técnico de Microsoft para solucionar problemas.

Eliminar permisos

Para eliminar un permiso para un bloc de notas, grupo de sección o sección, envía una solicitud DELETE al punto de conexión apropiado. Puedes eliminar un permiso por solicitud.

Cuando eliminas un permiso, este se elimina de todas las entidades de OneNote de la parte baja de la cadena de herencia.

Eliminar un permiso para un bloc de notas

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

Eliminar un permiso para un grupo de sección

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

Eliminar un permiso para una sección

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

Ejemplo

La siguiente solicitud elimina un permiso para el bloc de notas especificado.

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

Información de la solicitud y respuesta

La siguiente información se aplica a DELETE /permissions solicitudes.

Datos de solicitudDescripción
ProtocoloTodas las solicitudes usan el protocolo HTTPS SSL/TLS.
Encabezado Authorization

Bearer {token}, donde {token} es un token de acceso de OAuth 2.0 válido para la aplicación registrada.

Si falta o no es válido, se produce un error en la solicitud con un código de estado 401. Consultar Autenticar con Azure AD (apps empresariales).

Ámbito de permisosNotas.LecturaEscritura.CreadoPorApp, Notas.LecturaEscritura o Notas.LecturaEscrituraTodo
Datos de respuestaDescripción
Código correctoUn código de estado HTTP 204.
ErroresSi se produce un error en la solicitud, la API devuelve errores en el cuerpo de la respuesta.
Encabezado X-CorrelationIdGUID que identifica la solicitud de manera única. Puede usar este valor junto con el valor del encabezado de fecha al trabajar con el soporte técnico de Microsoft para solucionar problemas.

Permisos, herencia y precedencia

Puedes configurar los siguientes permisos en blocs de notas, grupos de secciones y secciones.

PermisoDescripción
LectorAcceso de sólo lectura a blocs de notas, grupos de secciones y secciones.
ColaboradorPuedes añadir, editar y eliminar blocs de notas, grupos de secciones y secciones.
PropietarioLos permisos anteriores también pueden administrar permisos (obtener, crear y eliminar).

Al administrar permisos en entidades de OneNote, debes comprender la herencia y la precedencia de los mismos.

  • Herencia. Las entidades heredan los permisos de sus elementos primarios. Por lo que los blocs de notas heredan los permisos de la biblioteca de documentos que contiene el bloc de notas. Y a su vez, estos permisos los heredan los grupos de secciones y las secciones secundarias dentro del bloc de notas. Cuando estableces permisos explícitos en un bloc de notas, grupo de sección o sección, los permisos se propagan también a sus objetos secundarios.

  • Precedencia. Cuando se establecen permisos contradictorios en una entidad de OneNote, se respeta el permiso más alto (más permisivo). A los usuarios y a los grupos se les pueden conceder niveles conflictivos de acceso cuando se aplican múltiples permisos a una entidad (de manera explícita o heredada) o cuando el usuario o el grupo pertenece a múltiples roles.

Estos principios determinan cómo la API de OneNote administra los permisos. Por ejemplo:

  • Cuando creas un permiso para un bloc de notas o grupo de sección, el permiso se envía a todos los elementos secundarios.

  • Cuando eliminas un permiso para un bloc de notas o grupo de sección, el permiso se elimina de todos los elementos secundarios.

  • Cuando obtienes permisos, la API de OneNote devuelve sólo el permiso más alto para los roles que tienen permisos conflictivos.

  • Puedes actualizar los permisos para conceder un acceso más permisivo a un usuario o grupo. Pero si quieres restringir el acceso, primero debes eliminar el permiso más permisivo y luego crear un nuevo permiso con el acceso restrictivo. Esto se debe a que una POST /permissions solicitud en realidad añade un rol de usuario a la colección de permisos para la entidad, y se respeta el acceso más permisivo. Dicho de otra forma, puedes actualizar un permiso de Lector para tener un acceso de Colaborador o Propietario, pero no puedes actualizar un permiso de Colaborador para permitir sólo el acceso de Lector.

Crear la URL raíz del servicio de OneNote

La dirección URL raíz del servicio de OneNote utiliza el siguiente formato para todas las llamadas a la API de OneNote.

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


El segmento version de la URL representa la versión de la API de OneNote que desea utilizar.

  • Utilice v1.0 para un código de producción estable.
  • Use beta para probar una característica que esté en desarrollo. Las características y funciones pueden cambiar en la versión beta, por lo que le recomendamos que no la use en su código de producción.


El segmento location de la URL representa la ubicación de los blocs de notas a los que desea acceder.

Blocs de notas en OneDrive para la Empresa
Use me para el contenido de OneNote que sea propiedad del usuario actual.

Utilice users/{id} para el contenido de OneNote que el usuario especificado (en la URL) haya compartido con el usuario actual. Use la API de Azure AD Graph para obtener id. de usuario.

Blocs de notas del sitio de SharePoint
Los sitios de grupo y otros sitios de SharePoint pueden contener blocs de notas de OneNote en sus bibliotecas de documentos.

Utilice myOrganization/siteCollections/{id}/sites/{id} para el contenido de OneNote en un sitio de la cuenta empresarial en la que el usuario actual haya iniciado sesión. Solo se admite la cuenta empresarial actual, a la que se accede empleando la palabra clave myOrganization. Descubra cómo obtener id. de sitio.

Blocs de notas de grupo de Office 365
Los grupos de Office 365 son parte de la experiencia conectada de Office 365. Los miembros del grupo pueden compartir blocs de notas, archivos y correos electrónicos.

Utilice myOrganization/groups/{id} para el contenido de OneNote en el grupo especificado del que el usuario actual sea miembro. Los grupos de Office 365 (que devuelven el unified groupType) son el único tipo de grupo admitido. Use la API de Azure AD Graph para obtener id. de usuario.


Utilizar el método FromUrl para obtener la colección y los id. de sitios
Puede usar el método FromUrl para obtener la colección y los id. de sitios para una URL de sitio absoluta y específica. Debe realizar esta llamada solo cuando sea necesario y luego guardar los valores para usarlos en el futuro.

El formato de la URL de sitio depende de su configuración, por ejemplo https://domain.sharepoint.com/site-a o https://domain.com/sites/site-a.

Ejemplo de solicitud:

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

Ejemplo de respuesta:

{
  "@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"
}

Requisitos para usar FromUrl y trabajar con blocs de notas del sitio de SharePoint:

  • Solo puede crear blocs de notas de OneNote, grupos de secciones, secciones y páginas en sitios que tengan una biblioteca de documentos predeterminada. (Algunas plantillas de sitio no crean una biblioteca de documentos predeterminada). Sin embargo, las solicitudes GET devuelven contenido de OneNote de todas las bibliotecas de documentos del sitio.
  • La URL raíz del servicio de OneNote es inmutable, lo que significa que no puede usar una ruta de sitio de la API de REST de SharePoint y luego añadirle el punto de conexión notes.
  • El usuario en cuyo nombre está realizando la llamada debe ser miembro del sitio.
  • FromUrl funciona solo con sitios que hayan sido indexados. Puede llevar varias horas indexar un nuevo sitio.

Recursos adicionales

© 2018 Microsoft