Copiar blocos de anotações, seções e páginas

  • Artigo

Aplica-se a: Bloco de anotações empresariais apenas no Office 365

Para copiar um bloco de anotações, uma seção ou uma página do OneNote, envie uma solicitação POST ao ponto de extremidade respectivo da ação cópia. Por exemplo:

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

Envie um objeto de cópia JSON no corpo da mensagem. Se a solicitação for bem-sucedida, a API do OneNote retornará um código de status HTTP 202 e um cabeçalho Operation-Location. Em seguida, é possível pesquisar ponto de extremidade do resultado.

Observação

Atualmente, a funcionalidade de cópia tem suporte para blocos de anotações pessoais, de site e de grupo do Office 365, mas não para blocos de anotações de consumidores no OneDrive.

Construir o URI de solicitação

  1. Para criar o URI de solicitação, inicie com a URL raiz do serviço para 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. Acrescente o ponto de extremidade respectivo da ação cópia:

    Copiar uma página a uma seção

    ../pages/{id}/copyToSection

    Copiar uma seção a um bloco de anotações

    ../sections/{id}/copyToNotebook

    Copiar uma seção a um grupo de seções

    ../sections/{id}/copyToSectionGroup

    Copiar um bloco de anotações

    ../notebooks/{id}/copyNotebook

O bloco de anotações é copiado para a pasta Blocos de anotações na biblioteca de destino Documentos. A pasta Bloco de anotações será criada caso não exista.

Seu URI de solicitação completo parecerá com um dos seguintes exemplos:

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

Observação

Saiba mais sobre a URL raiz de serviço.

Construir o corpo da mensagem

No corpo da mensagem, envie um objeto JSON que contenha os parâmetros de que sua operação precisa. Não há problema em enviar um corpo vazio se nenhum parâmetro for necessário.

Parâmetro Descrição
id A ID do bloco de anotações ou grupo de seções de destino (para seções); ou a ID da seção de destino (para páginas).

Usada apenas com copyToNotebook, copyToSectionGroupe copyToSection.
siteCollectionId A ID do conjunto de sites do SharePoint que contém o site para o qual copiar o item.

Usada com siteId e somente ao copiar para um site do SharePoint.
siteId A ID do site do SharePoint para o qual copiar o item.

Usada com siteCollectionId e somente ao copiar para um site do SharePoint.
groupId A ID do grupo para o qual copiar o item.

Usado somente ao copiar para um grupo unificado.
renameAs O nome da cópia.

Usado apenas com copyNotebook, copyToNotebook e copyToSectionGroup. Tem o nome do item existente como padrão.

Saiba como obter IDs de blocos de anotações, grupos de seção e seções e como obter conjuntos de sites e IDs de sites. Para obter informações sobre como obter IDs de grupo, consulte Documentação da API do Azure AD Graph.

Fluxo de exemplo para uma operação de cópia

Primeiro, envie uma solicitação POST para a ação de cópia no item que você deseja copiar. Você pode copiar dos blocos de anotações aos quais o usuário têm acesso (de propriedade ou compartilhado), desde que a origem e o destino estejam no mesmo locatário.

O exemplo a seguir copia um bloco de anotações pessoal para um site de equipe do SharePoint. A solicitação não inclui o parâmetro renameAs, portanto, o novo bloco de anotações usa o nome existente.

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

Observação

As operações de cópia respeitam as permissões do bloco de anotações de origem, de modo que o usuário autenticado deve poder acessar o bloco de anotações de origem para copiá-lo. Porém, cópias não retêm as permissões da origem. A cópia tem permissões como se usuário a tivesse recém-criado.

Se a chamada for bem-sucedida, a API do OneNote retornará um código de status 202 e um cabeçalho Operation-Location. Aqui está um trecho da resposta:

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

Então você pesquisa o ponto de extremidade Operation-Location para obter o status da operação de cópia:

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

A API do OneNote retorna um objeto OperationModel que mostra o status atual. A resposta do exemplo a seguir é retornada quando o status é concluído.

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

O status pode ser concluído, em execução ou falhou.

  • Se for concluído, a propriedade resourceLocation contém o ponto de extremidade do recurso para a nova cópia.
  • Se for em execução, a propriedade percentComplete mostra a porcentagem aproximada de conclusão.
  • Se for falhou, as propriedades error e @ api.diagnostics fornecem informações de erro.

Você pode pesquisar ponto de extremidade da operação até que a operação tenha sido concluída ou tenha falhado.

Solicitação e informações de resposta

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 ele estiver ausente ou for inválido, a solicitação falhará com um código de status 401. Confira Autenticação e permissões.
Cabeçalho de tipo de conteúdo application/json
Cabeçalho Accept application/json


Dados de resposta Descrição
Código de êxito Um código de status HTTP do status 200.
Cabeçalho Operation-Location A URL para pesquisar o status da operação.

A pesquisa do ponto de extremidade da operação retorna um objeto OperationModel, que contém o status da operação e outras informações.
Cabeçalho X-CorrelationId Um GUID que identifica de forma exclusiva a solicitação. Você pode usar esse valor juntamente com o valor do cabeçalho Date ao trabalhar com o suporte da Microsoft para solucionar problemas.

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 tipo 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 as IDs de sites

Você pode usar o método FromUrl para obter o conjunto de sites e as IDs de 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.

Solicitação de exemplo

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 usar FromUrl e 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.

Permissões

Para copiar blocos de anotações, seções e páginas do OneNote, você precisará solicitar as permissões apropriadas. Escolha o nível mais baixo de permissões que seu aplicativo precisa para funcionar.

Plataforma Escopo de permissão
Consumidor office.onenote_create, office.onenote_update_by_app, office.onenote_update
Empresa Notes.Create, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, Notes.ReadWrite.All

Para saber mais sobre escopos de permissão e como eles funcionam, confira Escopos de permissão do OneNote.

Confira também