Criar páginas do OneNote
Aplica-se a: Blocos de anotações de consumidor no OneDrive | Blocos de anotações empresariais no Microsoft 365
Para criar uma página do OneNote, você envia uma solicitação POST para um ponto de extremidade de pages. Por exemplo:
POST ../notes/sections/{id}/pages
Envie o HTML que define a página no corpo da mensagem. Se a solicitação for bem-sucedida, o Microsoft Graph retornará um código de status de HTTP 201.
Observação
Para saber mais sobre as solicitações POST que você pode enviar para criar seções, grupos de seções e blocos de anotações, consulte nossa referência interativa do REST.
Construir a URI de solicitação
Para construir a URI de solicitação POST, comece com a URL raiz do serviço:
https://graph.microsoft.com/v1.0/me/onenote
Depois acrescente o ponto de extremidade de pages:
Criar uma página em qualquer seção (especificada pelo nome da seção)
.../pages?sectionName=DefaultSectionCriar uma página em qualquer seção (especificada pela ID)
.../sections/{section-id}/pages
Se você estiver criando páginas no bloco de anotações pessoal do usuário, o Microsoft Graph também fornecerá pontos de extremidade que você pode usar para criar páginas no bloco de anotações padrão:
Criar uma página na seção padrão do bloco de anotações padrão
../pages
Sua URI de solicitação completa parecerá com um dos seguintes exemplos:
https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pageshttps://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework
Saiba mais sobre a URL raiz de serviço.
Usar o parâmetro da URL sectionName
As seguintes regras aplicam-se ao usar o parâmetro sectionName para a criação de uma página em uma seção nomeada no bloco de anotações padrão:
Apenas seções de nível superior podem ser referenciadas (não as seções nos grupos de seções).
Se não houver uma seção com o nome especificado no bloco de anotações padrão, a API a criará. Os seguintes caracteres não são permitidos nos nomes de seção:
? * \ / : < > | & # " % ~Os nomes das seções não diferenciam letras maiúsculas de minúsculas para correspondência, mas a diferença entre maiúsculas e minúsculas é preservada ao criar seções. Portanto, "Minha Nova Seção" será exibida assim, mas também seria feita a correspondência de "minha nova seção" nas postagens subsequentes.
Os nomes das seções devem ser codificados por URL. Por exemplo, os espaços devem ser codificados como 20%.
O parâmetro sectionName só é válido com a rota
../notes/pages(não com../notes/sections/{id}/pages).
Como serão criadas seções caso não existam, é seguro usar essa chamada com todas as páginas que o seu aplicativo criar. Os usuários podem renomear as seções, mas a API criará uma nova seção com o nome da seção que você fornecer.
Observação
Os links retornados pela API das páginas de uma seção renomeada ainda abrirão essas páginas antigas.
Criar o corpo da mensagem
O HTML que define o conteúdo da página se chama HTML de entrada. O HTML de entrada é compatível com um subconjunto de HTML e CSS padrão, com a adição de atributos personalizados. (Os atributos personalizados, como data-id e data-render-src, são descritos em HTML de entrada e de saída.)
Envie o HTML de entrada no corpo da mensagem da solicitação POST. Você pode enviar o HTML de entrada diretamente no corpo da mensagem usando o application/xhtml+xml tipo de conteúdo ou text/html ou enviá-lo na parte "Apresentação" de uma solicitação de várias partes.
O exemplo a seguir envia o HTML de entrada diretamente no corpo da mensagem.
POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: application/xhtml+xml
<!DOCTYPE html>
<html>
<head>
<title>A page with a block of HTML</title>
<meta name="created" content="2015-07-22T09:00:00-08:00" />
</head>
<body>
<p>This page contains some <i>formatted</i> <b>text</b> and an image.</p>
<img src="https://..." alt="an image on the page" width="500" />
</body>
</html>
Se você estiver enviando dados binários, use uma solicitação de diversas partes.
Observação
Para simplificar a programação e a consistência em seu aplicativo, use as solicitações de diversas partes para criar todas as páginas. É uma boa ideia usar uma biblioteca para criar mensagens de diversas partes. Isso reduz o risco da criação de cargas mal formadas.
Requisitos e limitações para HTML de entrada em solicitações de páginas POST
Ao enviar HTML de entrada, lembre-se desses requisitos e limitações gerais:
O HTML de entrada deve ser codificado em UTF-8 e Extensible HTML bem elaborado. Todas as marcas de início do contêiner exigem marcas de fechamento correspondentes. Todos os valores do atributo devem estar entre aspas simples ou duplas.
O código JavaScript, os arquivos inclusos e CSS são removidos.
Os formulários HTML são removidos totalmente.
O Microsoft Graph é compatível com um subconjunto de elementos HTML.
O Microsoft Graph é compatível com um subconjunto de atributos HTML comuns e um conjunto de atributos personalizados, como o atributo data-id usado para atualizar as páginas. Confira os atributos compatíveis em HTML de entrada e de saída.
HTML e CSS compatíveis com páginas do OneNote
Nem todos os elementos, atributos e propriedades são compatíveis (em HTML4, Extensible HTML, CSS, HTML5 etc.). Em vez disso, o Microsoft Graph aceita um conjunto limitado de HTML mais adequado à forma como as pessoas usam o OneNote. Saiba mais em Suporte de marca HTML para páginas. Se uma marca não estiver listada aqui, provavelmente será ignorada.
A lista a seguir mostra os tipos de elementos básicos compatíveis com o Microsoft Graph:
-
<head>e<body> -
<title>e<meta>que definem a data de criação e o título de página -
<h1>a<h6>para títulos de seção -
<p>para parágrafos -
<ul>,<ol>e<li>para listas e itens de lista -
<table>,<tr>e<td>, incluindo tabelas aninhadas -
<pre>para texto pré-formatado (preserva as quebras de linha e espaços em branco) -
<b>e<i>para estilos de caractere em negrito e itálico
O Microsoft Graph preserva o conteúdo semântico e a estrutura básica do HTML de entrada ao criar páginas, mas converte o HTML de entrada para usar o conjunto compatível de HTML e CSS. Os recursos que não existem no OneNote não têm nada para ser convertido, portanto, podem não ser reconhecidos no HTML de origem.
Exemplo de solicitação
Esse exemplo de solicitação de diversas partes cria uma página que contém imagens e um arquivo inserido. A parte Apresentação necessária contém o HTML de entrada que define a página. A parte imageBlock1 contém os dados de imagem binária, e fileBlock1 contém os dados do arquivo binário. As partes de dados também podem conter HTML e, nesse caso, o Microsoft Graph processa o HTML como uma imagem na página do OneNote.
POST https://graph.microsoft.com/v1.0/me/onenote/pages
Authorization: Bearer {token}
Content-Type: multipart/form-data; boundary=MyPartBoundary198374
--MyPartBoundary198374
Content-Disposition:form-data; name="Presentation"
Content-Type:text/html
<!DOCTYPE html>
<html>
<head>
<title>A page with rendered images and an attached file</title>
<meta name="created" content="2015-07-22T09:00:00-08:00" />
</head>
<body>
<p>Here's an image from an <i>online source</i>:</p>
<img src="https://..." alt="an image on the page" width="500" />
<p>Here's an image uploaded as <b>binary data</b>:</p>
<img src="name:imageBlock1" alt="an image on the page" width="300" />
<p>Here's a file attachment:</p>
<object data-attachment="FileName.pdf" data="name:fileBlock1" type="application/pdf" />
</body>
</html>
--MyPartBoundary198374
Content-Disposition:form-data; name="imageBlock1"
Content-Type:image/jpeg
... binary image data ...
--MyPartBoundary198374
Content-Disposition:form-data; name="fileBlock1"
Content-Type:application/pdf
... binary file data ...
--MyPartBoundary198374--
Para obter mais exemplos que mostram como criar páginas que contêm imagens e outros arquivos, consulte Adicionar imagens e arquivos, nossos tutoriais e nossos exemplos. Além disso, saiba como criar elementos posicionados absolutos, usar marcas de anotação e extrair dados para capturas de cartão de visita e as listagens online de receitas e de produtos.
O Microsoft Graph é rigoroso com certos formatos, como novas linhas CRLF em um corpo da mensagem de diversas partes. Para reduzir o risco de criar cargas mal formadas, você deve usar uma biblioteca para criar mensagens de diversas partes.
Se você receber o status 400 para uma carga mal formada, verifique a formatação de novas linhas e espaços em branco e verifique se há problemas de codificação. Por exemplo, tente usar charset=utf-8 (exemplo: Content-Type: text/html; charset=utf-8).
Consulte Requisitos e limitações do HTML de entrada e Limites de tamanho para solicitações POST.
Informações de solicitação e resposta para solicitações de páginas POST
| Dados da solicitação | Descrição |
|---|---|
| Protocolo | Todas as solicitações usam o protocolo HTTPS de SSL/TLS. |
| Cabeçalho de autorização |
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 |
As solicitações de diversas partes são necessárias quando se enviam dados binários e usam o tipo de conteúdo |
| Cabeçalho Accept | application/json |
| Dados de resposta | Descrição |
|---|---|
| Código de êxito | Um código de status HTTP 201. |
| Corpo da resposta | Uma representação OData da nova página no formato JSON. |
| Erros | Se a solicitação falhar, a API retornará erros no objeto @api.diagnostics no corpo da resposta. |
| Cabeçalho location | A URL do recurso para a nova página. |
| 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 do Microsoft Graph
A URL raiz do serviço 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.
Limitações de tamanho de seção do OneNote
Há um limite para o número de páginas que você pode adicionar a uma seção usando a API do OneNote. Quando esse limite é atingido em uma seção e é feita uma tentativa de criar uma nova página nessa seção, você verá uma resposta com o código de status HTTP 507 e a mensagem "O número máximo de páginas permitido por seção foi excedido". Para obter mais informações sobre esse código de erro, consulte Códigos de erro do OneNote.
Você pode usar uma das seguintes soluções alternativas:
- Crie uma nova seção e adicione novas páginas.
- Exclua páginas não utilizadas de uma seção existente que atingiu o limite de páginas.
Permissões
Para criar 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.
Escolha entre:
- Notes.Create
- 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.