Atualizar o conteúdo da página do OneNoteUpdate OneNote page content

Aplica-se a Blocos de anotações do consumidor no OneDrive | Blocos de anotações empresariais no Microsoft 365Applies to Consumer notebooks on OneDrive | Enterprise notebooks on 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:To update the content of a OneNote page, you send a PATCH request to the page's content endpoint:

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.Send a JSON change object in the message body. If the request is successful, Microsoft Graph returns a 204 HTTP status code.

Construir a URI de solicitaçãoConstruct the request URI

Para construir a URI de solicitação, comece com a URL raiz do serviço:To construct the request URI, start with the service root URL:

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


Acrescente então o ponto de extremidade do conteúdo da página:Then append the page's content endpoint:

  • Obter o HTML da página e todos os valores de data-id definidosGet the page HTML and all defined data-id values

    ../pages/{id}/content

  • Obter o HTML da página, todos os valores de data-id definidos e todos os valores de id geradosGet the page HTML, all defined data-id values, and all generated id values

    ../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.The data-id and id values are used as target identifiers for the elements you want to update.

Sua solicitação de URI completa terá a seguinte aparência:Your full request URI will look like this:

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

Saiba mais sobre a URL raiz de serviço.Learn more about the service root URL.

Criar o corpo da mensagemConstruct the message body

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.The HTML of a OneNote page contains text, images, and other content organized into structures such as div, img, and ol elements. Para atualizar o conteúdo da página do OneNote, adicione e substitua elementos HTML na página.To update OneNote page content, you add and replace HTML elements on the page.

Suas alterações serão enviadas no corpo da mensagem como uma matriz de objetos de alteração JSON.Your changes are sent in the message body as an array of JSON change objects. Cada objeto especifica o elemento de destino, o novo conteúdo HTML e o que fazer com o conteúdo.Each object specifies the target element, new HTML content, and what to do with the content.

A matriz a seguir define duas alterações.The following array defines two changes. 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.The first inserts an image above a paragraph as a sibling, and the second appends an item to a list as a last child.

Observação

Ao atualizar uma imagem em uma página do OneNote, você não pode usar links da www.When updating an image on a OneNote page, you can't use www links. O serviço não tentará baixar recursos aleatórios.The service won't try to download random resources. Em vez disso, a imagem deve fazer parte da solicitação, seja por uma URL de dados de imagem ou um nome de parte de uma solicitação com diversas partes.Instead, the image must be part of the request, either by an image-data-url or a part-name of a multipart request.

[
   {
    '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.See more examples.

Atributos de objetos de alteração JSONAttributes for JSON change objects

Use atributos target, action, position e content para definir objetos JSON para solicitações de PATCH.Use the target, action, position, and content attributes to define JSON objects for PATCH requests.

destinotarget

O elemento a ser atualizado.The element to update. O valor deve ser uma dos seguintes identificadores:The value must be one of the following identifiers:

IdentificadorIdentifier DescriçãoDescription
#{data-id}#{data-id}

Essa ID é opcionalmente definida em elementos na HTML de entrada ao criar uma página ou atualizar uma página.This ID is optionally defined on elements in the input HTML when creating a page or updating a page. Coloque um # como prefixo do valor.Prefix the value with a #.

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

idid

É a ID gerada do Microsoft Graph e é necessário para a maioria das operações de substituição.This is the generated ID from Microsoft Graph, and is required for most replace operations. Não use # como prefixo.Do not prefix with a #.

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

Não confunda esses identificadores com valores de id definidos no HTML de entrada.Don't confuse these with any id values defined in the input HTML. Todos os valores de id enviados no HTML de entrada são descartados.All id values sent in the input HTML are discarded.

corpobody A palavra-chave que tem como destino o primeiro div na página.The keyword that targets the first div on the page. Não use # como prefixo.Do not prefix with a #.
titletitle A palavra-chave que tem como destino o título da página.The keyword that targets the page title. Não use # como prefixo.Do not prefix with a #.

actionaction

A ação a ser executada no elemento de destino.The action to perform on the target element. Veja as ações com suporte para elementos.See supported actions for elements.

AçãoAction DescriçãoDescription
appendappend

Adiciona o conteúdo fornecido ao destino como primeiro ou último filho, conforme determinado pelo atributo position.Adds the supplied content to the target as a first or last child, as determined by the position attribute.

Aplicável somente a elementos body, div, ol e ul.Applies only to body, div, ol, and ul elements.

insertinsert Adiciona o conteúdo fornecido como irmão antes ou depois do destino, conforme determinado pelo atributo position.Adds the supplied content as a sibling before or after the target, as determined by the position attribute.
prependprepend

Adiciona o conteúdo fornecido ao destino como um primeiro filho.Adds the supplied content to the target as a first child. Atalho para append + before.Shortcut for append + before.

Aplicável somente a elementos body, div, ol e ul.Applies only to body, div, ol, and ul elements.

replacereplace

Substitui o destino pelo conteúdo fornecido.Replaces the target with the supplied content.

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).Most replace actions require using the generated ID for the target (except img and object elements within a div, which also support using data-id).

positionposition

O local para adicionar o conteúdo fornecido em relação ao elemento de destino.The location to add the supplied content, relative to the target element. Usa o padrão after caso seja omitido.Defaults to after if omitted.

PosiçãoPosition DescriçãoDescription
after (padrão)after (default)

Com append: último filho do elemento de destino.With append: The last child of the target element.

Com insert: o irmão subsequente do elemento de destino.With insert: The subsequent sibling of the target element.

beforebefore

Com append: primeiro filho do elemento de destino.With append: The first child of the target element.

Com insert: o irmão precedente do elemento de destino.With insert: The preceding sibling of the target element.

contentcontent

Uma cadeia de caracteres em HTML bem formado para adicionar à página e dados binários de imagem ou arquivo.A string of well-formed HTML to add to the page, and any image or file binary data. 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.)If the content contains binary data, the request must be sent using the multipart/form-data content type with a "Commands" part (see an example).

IDs geradasGenerated IDs

O Microsoft Graph gera valores de id para que os elementos na página possam ser atualizados.Microsoft Graph generates id values for the elements on the page that can be updated. Para obter as IDs geradas, use a expressão de cadeia de caracteres de consulta includeIDs=true na sua solicitação GET:To get generated IDs, use the includeIDs=true query string expression in your GET request:

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

Observação: a API descarta todos os valores de id na HTML de entrada das solicitações de criar página e atualizar página.Note: The API discards all id values that are defined in the input HTML of create-page and update-page requests.

O exemplo a seguir mostra IDs geradas para um parágrafo e uma imagem no HTML de saída de uma página.The following example shows generated IDs for a paragraph and an image in the output HTML of a page.

<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.Generated id values might change after a page update, so you should get the current values before building a PATCH request that uses them.

Você pode especificar elementos de destino usando os valores data-id ou id seguinte maneira:You can specify target elements by using the data-id or id value, as follows:

  • Para as ações append e insert, você pode usar o ID como o valor de destino.For append and insert actions, you can use either ID as the target value.
  • 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.For replace actions, you must use the generated ID for all elements except for the page title and images and objects that are within a div.
    • Para substituir um título, use a palavra-chave título.To replace a title, use the title keyword.
    • Para substituir imagens e objetos que estejam dentro de um div, use data-id ou id.To replace images and objects that are within a div, use either data-id or id.

O exemplo a seguir usa o valor id para o destino.The following example uses the id value for the target. Não use o prefixo # com um ID gerado.Don't use the # prefix with a generated ID.

[
   {
    '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íveisSupported elements and actions

Muitos elementos na página podem ser atualizados, mas cada tipo de elemento é compatível com ações específicas.Many elements on the page can be updated, but each element type supports specific actions. A tabela a seguir mostra os elementos de destino compatíveis com as ações de atualização a que eles dão suporte.The following table shows supported target elements and the update actions that they support.

ElementoElement SubstituirReplace Anexar filhoAppend child Inserir irmãoInsert sibling
bodybody
(tem como destino o primeiro div na página)(targets first div on the page)
nãono simyes nãono
divdiv
(absoluto posicionado)(absolute positioned)
nãono simyes nãono
divdiv
(em um div)(within a div)
simyes
(somente id)(id only)
simyes simyes
img, objectimg, object
(em um div)(within a div)
simyes nãono simyes
ol, ulol, ul simyes
(somente id)(id only)
simyes simyes
tabletable simyes
(somente id)(id only)
nãono simyes
p, li, h1-h6p, li, h1-h6 simyes
(somente id)(id only)
nãono simyes
titletitle simyes nãono nãono

Os seguintes elementos não dão suporte a nenhuma ação de atualização.The following elements do not support any update actions.

Solicitações de exemploExample requests

Uma solicitação de atualização contém um ou mais alterações representadas como objetos de alteração JSON.An update request contains one or more changes represented as JSON change objects. Esses objetos podem definir destinos diferentes na página e outras ações e conteúdos diferentes para os destinos.These objects can define different targets on the page and different actions and content for the targets.

Os exemplos a seguir contêm objetos JSON usados em solicitações de PATCH e solicitações de PATCH completo:The following examples include JSON objects used in PATCH requests and complete PATCH requests:

Acrescentar elementos filhoAppend child elements

A ação append adiciona um filho a um elemento body, div (dentro de um div), ol ou ul.The append action adds a child to a body, div (within a div), ol, or ul element. O atributo position determina se deve acrescentar o filho antes ou depois do destino.The position attribute determines whether to append the child before or after the target. A posição padrão é after.The default position is after.

Acrescentar a um divAppend to a div

O exemplo a seguir adiciona dois nós filho ao elemento div1.The following example adds two child nodes to the div1 element. Ele adiciona uma imagem como primeiro filho e um parágrafo como último filho.It adds an image as the first child and a paragraph as the last child.

[
 {
    '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 bodyAppend to the body element

Você pode usar o atalho body para acrescentar um elemento filho dentro o primeiro div em qualquer página.You can use the body shortcut to append a child element inside the first div on any page.

O exemplo a seguir adiciona dois parágrafos como primeiro filho e último filho ao primeiro div na página.The following example adds two paragraphs as the first child and the last child to the first div on the page. Não use # com o destino body.Don't use a # with the body target. Este exemplo usa a ação prepend como um atalho para append + before.This example uses the prepend action as a shortcut for 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 listaAppend to a list

O exemplo a seguir adiciona um item de lista como um último filho à lista de destino.The following example adds a list item as a last child to the target list. A propriedade list-style-type é definida porque o item usa um estilo de lista não padrão.The list-style-type property is defined because the item uses a non-default list style.

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

Inserir elementos irmãosInsert sibling elements

A ação insert adiciona irmão a um elemento de destino.The insert action adds a sibling to the target element. O atributo position determina se deve inserir o irmão antes ou depois do destino.The position attribute determines whether to insert the sibling before or after the target. A posição padrão é after.The default position is after. Ver elementos compatíveis com insert.See elements that support insert.

Inserir irmãosInsert siblings

O exemplo a seguir adiciona dois nós irmãos à página.The following example adds two sibling nodes to the page. Adiciona uma imagem acima do elemento para1 elemento e um parágrafo abaixo do elemento para2.It adds an image above the para1 element and a paragraph below the para2 element.

[
  {
     '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 elementosReplace elements

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.You can use either the data-id or generated id as the target value to replace img and object elements that are within a div. Para substituir um título de página, use a palavra-chave title.To replace the page title, use the title keyword. Para todos os outros elementos compatíveis com replace, você deve usar o ID gerado.For all other elements that support replace, you must use the generated ID.

Substituir uma imagemReplace an image

O exemplo a seguir substitui uma imagem por um div usando a data-id da imagem como destino.The following example replaces an image with a div by using the image's data-id as the target.

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

Atualizar um tabelaUpdate a table

Este exemplo mostra como atualizar uma tabela usando seu ID gerado.This example shows how to update a table by using its generated ID. A substituição dos elementos tr e td não tem suporte, mas você pode substituir a tabela inteira.Replacing tr and td elements is not supported, but you can replace the entire table.

[
  {
    '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ítuloChange the title

Este exemplo mostra como alterar o título da página.This example shows how to change the title of a page. Para alterar o título, use a palavra-chave title como o valor de destino.To change the title, use the title keyword as the target value. Não use # com o destino de título.Don't use a # with the title target.

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

Atualizar um item pendenteUpdate a to-do item

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.The following example uses the replace action to change a to-do check box item to a completed state.

[
  {
    'target':'#task1',
    '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.See Use note tags for more about using the data-tag attribute.

Exemplos de solicitação de PATCH completoComplete PATCH request examples

Os exemplos a seguir mostram solicitações de PATCH completo.The following examples show complete PATCH requests.

Solicitar apenas com conteúdo de textoRequest with text content only

O exemplo a seguir mostra uma solicitação de PATCH que usa o tipo de conteúdo application/json.The following example shows a PATCH request that uses the application/json content type. Você pode usar esse formato quando seu conteúdo não contém dados binários.You can use this format when your content doesn't contain binary data.

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árioMultipart request with binary content

O exemplo a seguir mostra uma solicitação de PATCH de diversas partes que inclui dados binários.The following example shows a multipart PATCH request that includes binary data. 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.Multipart requests require a "Commands" part that specifies the application/json content type and contains the array of JSON change objects. Outras partes de dados podem conter dados binários.Other data parts can contain binary data. Os nomes de partes são geralmente cadeias de caracteres acrescentadas com a hora atual em milissegundos ou um GUID aleatório.Part names typically are strings appended with the current time in milliseconds or a random GUID.

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 PATCHRequest and response information for PATCH requests

Dados da solicitaçãoRequest data DescriçãoDescription
ProtocoloProtocol Todas as solicitações usam o protocolo HTTPS de SSL/TLS.All requests use the SSL/TLS HTTPS protocol.
Cabeçalho de autorizaçãoAuthorization header

Bearer {token}, onde {token} é um token de acesso do OAuth 2.0 válido para o aplicativo registrado.Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

Se ele estiver ausente ou for inválido, a solicitação falhará com um código de status 401.If missing or invalid, the request fails with a 401 status code. Confira Autenticação e permissões.See Authentication and permissions.

Cabeçalho content-typeContent-Type header

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.application/json for the array of JSON change objects, whether sent directly in the message body or in the required "Commands" part of multipart requests.

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.Multipart requests are required when sending binary data, and use the multipart/form-data; boundary=part-boundary content type, where {part-boundary} is a string that signals the start and end of each data part.


Dado de respostaResponse data DescriçãoDescription
Código de êxitoSuccess code Um código de status de HTTP 204.A 204 HTTP status code. Nenhum dado JSON é retornado para uma solicitação PATCH.No JSON data is returned for a PATCH request.
ErrosErrors 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.Read Error codes for OneNote APIs in Microsoft Graph to learn about OneNote errors that Microsoft Graph can return.

Criar a URL raiz do serviço do Microsoft GraphConstructing the Microsoft Graph service root URL

A URL raiz do serviço do OneNote usa o formato a seguir para todas as chamadas para o OneNote:The OneNote service root URL uses the following format for all calls to the OneNote API:

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

O segmento version na URL representa a versão do Microsoft Graph que você deseja usar.The version segment in the URL represents the version of Microsoft Graph that you want to use. v1.0 serve para o código de produção estável.v1.0 is for stable production code. beta serve para experimentar um recurso que está em desenvolvimento.beta is to try out a feature that's in development. 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.Features and functionality in beta may change, so you shouldn't use it in your production code.

me serve para o conteúdo do OneNote que o usuário atual pode acessar (exclusivo e compartilhado).me is for OneNote content that the current user can access (owned and shared). users/{id} serve para o conteúdo do OneNote que o usuário especificado (na URL) compartilhou com o usuário atual.users/{id} is for OneNote content that the specified user (in the URL) has shared with the current user. Use a API do Microsoft Azure AD Graph.Use the Azure AD Graph API.

Observação: para obter as ids de usuário, faça uma solicitação GET em https://graph.microsoft.com/v1.0/users.Note: You can get user ids by making a GET request on https://graph.microsoft.com/v1.0/users.

PermissõesPermissions

Para atualizar páginas do OneNote, solicite as permissões apropriadas.To update OneNote pages, you'll need to request appropriate permissions. Escolha o nível mais baixo de permissões que seu aplicativo precisa para realizar o trabalho.Choose the lowest level of permissions that your app needs to do its work.

  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

Para saber mais sobre escopos de permissão e como eles funcionam, confira Escopos de permissão do OneNote.For more information about permission scopes and how they work, see OneNote permission scopes.

Confira tambémSee also