Compartilhar via

Atualizar o conteúdo da página do OneNote

  • Artigo

Aplica-se a Notebooks de consumidores no OneDrive | Notebooks corporativos no Microsoft 365

Para atualizar o conteúdo de uma página do OneNote, envie uma solicitação de PATCH para o ponto de extremidade do conteúdo da página:

PATCH ../notes/pages/{id}/content

Envie um objeto de alteração JSON no corpo da mensagem. Se a solicitação for bem-sucedida, o Microsoft Graph retornará um código de status de HTTP 204.

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


Acrescente então o ponto de extremidade do conteúdo da página:

  • Obter o HTML da página e todos os valores de data-id definidos

    ../pages/{id}/content

  • Obter o HTML da página, todos os valores de data-id definidos e todos os valores de id gerados

    ../pages/{page-id}/content?includeIDs=true

A data-id e os valores de id são usados como identificadores de destino para elementos que você deseja atualizar.

Sua solicitação de URI completa terá a seguinte aparência:

https://graph.microsoft.com/v1.0/me/onenote/pages/{id}/content

Saiba mais sobre a URL raiz de serviço.

Criar o corpo da mensagem

O HTML de uma página do OneNote contém texto, imagens e outros conteúdos organizados em estruturas como elementos div, img e ol. Para atualizar o conteúdo da página do OneNote, adicione e substitua elementos HTML na página.

Suas alterações serão enviadas no corpo da mensagem como uma matriz de objetos de alteração JSON. Cada objeto especifica o elemento de destino, o novo conteúdo HTML e o que fazer com o conteúdo.

A matriz a seguir define duas alterações. A primeira insere uma imagem acima de um parágrafo como um irmão, e a segunda acrescenta um item em uma lista como um último filho.

Observação

Ao atualizar uma imagem em uma página do OneNote, você não pode usar links www. O serviço não tentará baixar recursos aleatórios. Em vez disso, a imagem deve fazer parte da solicitação, seja por uma imagem-data-url ou por um nome de parte de uma solicitação multipart.

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-data-url-or-part-name" alt="Image above the target paragraph" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the end of the list</li>'
  }
]

Veja mais exemplos.

Atributos de objetos de alteração JSON

Use atributos target, action, position e content para definir objetos JSON para solicitações de PATCH.

destino

O elemento a ser atualizado. O valor deve ser uma dos seguintes identificadores:

Identificador Descrição
#{data-id}

Essa ID é opcionalmente definida em elementos na HTML de entrada ao criar uma página ou atualizar uma página. Coloque um # como prefixo do valor.

Exemplo:
'target':'#intro' tem como destino o elemento <div data-id="intro" ...>
id

É a ID gerada do Microsoft Graph e é necessário para a maioria das operações de substituição. Não use # como prefixo.

Exemplo:
'target':'div:{33f8a2...}{37}' tem como destino o elemento <div id="div:{33f8a2...}{37}" ...>

Não confunda esses identificadores com valores de id definidos no HTML de entrada. Todos os valores de id enviados no HTML de entrada são descartados.
body A palavra-chave que tem como destino o primeiro div na página. Não use # como prefixo.
title A palavra-chave que tem como destino o título da página. Não use # como prefixo.

action

A ação a ser executada no elemento de destino. Veja as ações com suporte para elementos.

Ação Descrição
append

Adiciona o conteúdo fornecido ao destino como primeiro ou último filho, conforme determinado pelo atributo position.

Aplicável somente a elementos body, div, ol e ul.
insert Adiciona o conteúdo fornecido como irmão antes ou depois do destino, conforme determinado pelo atributo position.
prepend

Adiciona o conteúdo fornecido ao destino como um primeiro filho. Atalho para append + before.

Aplicável somente a elementos body, div, ol e ul.
replace

Substitui o destino pelo conteúdo fornecido.

A maioria das ações replace exige o uso de ID gerada para o destino (exceto os elementos img e object em um div, que também é compatível com o uso de data-id).

position

O local para adicionar o conteúdo fornecido em relação ao elemento de destino. Usa o padrão after caso seja omitido.

Posição Descrição
after (padrão)

Com append: último filho do elemento de destino.

Com insert: o irmão subsequente do elemento de destino.
before

Com append: primeiro filho do elemento de destino.

Com insert: o irmão precedente do elemento de destino.

content

Uma cadeia de caracteres em HTML bem formado para adicionar à página e dados binários de imagem ou arquivo. Se o conteúdo contiver dados binários, a solicitação deverá ser enviada usando o tipo de conteúdo multipart/form-data com uma parte "Commands" (veja um exemplo.)

IDs geradas

O Microsoft Graph gera valores de id para que os elementos na página possam ser atualizados. Para obter as IDs geradas, use a expressão de cadeia de caracteres de consulta includeIDs=true na sua solicitação GET:

GET ../notes/pages/{page-id}/content?includeIDs=true

Observação

A API descarta todos os valores de ID definidos no HTML de entrada de solicitações de página de criação e de página de atualização.

O exemplo a seguir mostra IDs geradas para um parágrafo e uma imagem no HTML de saída de uma página.

<p id="p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}">Some text on the page</p>
<img id="img:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{45}" ... />

Os valores de id gerados podem ser alterados após uma atualização de página. Então você deve obter valores atuais antes de criar uma solicitação de PATCH que usa esses valores.

Você pode especificar elementos de destino usando os valores data-id ou id seguinte maneira:

  • Para as ações append e insert, você pode usar o ID como o valor de destino.
  • Para as ações replace, use o ID gerado para todos os elementos, exceto o título da página e imagens e objetos que estejam dentro de um div.
    • Para substituir um título, use a palavra-chave título.
    • Para substituir imagens e objetos que estejam dentro de um div, use data-id ou id.

O exemplo a seguir usa o valor id para o destino. Não use o prefixo # com um ID gerado.

[
   {
    'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
    'action':'insert',
    'position':'before',
    'content':'<p>This paragraph goes above the target paragraph.</p>'
  }
]

Elementos e ações compatíveis

Muitos elementos na página podem ser atualizados, mas cada tipo de elemento é compatível com ações específicas. A tabela a seguir mostra os elementos de destino compatíveis com as ações de atualização a que eles dão suporte.

Elemento Substituir Anexar filho Inserir irmão
body
(tem como destino o primeiro div na página)		 não sim não
div
(absoluto posicionado)		 não sim não
div
(em um div)		 sim
(somente id)		 sim sim
img, object
(em um div)		 sim não sim
ol, ul sim
(somente id)		 sim sim
table sim
(somente id)		 não sim
p, li, h1-h6 sim
(somente id)		 não sim
title sim não não

Os seguintes elementos não dão suporte a nenhuma ação de atualização.

Solicitações de exemplo

Uma solicitação de atualização contém um ou mais alterações representadas como objetos de alteração JSON. Esses objetos podem definir destinos diferentes na página e outras ações e conteúdos diferentes para os destinos.

Os exemplos a seguir contêm objetos JSON usados em solicitações de PATCH e solicitações de PATCH completo:

Acrescentar elementos filho

A ação append adiciona um filho a um elemento body, div (dentro de um div), ol ou ul. O atributo position determina se deve acrescentar o filho antes ou depois do destino. A posição padrão é after.

Acrescentar a um div

O exemplo a seguir adiciona dois nós filho ao elemento div1. Ele adiciona uma imagem como primeiro filho e um parágrafo como último filho.

[
 {
    'target':'#div1',
    'action':'append',
    'position':'before',
    'content':'<img data-id="first-child" src="image-url-or-part-name" />'
  },
  {
    'target':'#div1',
    'action':'append',
    'content':'<p data-id="last-child">New paragraph appended to the div</p>'
  }
]

Acrescentar ao elemento body

Você pode usar o atalho body para acrescentar um elemento filho dentro o primeiro div em qualquer página.

O exemplo a seguir adiciona dois parágrafos como primeiro filho e último filho ao primeiro div na página. Não use # com o destino body. Este exemplo usa a ação prepend como um atalho para append + before.

[
  {
    'target':'body',
    'action':'prepend',
    'content':'<p data-id="first-child">New paragraph as first child in the first div</p>'
  },
  {
    'target':'body',
    'action':'append',
    'content':'<p data-id="last-child">New paragraph as last child in the first div</p>'
  }
]

Acrescentar a uma lista

O exemplo a seguir adiciona um item de lista como um último filho à lista de destino. A propriedade list-style-type é definida porque o item usa um estilo de lista não padrão.

[
  {
    'target':'#circle-ul',
    'action':'append',
    'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
  }
]

Inserir elementos irmãos

A ação insert adiciona irmão a um elemento de destino. O atributo position determina se deve inserir o irmão antes ou depois do destino. A posição padrão é after. Ver elementos compatíveis com insert.

Inserir irmãos

O exemplo a seguir adiciona dois nós irmãos à página. Adiciona uma imagem acima do elemento para1 elemento e um parágrafo abaixo do elemento para2.

[
  {
     'target':'#para1',
     'action':'insert',
     'position':'before',
     'content':'<img src="image-data-url-or-part-name" alt="Image inserted above the target" />'
  },
  {
    'target':'#para2',
     'action':'insert',
     'content':'<p data-id="next-sibling">Paragraph inserted below the target</p>'
  }
]

Substituir elementos

Você pode usar data-id ou id gerado como o valor de destino para substituir os elementos img e object que estão em um div. Para substituir um título de página, use a palavra-chave title. Para todos os outros elementos compatíveis com replace, você deve usar o ID gerado.

Substituir uma imagem

O exemplo a seguir substitui uma imagem por um div usando a data-id da imagem como destino.

[
  {
    'target':'#img1',
    'action':'replace',
    'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
  }
]

Atualizar um tabela

Este exemplo mostra como atualizar uma tabela usando seu ID gerado. A substituição dos elementos tr e td não tem suporte, mas você pode substituir a tabela inteira.

[
  {
    'target':'table:{de3e0977-94e4-4bb0-8fee-0379eaf47486}{11}',
    'action':'replace',
    'content':'<table data-id="football">
      <tr><td><p><b>Brazil</b></p></td><td><p>Germany</p></td></tr>
      <tr><td><p>France</p></td><td><p><b>Italy</b></p></td></tr>
      <tr><td><p>Netherlands</p></td><td><p><b>Spain</b></p></td></tr>
      <tr><td><p>Argentina</p></td><td><p><b>Germany</b></p></td></tr></table>'
  }
]

Alterar o título

Este exemplo mostra como alterar o título da página. Para alterar o título, use a palavra-chave title como o valor de destino. Não use # com o destino de título.

[
  {
    'target':'title',
    'action':'replace',
    'content':'New title'
  }
]

Atualizar um item pendente

O exemplo a seguir usa a ação de substituir para alterar um item de caixa de seleção pendente para um estado concluído.

[
  {
    'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
    'action':'replace',
    'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
  }
]

Veja Usar marcas de anotação para saber mais sobre como usar o atributo data-tag.

Exemplos de solicitação de PATCH completo

Os exemplos a seguir mostram solicitações de PATCH completo.

Solicitar apenas com conteúdo de texto

O exemplo a seguir mostra uma solicitação de PATCH que usa o tipo de conteúdo application/json. Você pode usar esse formato quando seu conteúdo não contém dados binários.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-data-url" alt="New image from a URL" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

Solicitação de partes múltiplas com conteúdo binário

O exemplo a seguir mostra uma solicitação de PATCH de diversas partes que inclui dados binários. As solicitações de diversas partes exigem uma parte de "Comandos" que especifica o tipo de conteúdo application/json e contém a matriz de objetos de alteração JSON. Outras partes de dados podem conter dados binários. Os nomes de partes são geralmente cadeias de caracteres acrescentadas com a hora atual em milissegundos ou um GUID aleatório.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: multipart/form-data; boundary=PartBoundary123
Authorization: Bearer {token}

--PartBoundary123
Content-Disposition: form-data; name="Commands"
Content-Type: application/json

[
  {
    'target':'img:{2998967e-69b3-413f-a221-c1a3b5cbe0fc}{42}',
    'action':'replace',
    'content':'<img src="name:image-part-name" alt="New binary image" />'
  }, 
  {
    'target':'#list-id',
    'action':'append',
    'content':'<li>Item at the bottom of the list</li>'
  }
]

--PartBoundary123
Content-Disposition: form-data; name="image-part-name"
Content-Type: image/png

... binary image data ...

--PartBoundary123--

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

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 content-type

application/json para a matriz de objetos de alteração JSON, seja enviado diretamente no corpo da mensagem, seja na parte "Comandos" obrigatória de solicitações de diversas partes.

As solicitações de diversas partes são necessárias quando se enviam dados binários e usam o tipo de conteúdo multipart/form-data; boundary=part-boundary, onde {part-boundary} é uma cadeia de caracteres que sinaliza o início e o término de cada parte de dados.

Dados de resposta Descrição
Código de êxito Um código de status de HTTP 204. Nenhum dado JSON é retornado para uma solicitação PATCH.
Erros Leia Códigos de erro para APIs do OneNote no Microsoft Graph para saber mais sobre erros do OneNote que poderão ser retornados pelo Microsoft Graph.

Criar a URL raiz do serviço do Microsoft Graph

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

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

O segmento version na URL representa a versão do Microsoft Graph que você deseja usar. v1.0 serve para o código de produção estável. beta serve 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.

me serve para o conteúdo do OneNote que o usuário atual pode acessar (exclusivo e compartilhado). users/{id} serve para o conteúdo do OneNote que o usuário especificado (na URL) compartilhou com o usuário atual. Use a API de usuários.

Observação

Você pode obter ids de usuário fazendo uma solicitação GET em https://graph.microsoft.com/v1.0/users.

Permissões

Para atualizar páginas do OneNote, solicite as permissões apropriadas. Escolha o nível mais baixo de permissões que seu aplicativo precisa para realizar o trabalho.

  • Notes.ReadWrite
  • Notes.ReadWrite.All

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

Conteúdo relacionado