Obter a estrutura e o conteúdo do OneNote

  • Artigo

Aplica-se a: Blocos de anotações de consumidor no OneDrive | Blocos de anotações empresariais no Microsoft 365

Para obter o conteúdo e a estrutura do OneNote usando a API do OneNote do Microsoft Graph, envie uma solicitação GET para o ponto de extremidade de destino. Por exemplo:

GET ../onenote/pages/{id}

Se a solicitação for bem-sucedida, o Microsoft Graph retornará um código de status HTTP 200 OK e as entidades ou o conteúdo que você solicitou. As entidades do OneNote são retornadas como objetos JSON que estão em conformidade com a especificação OData versão 4.0.

Usando as opções de cadeia de caracteres de consulta, você pode filtrar as consultas e melhorar o desempenho.

Observação

Se você estiver criando uma solução que dê suporte a um dos cenários a seguir, atingirá as limitações da API do OneNote:

  • Seções do OneNote de Backup/restauração
  • Fazer backup/restaurar blocos de anotações do OneNote

Para operações de backup e restauração, consulte Práticas recomendadas para descobrir arquivos e detectar alterações em escala.

Construir a URI de solicitação

Para construir a URI de solicitação, comece com a URL raiz do serviço:

https://graph.microsoft.com/v1.0/me/onenote

Em seguida, acrescente o ponto de extremidade do recurso que você deseja recuperar. (Os caminhos recurso são mostrados na próxima seção).

Sua URI de solicitação completa parecerá com um dos seguintes exemplos:

  • https://graph.microsoft.com/v1.0/me/onenote/notebooks/{id}/sections
  • https://graph.microsoft.com/v1.0/me/onenote/notes/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?select=title,self

Observação

Saiba mais sobre a URL raiz de serviço.

Caminhos de recursos para solicitações GET

Use os caminhos de recursos a seguir para obter páginas, seções, grupos de seções, blocos de anotações e recursos de arquivo ou imagem.

Coleção de páginas

Obter páginas (metadados) em todos os blocos de anotações.

../pages[?filter,orderby,select,expand,top,skip,count]

Obter páginas (metadados) de uma seção específica.

../sections/{section-id}/pages[?filter,orderby,select,expand,top,skip,count,pagelevel]

A ordem de classificação padrão é lastModifiedTime desc.

A consulta padrão expande a seção pai e seleciona as propriedades id, name e self da seção.

Por padrão, somente as primeiras 20 entradas são retornadas para solicitações GET pages. Solicitações que não especificam uma opção principal de sequência de caracteres de consulta retornam um link @odata.nextLink na resposta que você pode usar para obter as próximas 20 entradas.

Para a coleção de páginas em uma seção, use pagelevel para retornar o nível de recuo de páginas e sua ordem dentro da seção.

Exemplo

GET ../sections/{section-id}/pages?pagelevel=true

Entidade Page

Obtenha os metadados de uma página específica.

../pages/{page-id}[?select,expand,pagelevel]

As páginas podem expandir as propriedades parentNotebook e parentSection.

A consulta padrão expande a seção pai e seleciona as propriedades id, name e self da seção.

Use pagelevel para retornar o nível de recuo da página e sua ordem dentro da seção pai.

Exemplo

GET ../pages/{page-id}?pagelevel=true

Visualização de página

Obtenha conteúdo de visualização de texto e imagem de uma página.

../pages/{page-id}/preview

A resposta JSON contém conteúdo de visualização que você pode usar para ajudar os usuários a identificar o que está na página.

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.PagePreview",
  "previewText":"text-snippet",
  "links":{
    "previewImageUrl":{
      "href":"https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png"
    }
  }
}

A propriedade previewText contém um trecho de texto proveniente da página. O Microsoft Graph retorna frases completas, no máximo de 300 caracteres.

Se a página tem uma imagem que pode ser usada para criar uma IU de visualização, a propriedade href no objeto previewImageUrl contém um link para um recurso de imagem público. Você pode usar esse link em HTML. Caso contrário, href retorna nulo.

Exemplo

<img src="https://www.onenote.com/api/v1.0/resources/{id}/content?publicAuth=true&mimeType=image/png" />

Conteúdo HTML da página

Obtenha o conteúdo HTML da página.

../pages/{page-id}/content[?includeIDs]

(saiba mais sobre conteúdo HTML retornado)

Use a opção de cadeia de caracteres de consulta includeIDs=true para obter IDs gerados usados para atualizar a página.

Conjunto da seção

Obtenha todas as seções de todos os blocos de anotações de propriedade de um usuário, incluindo seções em grupos de seções aninhadas.

../sections[?filter,orderby,select,top,skip,expand,count]

Obtenha todas as seções que estão diretamente em um grupo de seções específico.

../sectionGroups/{sectiongroup-id}/sections[?filter,orderby,select,top,skip,expand,count]

Obtenha todas as seções que estão diretamente em um bloco de anotações específico.

../notebooks/{notebook-id}/sections[?filter,orderby,select,top,skip,expand,count]

As seções podem expandir as propriedades parentNotebook e parentSectionGroup.

A ordem de classificação padrão para seções é name asc.

A consulta padrão expande o bloco de anotações pai e o grupo de seções pai e seleciona as propriedades id, name e self.

Entidade Section

Obtenha uma seção específica.

../sections/{section-id}[?select,expand]

As seções podem expandir as propriedades parentNotebook e parentSectionGroup.

A consulta padrão expande o bloco de anotações pai e o grupo de seções pai e seleciona as propriedades id, name e self.

Coleção SectionGroup

Obtenha todos os grupos de seções de todos os blocos de anotações que são de propriedade de um usuário, incluindo grupos de seções aninhadas.

../sectionGroups[?filter,orderby,select,top,skip,expand,count]

Obtenha todos os grupos de seções que estão diretamente em um bloco de anotações específico.

../notebooks/{notebook-id}/sectionGroups[?filter,orderby,select,top,skip,expand,count]

Os grupos de seções podem expandir as propriedades sections, sectionGroups, parentNotebook e parentSectionGroup.

A ordem de classificação padrão para grupos de seções é name asc.

A consulta padrão expande o bloco de anotações pai e o grupo de seções pai e seleciona as propriedades id, name e self.

Entidade SectionGroup

Obtenha um grupo de seções específico.

../sectionGroups/{sectiongroup-id}[?select,expand]

Os grupos de seções podem expandir as propriedades sections, sectionGroups, parentNotebook e parentSectionGroup.

A consulta padrão expande o bloco de anotações pai e o grupo de seções pai e seleciona as propriedades id, name e self.

Coleção de blocos de anotações

Obtenha todos os blocos de anotações de propriedade do usuário.

../notebooks[?filter,orderby,select,top,skip,expand,count]

Os blocos de anotações podem expandir as propriedades sections e sectionGroups.

A ordem de classificação padrão para blocos de anotações é name asc.

Entidade Notebook

Obtenha um bloco de anotações específico.

../notebooks/{notebook-id}[?select,expand]

Os blocos de anotações podem expandir as propriedades sections e sectionGroups.

Imagem ou outro recurso de arquivo

Obtenha os dados binários de um recurso específico.

../resources/{resource-id}/$value

Você pode encontrar a URI do recurso do arquivo na página de HTML de saída.

Por exemplo, um rótulo img inclui os pontos de extremidade para a imagem original no atributo data-fullres-src e a imagem otimizada no atributo src.

Exemplo

<img 
    src="https://www.onenote.com/api/v1.0/me/notes/resources/{image-id}/$value"  
    data-src-type="image/png"
    data-fullres-src="https://www.onenote.com/api/v1.0/resources/{image-id}/$value"  
    data-fullres-src-type="image/png" ... />

E um rótulo object inclui o ponto de extremidade para o recurso do arquivo no atributo data.

Exemplo

<object
    data="https://www.onenote.com/api/v1.0/me/notes/resources/{file-id}/$value"
    data-attachment="fileName.pdf" 
    type="application/pdf" ... />

Observação

Não há suporte para obter uma coleção de recursos.

Quando um recurso de arquivo é obtido, não é necessário incluir um tipo de conteúdo Accept na solicitação.

Para obter mais informações sobre solicitações GET, confira os seguintes recursos na referência do Microsoft Graph API REST:

Exemplo de solicitações GET

Você pode consultar entidades do OneNote para obter apenas as informações necessárias. Os exemplos a seguir mostram algumas maneiras de usar opções de cadeia de caracteres de consulta com suporte em solicitações GET para o Microsoft Graph.

Lembre-se:

  • Todas as solicitações GET começam com a URL raiz de serviço raiz.

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

  • Os espaços na cadeia de caracteres de consulta da URL devem usar a codificação de %20.

    Exemplo: filter=title%20eq%20'biology'

  • Os nomes de propriedade e as comparações de cadeias de caracteres de OData diferenciam maiúsculas de minúsculas. É recomendável usar a função tolower do OData para comparações de cadeia de caracteres.

    Exemplo: filter=tolower(name) eq 'spring'

filter

Obtenha todas as páginas que foram criadas por um aplicativo específico.

[GET] ../pages?filter=createdByAppId eq 'WLID-000000004C12821A'

select

Obtenha o título, os links do cliente do OneNote e o link contentUrl para todas as páginas.

[GET] ../pages?select=title,links,contentUrl

expand

Obtenha todos os blocos de anotações e expanda suas seções e grupos de seções.

[GET] ../notebooks?expand=sections,sectionGroups

Obtenha um grupo de seções específico e expanda suas seções e grupos de seções.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections,sectionGroups

Obtenha uma página e expanda sua seção pai e o bloco de anotações pai.

[GET] ../pages/{page-id}?expand=parentSection,parentNotebook

expand (vários níveis)

Obtenha todos os blocos de anotações e expanda suas seções e grupos de seções, e expanda todas as seções em cada grupo de seções.

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections)

Observação

A expansão de pais de entidades filho ou a expansão de filhos de entidades pai cria uma referência circular não compatível.

expand e select (vários níveis)

Obtenha o nome e o link self para um grupo de seções específico, e obtenha o nome e os links self para todas as suas seções.

[GET] ../sectionGroups/{sectiongroup-id}?expand=sections(select=name,self)&select=name,self

Obtenha o nome e o link self para todas as seções e o nome e o tempo criados de cada bloco de anotações pai da seção.

[GET] ../sections?expand=parentNotebook(select=name,createdTime)&select=name,self

Obtenha o título e uma ID de todas as páginas, e o nome da seção pai e do bloco de anotações pai. 
[GET] ../pages?select=id,title&expand=parentSection(select=name),parentNotebook(select=name)

expand e levels (vários níveis)

Obtenha todos os blocos de anotações, seções e grupos de seção.

[GET] ../notebooks?expand=sections,sectionGroups(expand=sections,sectionGroups(levels=max;expand=sections))

filter

Obtenha todas as seções que foram criadas em outubro de 2014.

[GET] ../sections?filter=createdTime ge 2014-10-01 and createdTime le 2014-10-31

Obtenha as páginas que foram criadas por um aplicativo específico desde 1º de janeiro de 2015.

[GET] ../pages?filter=createdByAppId eq 'WLID-0000000048118631' and createdTime ge 2015-01-01

filter e expand

Obtenha todas as páginas em um bloco de anotações específico. A API retorna 20 entradas por padrão.

[GET] ../pages?filter=parentNotebook/id eq '{notebook-id}'&expand=parentNotebook

Obtenha o nome e o link pagesUrl para todas as seções do bloco de anotações School. Comparações de cadeias de caracteres de OData diferenciam maiúsculas de minúsculas, portanto, use a função tolower como uma prática recomendada.

[GET] ../notebooks?filter=tolower(name) eq 'school'&expand=sections(select=name,pagesUrl)

filter, select e orderby

Obtenha o nome e o link pagesUrl para todas as seções que contêm o termo spring no nome da seção. Ordenar seções de pedidos por última data modificada.

[GET] ../sections?filter=contains(tolower(name),'spring')&select=name,pagesUrl&orderby=lastModifiedTime desc

orderby

Obtenha as primeiras 20 páginas pela propriedade createdByAppId e, depois, pela hora de criação mais recente. A API retorna 20 entradas por padrão.

[GET] ../pages?orderby=createdByAppId,createdTime desc

filtrar & superior

Obtenha as cinco páginas mais recentes criadas desde 1º de janeiro de 2015. A API retorna 20 entradas por padrão com um máximo de 100. A ordem de classificação padrão é lastModifiedTime desc.

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5

filtrar & top & skip

Obtenha as próximas cinco páginas no conjunto de resultados .

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=5

E os próximos cinco.

[GET] ../pages?filter=createdTime ge 2015-01-01&top=5&skip=10

Observação

Se a parte superior e o filtro forem aplicados à mesma solicitação, os resultados incluirão apenas as entidades que correspondem aos dois critérios.

select

Obtenha nome, hora de criação e link self de todas as seções nos blocos de anotações do usuário.

[GET] ../sections?select=name,createdTime,self

Obtenha título, hora de criação e links do cliente do OneNote para uma página específica.

[GET] ../pages/{page-id}?select=title,createdTime,links

select, expand e filter (vários níveis)

Obtenha nome e link pagesUrl para todas as seções do bloco de anotações do usuário.

[GET] ../notebooks?select=name&expand=sections(select=name,pagesUrl)&filter=isDefault eq true

top, select e orderby

Obtenha o título e o link self das 50 primeiras páginas, classificadas em ordem alfabética por título. A API retorna 20 entradas por padrão com um máximo de 100. A ordem de classificação padrão é lastModifiedTime desc.

[GET] ../pages?top=50&select=title,self&orderby=title

skip, top, select e orderby

Obtenha páginas de 51 a 100. A API retorna 20 entradas por padrão com um máximo de 100.

[GET] ../pages?skip=50&top=50&select=title,self&orderby=title

Observação

Solicitações GET para páginas que recuperam o número padrão de entradas (ou seja, elas não especificam uma expressão superior ) retornam um link @odata.nextLink na resposta que você pode usar para obter as próximas 20 entradas.

Opções de cadeia de caracteres de consulta OData com suporte.

Quando enviar solicitações GET para Microsoft Graph, você pode usar as opções de cadeia de caracteres de consulta de OData para personalizar sua consulta e obter apenas as informações que você precisa. Também podem melhorar o desempenho, reduzindo o número de chamadas para o serviço e o tamanho da carga de resposta.

Observação

Para facilitar a leitura, os exemplos neste artigo não usam a codificação de %20 necessária para espaços na cadeia de caracteres de consulta da URL: filter=isDefault%20eq%20true

Opção de consulta Exemplo e descrição
count

count=true

A contagem de entidades da coleção. O valor é retornado na propriedade @odata.count na resposta.
expand

expand=sections,sectionGroups

Propriedades de navegação para retornar embutidas na resposta. As propriedades a seguir têm suporte para expressões expand:
– Páginas: parentNotebook, parentSection
– Seções: parentNotebook, parentSectionGroup
– Grupos de seções: sections, sectionGroups, parentNotebook, parentSectionGroup
– Blocos de anotações: sections, sectionGroups

Por padrão, as solicitações GET de páginas expandem parentSection e selecionam as propriedades id, name e self. Solicitações GET padrão de seções e grupos de seções expandem parentNotebook e parentSectionGroup e selecionam as propriedades pai id, name e self.

Pode ser usado para uma única entidade ou uma coleção.
Separar com vírgulas várias propriedades.
Os nomes de propriedades diferenciam maiúsculas de minúsculas.
filter

filter=isDefault eq true

Uma expressão booliana para se deseja incluir uma entrada no conjunto de resultados. Compatível com os seguintes operadores e funções OData:
– Operadores de comparação: eq, ne, gt, ge, lt, le
– Operadores lógicos: and, or, not
– Funções de cadeia de caracteres: contains, endswith, startswith, length, indexof, substring, tolower, toupper, trim, concat

Os nomes de propriedade e as comparações de cadeias de caracteres de OData diferenciam maiúsculas de minúsculas. É recomendável usar a função tolower do OData para comparações de cadeia de caracteres.

Exemplo: filter=tolower(name) eq 'spring'
orderby

orderby=title,createdTime desc

As propriedades para classificar por, com uma ordem de classificação opcional asc (padrão) ou desc. Você pode classificar por qualquer propriedade da entidade na coleção solicitada.

A ordem de classificação padrão para blocos de anotações, grupos de seções e seções é name asc, e para páginas é lastModifiedTime desc (última página modificada primeiro).

Separe as várias propriedades com vírgulas e liste-as na ordem de aplicação desejada. Os nomes de propriedades diferenciam maiúsculas de minúsculas.
select

select=id,title

As propriedades a serem retornadas. Pode ser usado para uma única entidade ou para uma coleção. Separar com vírgulas várias propriedades. Os nomes de propriedades diferenciam maiúsculas de minúsculas.
skip

skip=10

O número de entradas para ignorar no conjunto de resultados. Costumam ser usadas para resultados de paginação.
top

top=50

O número de entradas para retornar do conjunto de resultados, até um máximo de 100. O valor padrão é 20.

O Microsoft Graph também fornece a opção de cadeia de caracteres de consulta pagelevel que você pode usar para obter o nível e ordem das páginas dentro da seção pai. Aplicam-se apenas às consultas de páginas em uma seção específica ou consultas para uma página específica.

Exemplos

  • GET ../sections/{section-id}/pages?pagelevel=true
  • GET ../pages/{page-id}?pagelevel=true

Funções e operadores de OData compatíveis

Microsoft Graph é compatível com os seguintes operadores e funções do OData nas expressões de filter. Ao usar expressões de OData, lembre-se:

  • Os espaços na cadeia de caracteres de consulta da URL devem ser substituídos pela codificação %20.

                  Exemplo:filter=isDefault%20eq%20true

  • Os nomes de propriedade e as comparações de cadeias de caracteres de OData diferenciam maiúsculas de minúsculas. É recomendável usar a função tolower do OData para comparações de cadeia de caracteres.

                  Exemplo:filter=tolower(name) eq 'spring'

Operador de comparação Exemplo
eq
(igual a)		 createdByAppId eq '{app-id}'
ne
(é diferente de)		 userRole ne 'Owner'
gt
(maior que)		 createdTime gt 2014-02-23
ge
(maior que ou igual a)		 lastModifiedTime ge 2014-05-05T07:00:00Z
lt
(menor que)		 createdTime lt 2014-02-23
le
(menor que ou igual a)		 lastModifiedTime le 2014-02-23

Operador lógico Exemplo
e createdTime le 2014-01-30 and createdTime gt 2014-01-23
or createdByAppId eq '{app-id}' or createdByAppId eq '{app-id}'
not not contains(tolower(title),'school')

Função da cadeia de caracteres Exemplo
contains contains(tolower(title),'spring')
endswith endswith(tolower(title),'spring')
startswith startswith(tolower(title),'spring')
length length(title) eq 19
indexof indexof(tolower(title),'spring') eq 1
substring substring(tolower(title),1) eq 'spring'
tolower tolower(title) eq 'spring'
toupper toupper(title) eq 'SPRING'
trim trim(tolower(title)) eq 'spring'
concat concat(title,'- by MyRecipesApp') eq 'Carrot Cake Recipe - by MyRecipesApp'

Propriedades de entidade do OneNote

As expressões de consulta filter, select, expand e orderby podem incluir propriedades de entidades do OneNote.

Exemplo

../sections?filter=createdTime ge 2015-01-01&select=name,pagesUrl&orderby=lastModifiedTime desc

Os nomes de propriedades diferenciam maiúsculas de minúsculas em expressões de consulta.

Para obter a lista de propriedades e seus tipos, confira os seguintes recursos na referência do Microsoft Graph API REST:

A opção de cadeia de caracteres de consulta expand pode ser usada com as seguintes propriedades de navegação:

  • Páginas: parentNotebook, parentSection
  • Seções: parentNotebook, parentSectionGroup
  • Grupos de seções: sections, sectionGroups, parentNotebook, parentSectionGroup
  • Blocos de anotações: sections, sectionGroups

Informações de solicitação e resposta para solicitações de GET

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 Accept

application/json para entidades e conjuntos de entidades do OneNote

text/html para conteúdo de página

Dados de resposta Descrição
Código de êxito Um código de status de HTTP 200.
Corpo da resposta Uma representação de OData da entidade ou conjunto de entidades no formato JSON, da página HTML ou dados binários do recurso de arquivo.
Erros Se a solicitação falhar, a API retornará erros no objeto @api.diagnostics no corpo da resposta.
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 Data ao trabalhar com o suporte da Microsoft para solucionar problemas.

Criar a URL raiz do serviço de anotações do Microsoft Graph

A URL raiz do serviço de anotações do Microsoft Graph usa o formato a seguir para todas as chamadas para o Microsoft Graph:

https://graph.microsoft.com/{version}/me/onenote/

O segmento version na URL representa a versão do Microsoft Graph 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.

Use me para o conteúdo do OneNote que o usuário atual pode acessar (exclusivo e compartilhado). Use users/{id} para o conteúdo do OneNote que o usuário especificado (na URL) compartilhou com o usuário atual. Use o Microsoft Graph para obter as IDs de usuário.

Permissões para solicitações GET

Para obter conteúdo ou estrutura do OneNote, você vai precisar solicitar as permissões adequadas.

Os seguintes escopos permitem solicitações GET para Microsoft Graph. Escolha o nível mais baixo de permissões que seu aplicativo precisa para realizar o trabalho.

Escolha entre:

  • Notes.read
  • Notes.ReadWrite
  • Notes.ReadWrite.All

Para saber mais sobre escopos de permissão e como eles funcionam, confira Referência de permissões do Microsoft Graph.

Conteúdo relacionado