Gerenciar permissões em entidades do OneNote

  • Artigo

Aplica-se ao: Blocos de anotações empresariais no Office 365

Você pode usar o ponto de extremidade permissões para gerenciar permissões de leitura ou gravação para blocos de anotações, grupos de seções e seções.

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

Observação

O gerenciamento de permissões é suportado para os blocos de anotações pessoais, do site e de grupos unificados do Office 365, mas não para bloco de anotações de consumidores no OneDrive.

Construir a URI de solicitação

  1. Para criar o URI de solicitação, inicie com a URL raiz do serviço para a sua plataforma:

    Blocos de anotações no OneDrive for Business

    https://www.onenote.com/api/v1.0/me/notes/

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

    Blocos de anotações do site do SharePoint

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

    Blocos de anotações de grupo unificados

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

  2. Anexe o caminho ao bloco de anotações de destino, ao grupo de seções ou à entidade de seção, seguido pelo ponto de extremidade permissões ou permissões/{id}.

Seu URI de solicitação completo será parecido com estes exemplos:

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}

Observação

Saiba mais sobre a URL raiz de serviço.

Criar ou atualizar permissões

Para criar ou atualizar permissões para um bloco de anotações, grupo de seções ou seção, envie uma solicitação POST para o ponto de extremidade apropriado. Você pode criar ou atualizar apenas uma permissão por solicitação.

As permissões são aplicadas a todas as entidades do OneNote abaixo da cadeia de herança.

Você pode atualizar as permissões para conceder acesso mais permissivo. Mas para restringir o acesso, você deve excluir a permissão existente e criar uma nova permissão. Veja Herança de permissão e precedência.

Criar ou atualizar permissões para um bloco de anotações

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

Criar ou atualizar permissões para um grupo de seções

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

Criar ou atualizar permissões para uma seção

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

No corpo da mensagem, envie um objeto JSON com os parâmetros necessários.

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}
Parâmetro Descrição
userRole O tipo de permissão: Owner, Contributorou Reader.
userId O login de usuário ou de grupo para atribuir a permissão. A API aceita o formato de declarações que inclui o nome do provedor de associação (i:0#.f|membership|username@domainname.com), ou apenas o nome e login principal do usuário (username@domainname.com).

Exemplo

A solicitação a seguir cria uma permissão para o bloco de anotações especificado.

Solicitação

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

Resposta

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

Solicitação e informação de resposta

As informações a seguir aplicam-se às solicitações POST /permissions.

Dados da solicitação Descrição
Protocolo Todas as solicitações usam o protocolo HTTPS de SSL/TLS.
Cabeçalho de autorização

Bearer {token}, onde {token} é um token de acesso do OAuth 2.0 válido para o aplicativo registrado.

Se ausente ou inválido, a solicitação falhará com um código de status 401. Consulte Autenticar usando o Azure AD (aplicativos empresariais).
Escopo de permissão Notes.ReadWrite.CreatedByApp, Notes.ReadWrite ou Notes.ReadWrite.All


Dados da resposta Descrição
Código de êxito Um código de status HTTP 201.
Corpo da resposta Uma representação OData da permissão no formato JSON. Veja Obter permissões para uma descrição de um objeto de permissão.
Erros Se a solicitação falhar, a API retornará erros no corpo de resposta.
Cabeçalho X-CorrelationId Um GUID que identifica de forma exclusiva a solicitação. Você pode usar esse valor junto com o valor do cabeçalho de Date ao trabalhar com o suporte da Microsoft para solucionar problemas.

Obter permissões

Para criar ou atualizar permissões para um bloco de anotações, grupo de seções ou seção, envie uma solicitação GET para o ponto de extremidade apropriado.

Obter permissões para um bloco de anotações

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

Obter uma permissão específica para um bloco de anotações

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

Obter permissões para um grupo de seções

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

Obter uma permissão específica para um grupo de seção

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

Obter permissões para uma seção

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

Obter uma permissão específica para uma seção

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


As solicitações GET retornam a permissão mais alta para uma função de usuário na entidade de destino. Para mais informações, consulte Herança de permissão e precedência.

GET /permissions solicita suporte a opções de consulta OData, da seguinte maneira:

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

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

Observação

O ponto de extremidade permissões não suporta a expand opção de consulta.

Para saber mais sobre como obter entidades do OneNote, incluindo exemplos e opções de cadeia de consulta com suporte, consulte Obter conteúdo e estrutura do OneNote.

Objeto de permissão

Uma permissão contém as seguintes propriedades.

Propriedade Descrição
nome O nome de exibição do usuário ou do grupo principal. Exemplo: "name":"Everyone"
id O identificador exclusivo da permissão, na forma 1-{principal-member-id}. Exemplo: "id":"1-4"
próprio O URL do objeto de permissão.
userId O logon do usuário ou do grupo ao qual a permissão está atribuída. Esse valor é sempre retornado no formato de declarações, por exemplo: i:0#.f|membership|username@domainname.com.
userRole O tipo de permissão: Owner, Contributorou Reader.

Exemplo

A solicitação a seguir obtém todas as permissões para o bloco de anotações especificado.

Solicitação

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

Resposta

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

Solicitação e informação de resposta

As informações a seguir aplicam-se às solicitações GET /permissions.

Dados da solicitação Descrição
Protocolo Todas as solicitações usam o protocolo HTTPS de SSL/TLS.
Cabeçalho de autorização

Bearer {token}, onde {token} é um token de acesso do OAuth 2.0 válido para o aplicativo registrado.

Se ausente ou inválido, a solicitação falhará com um código de status 401. Consulte Autenticar usando o Azure AD (aplicativos empresariais).
Escopo de permissão Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Dados da resposta Descrição
Código de êxito Um código de status HTTP 200 e as permissões solicitadas.
Corpo da resposta Uma representação OData da permissão no formato JSON.
Erros Se a solicitação falhar, a API retornará erros no corpo de resposta.
Cabeçalho X-CorrelationId Um GUID que identifica de forma exclusiva a solicitação. Você pode usar esse valor junto com o valor do cabeçalho de Date ao trabalhar com o suporte da Microsoft para solucionar problemas.

Excluir permissões

Para excluir uma permissão para um bloco de anotações, um grupo de seções ou uma seção, envie uma solicitação DELETE para o ponto de extremidade apropriado. Você pode excluir uma permissão por solicitação.

Quando você exclui uma permissão, ela é excluída de todas as entidades do OneNote abaixo dacadeia de herança.

Excluir uma permissão para um bloco de anotações

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

Excluir uma permissão para um grupo de seções

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

Excluir uma permissão para uma seção

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

Exemplo

A solicitação a seguir exclui uma permissão para o bloco de anotações especificado.

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

Solicitação e informação de resposta

As informações a seguir aplicam-se às solicitações DELETE /permissions.

Dados da solicitação Descrição
Protocolo Todas as solicitações usam o protocolo HTTPS de SSL/TLS.
Cabeçalho de autorização

Bearer {token}, onde {token} é um token de acesso do OAuth 2.0 válido para o aplicativo registrado.

Se ausente ou inválido, a solicitação falhará com um código de status 401. Consulte Autenticar usando o Azure AD (aplicativos empresariais).
Escopo de permissão Notes.ReadWrite.CreatedByApp, Notes.ReadWrite ou Notes.ReadWrite.All


Dados da resposta Descrição
Código de êxito Um código de status HTTP 204.
Erros Se a solicitação falhar, a API retornará erros no corpo de resposta.
Cabeçalho X-CorrelationId Um GUID que identifica de forma exclusiva a solicitação. Você pode usar esse valor junto com o valor do cabeçalho de Date ao trabalhar com o suporte da Microsoft para solucionar problemas.

Permissões, herança e precedência

Você pode definir as seguintes permissões em blocos de anotações, grupos de seções e seções.

Permissão Descrição
Leitor Acesso somente leitura aos blocos de anotações, grupos de seções e seções.
Colaborador Pode adicionar, editar e excluir blocos de anotações, grupos de seções e seções.
Proprietário Todas as permissões acima também podem gerenciar permissões (obter, criar e excluir).

Ao gerenciar permissões em entidades do OneNote, você deve entender a herança e a precedência da permissão.

  • Herança. Entidades herdam as permissões de seus pais. Portanto, os blocos de anotações herdam as permissões da biblioteca de documentos que contém o bloco de anotações. Por sua vez, essas permissões são herdadas pelos grupos de seções e seções filhos no bloco de anotações. Quando você define permissões explícitas em um bloco de anotações, grupo de seções ou seção, as permissões também se propagam para seus objetos filho.

  • Precedência. Quando as permissões conflitantes são definidas em uma entidade do OneNote, a permissão mais alta (mais permissiva) é respeitada. Os usuários e grupos podem receber níveis de acesso conflitantes quando várias permissões são aplicadas a uma entidade (explicitamente ou herdadas) ou quando o usuário ou grupo pertence a várias funções.

Esses princípios determinam como a API do OneNote gerencia as permissões. Por exemplo:

  • Quando você cria uma permissão para um bloco de notas ou grupo de seções, a permissão é enviada para todos os filhos.

  • Quando você exclui uma permissão para um bloco de anotações ou grupo de seções, a permissão é excluída de todas as crianças.

  • Quando você obtém permissões, a API do OneNote retorna apenas a permissão mais alta para funções que possuem permissões conflitantes.

  • Você pode atualizar as permissões para conceder acesso mais permissivo a um usuário ou grupo. Mas se você quiser restringir o acesso, primeiro exclua a permissão mais permissiva e crie uma nova permissão com acesso restrito.

    Isso ocorre porque uma solicitação POST /permissions, na verdade, anexa uma função de usuário à coleção de permissões da entidade e o acesso mais permissivo é honrado. Em outras palavras, você pode atualizar uma permissão de Leitor para ter acesso de Colaborador ou Proprietário, mas não pode atualizar uma permissão de Colaborador para permitir apenas o acesso ao Leitor.

Construir a URL raiz de serviço do OneNote

A URL raiz do serviço do OneNote usa o formato a seguir para todas as chamadas para a API do OneNote.

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

O segmento version na URL representa a versão da API do OneNote que você deseja usar.

  • Use v1.0 para o código de produção estável.

  • Use beta para experimentar um recurso que está em desenvolvimento. Os recursos e a funcionalidade na versão beta podem mudar, por isso, você não deve usá-la no código de produção.

O segmento location na URL representa a localização dos blocos de anotações que você deseja acessar:

  • Blocos de anotações no OneDrive for Business

    • Use me para conteúdos do OneNote pertencentes ao usuário atual.

    • Use users/{id} para o conteúdo do OneNote que o usuário especificado (na URL) compartilhou com o usuário atual. Use a API do Azure AD Graph para obter IDs de usuários.

  • Blocos de anotações do site do SharePoint

    • Sites de equipe e outros sites do SharePoint podem conter blocos de anotações do OneNote em suas bibliotecas de documentos.

    • Use myOrganization/siteCollections/{id}/sites/{id} para conteúdo do OneNote em um site no locatário no qual o usuário atual está conectado. Apenas o locatário atual tem suporte, acessado com a palavra-chave myOrganization. Aprenda como obter IDs de site.

  • Blocos de anotações de grupo unificados

    • Grupos unificados (também chamados de grupos do Office 365) fazem parte da experiência conectada do Office 365. Os membros do grupo podem compartilhar blocos de anotações, arquivos e e-mails.

    • Use myOrganization/groups/{id} para conteúdos do OneNote no grupo especificado do qual o usuário atual é membro. Grupos unificados são os únicos tipos de grupo com suporte. Use a API do Azure AD Graph para obter IDs de grupos.

Use o método FromUrl para obter o conjunto de sites e os IDs dos sites

Você pode usar o método FromUrl para obter o conjunto de sites e os IDs dos sites para uma URL absoluta do site especificado. Você deve fazer essa chamada somente quando necessário e armazenar os valores para uso futuro.

O formato da URL do site depende da sua configuração, por exemplo https://domain.sharepoint.com/site-a ou https://domain.com/sites/site-a.

Exemplo de solicitação

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

Authorization: Bearer {token}

Accept: application/json

Resposta de exemplo

{"@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 uso de FromUrl e como trabalhar com os blocos de anotações do site do SharePoint:

  • Você só pode criar blocos de anotações, grupos de seções, seções e páginas do OneNote em sites que tenham uma biblioteca de documentos padrão. (Alguns modelos de site não criam uma biblioteca de documentos padrão.) No entanto, as solicitações GET retornam o conteúdo do OneNote de todas as bibliotecas de documentos no site.

  • A URL raiz do serviço do OneNote é imutável, o que significa que você não pode usar um caminho do site da API REST do SharePoint e depois rastrear o ponto de extremidade notes nele.

  • O usuário para quem você está fazendo a chamada deve ser membro do site.

  • O método FromUrl funciona apenas com sites que foram indexados. Pode levar várias horas para indexar um site novo.

Confira também