Crear páginas de OneNoteCreate OneNote pages

Se aplica a: Blocs de notas para consumidores de OneDrive | Blocs de notas empresariales de Office 365Applies to: Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

Para crear una página de OneNote, envíe una solicitud POST al punto de conexión pages.To create a OneNote page, you send a POST request to a pages endpoint. Por ejemplo:For example:

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


Envíe el código HTML que define la página en el cuerpo del mensaje.Send the HTML that defines the page in the message body. Si la solicitud se completa correctamente, Microsoft Graph devuelve un código de estado HTTP 201.If the request is successful, Microsoft Graph returns a 201 HTTP status code.

Nota: Para obtener información sobre las solicitudes POST que puede enviar para crear secciones, grupos de secciones y blocs de notas, vea la referencia de REST interactiva.Note: To learn about the POST requests you can send to create sections, section groups, and notebooks, see our interactive REST reference.

Crear el URI de la solicitudConstruct the request URI

Para crear el URI de la solicitud POST, empiece con la dirección URL raíz del servicio:To construct the POST request URI, start with the service root URL:

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


Después, anexe el punto de conexión pages:Then append the pages endpoint:

  • Crear una página en cualquier sección (especificado por el nombre de sección)Create a page in any section (specified by section name)

    .../pages?sectionName=DefaultSection

  • Crear una página en cualquier sección (especificado por el id.)Create a page in any section (specified by ID)

    .../sections/{section-id}/pages

Si va a crear páginas en el bloc de notas personal del usuario, Microsoft Graph también proporciona puntos de conexión que puede usar para crear páginas en el bloc de notas predeterminado:If you're creating pages in the user's personal notebook, Microsoft Graph also provides endpoints you can use to create pages in the default notebook:

  • Crear una página de OneNote en la sección predeterminada del bloc de notas predeterminadoCreate a page in the default section of the default notebook

    ../pages

La URI de la solicitud completa tendrá un aspecto similar a uno de estos ejemplos:Your full request URI will look like one of these examples:

  • https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pages
  • https://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework

Obtenga más información sobre la URL de raíz del servicio.Learn more about the service root URL.

Usar el parámetro de URL sectionNameUsing the sectionName URL parameter

Las reglas siguientes se aplican al usar el parámetro sectionName para crear una página en una sección con nombre del bloc de notas predeterminado:The following rules apply when using the sectionName parameter to create a page in a named section in the default notebook:

  • Solo se puede hacer referencia a las secciones de nivel superior (no a las secciones dentro de grupos de secciones).Only top-level sections can be referenced (not sections within section groups).

  • Si en el bloc de notas predeterminado no existe una sección con el nombre especificado, la API la creará.If a section with the specified name doesn't exist in the default notebook, the API creates it. Los caracteres siguientes no pueden usarse en los nombres de sección: ? * \ / : < > | & # " % ~These characters are not allowed for section names: ? * \ / : < > | & # " % ~

  • Los nombres de sección no distinguen mayúsculas de minúsculas, pero el uso de mayúsculas se conserva al crear las secciones.Section names are case-insensitive for matching, but case is preserved when sections are created. Por lo tanto, “Mi nueva sección” se mostrará de esa forma, pero “mi nueva sección” también coincidirá en las publicaciones posteriores.So "My New Section" will display like that, but "my new section" would also match on subsequent posts.

  • Los nombres de sección necesitan tener el formato de codificación URL.Section names must be URL-encoded. Por ejemplo, los espacios tienen que codificarse como %20.For example, spaces must be encoded as %20.

  • El parámetro sectionName solo es válido con la ruta ../notes/pages (pero no con ../notes/sections/{id}/pages).The sectionName parameter is valid only with the ../notes/pages route (not ../notes/sections/{id}/pages).

Como se crearán secciones si no existen, es seguro usar esta llamada con todas las páginas que cree la aplicación.Because sections are created if they don't exist, it's safe to use this call with every page your app creates. Aunque los usuarios pueden cambiar el nombre de las secciones, la API creará una sección con el nombre de sección que especifique.Users might rename sections, but the API will create a new section with the section name that you supply.

Nota: Los vínculos devueltos por la API para las páginas en una sección con un nombre cambiado también llegarán a las páginas anteriores.Note: The links returned by the API for pages in a renamed section will still reach those older pages.

Crear el cuerpo del mensajeConstruct the message body

El código HTML que define el contenido de la página se denomina HTML de entrada.The HTML that defines page content is called input HTML. El código HTML de entrada admite un subconjunto de HTML y CSS estándar, además de atributos personalizados.Input HTML supports a subset of standard HTML and CSS, with the addition of custom attributes. (Los atributos personalizados, como data-id y data-render-src, se describen en HTML de entrada y salida).(Custom attributes, like data-id and data-render-src, are described in Input and output HTML.)

Envíe el código HTML de entrada en el cuerpo del mensaje de la solicitud POST.Send the input HTML in the message body of the POST request. Puede enviar el código HTML de entrada directamente en el cuerpo del mensaje con el tipo de contenido application/xhtml+xml o text/html, o bien puede enviarlo en el elemento “Presentación” de una solicitud de varias partes.You can send the input HTML directly in the message body using the application/xhtml+xml or text/html content type, or you can send it in the "Presentation" part of a multipart request.

En el ejemplo siguiente, se envía el código HTML de entrada directamente en el cuerpo del mensaje.The following example sends the input HTML directly in the message body.

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>

Si envía datos binarios, tendrá que usar una solicitud de varias partes.If you're sending binary data, you must use a multipart request.

Nota: Para simplificar la programación y la coherencia en la aplicación, puede usar solicitudes de varias partes para crear todas las páginas.Note: To simplify programming and consistency in your app, you can use multipart requests to create all pages. Le recomendamos que use una biblioteca para crear mensajes de varias partes.It's a good idea to use a library to construct multipart messages. Esto reduce el riesgo de crear cargas de trabajo con formato incorrecto.This reduces the risk of creating malformed payloads.

Requisitos y limitaciones para código HTML de entrada en solicitudes de páginas POSTRequirements and limitations for input HTML in POST pages requests

Al enviar código HTML de entrada, tenga en cuenta estos requisitos y limitaciones generales:When sending input HTML, be aware of these general requirements and limitations:

  • El código HTML de entrada necesita tener codificación UTF-8 y XHTML con un formato correcto.Input HTML should be UTF-8 encoded and well-formed XHTML. Todas las etiquetas de inicio del contenedor necesitan las etiquetas de cierre correspondientes.All container start tags require matching closing tags. Todos los valores de atributo tienen que delimitarse con comillas dobles o simples.All attribute values must be surrounded by double- or single-quote marks.

  • El código JavaScript se quita, incluidos los archivos y CSS.JavaScript code, included files, and CSS are removed.

  • Los formularios HTML se quitan por completo.HTML forms are removed in their entirety.

  • Microsoft Graph admite un subconjunto de elementos HTML.Microsoft Graph supports a subset of HTML elements.

  • Microsoft Graph admite un subconjunto de atributos HTML comunes y un conjunto de atributos personalizados, como el atributo data-id usado para actualizar páginas.Microsoft Graph supports a subset of common HTML attributes and a set of custom attributes, such as the data-id attribute used for updating pages. Para obtener información sobre los atributos admitidos, vea HTML de entrada y salida.For supported attributes, see Input and output HTML.

HTML y CSS admitido para páginas de OneNoteSupported HTML and CSS for OneNote pages

No se admiten todos los elementos, atributos y propiedades (en HTML4, XHTML, CSS, HTML5, etc.).Not all elements, attributes, and properties are supported (in HTML4, XHTML, CSS, HTML5, etc.). En su lugar, Microsoft Graph admite un conjunto limitado de HTML que se adapta mejor a la forma en que los usuarios usan OneNote.Instead, Microsoft Graph accepts a limited set of HTML that better fits how people use OneNote. Para obtener más información, vea Etiquetas HTML admitidas para páginas.For more information, see HTML tag support for pages. Si una etiqueta no se muestra aquí, lo más probable es que se omita.If a tag's not listed there, it'll probably be ignored.

En la lista siguiente, se muestran los tipos de elementos básicos admitidos por Microsoft Graph:The following list shows the basic element types that Microsoft Graph supports:

  • <head> y <body><head> and <body>

  • <title> y <meta> que establece el título de página y la fecha de creación<title> and <meta> that set the page title and creation date

  • <h1> a <h6> para los encabezados de sección<h1> through <h6> for section headings

  • <p> para párrafos<p> for paragraphs

  • <ul>, <ol> y <li> para listas y elementos de lista<ul>, <ol>, and <li> for lists and list items

  • <table>, <tr>y <td>, incluidas las tablas anidadas<table>, <tr> and <td>, including nested tables

  • <pre> para texto con formato previo (conserva el espacio en blanco y los saltos de línea)<pre> for preformatted text (preserves white space and line breaks)

  • <b> y <i> para estilos de carácter negrita y cursiva<b> and <i> for bold and italic character styles

Microsoft Graph conserva el contenido semántico y la estructura básica del código HTML de entrada al crear páginas, pero convierte el código HTML de entrada para usar el conjunto admitido de HTML y CSS.Microsoft Graph preserves the semantic content and basic structure of the input HTML when it creates pages, but it converts the input HTML to use the supported set of HTML and CSS. Las características que no existen en OneNote no pueden traducirse a nada, por lo que es posible que no se reconozcan en el código HTML de origen.Features that don't exist in OneNote have nothing to be translated to, so they might not be recognized in the source HTML.

Ejemplo de solicitudExample request

En esta solicitud de varias partes de ejemplo, se crea una página que contiene imágenes y un archivo incrustado.This example multipart request creates a page that contains images and an embedded file. El elemento Presentation necesario contiene el código HTML de entrada que define la página.The required Presentation part contains the input HTML that defines the page. El elemento imageBlock1 contiene los datos de imágenes binarias y fileBlock1 contiene los datos de archivos binarios.The imageBlock1 part contains the binary image data, and fileBlock1 contains the binary file data. Los elementos de datos también pueden contener HTML; en ese caso, Microsoft Graph representa el código HTML como una imagen en la página de OneNote.Data parts can also contain HTML, in which case Microsoft Graph renders the HTML as an image on the OneNote page.

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 obtener más ejemplos donde se muestra cómo crear páginas que contienen imágenes y otros archivos, vea Agregar imágenes y archivos, tutoriales y ejemplos.For more examples that show how to create pages that contain images and other files, see Add images and files, our tutorials, and our samples. Además, obtenga información sobre cómo crear elementos con posición absoluta, usar etiquetas de nota y extraer datos de capturas de tarjetas de presentación y listas de productos y recetas en línea.Also, learn how to create absolute positioned elements, use note tags, and extract data for business card captures and online recipe and product listings.

Microsoft Graph es estricto en relación con algunos formatos, como nuevas líneas CRLF en el cuerpo de un mensaje de varias partes.Microsoft Graph is strict about some formats, such as CRLF newlines in a multipart message body. Para reducir el riesgo de crear cargas de trabajo con formato incorrecto, necesita usar una biblioteca para crear mensajes de varias partes.To reduce the risk of creating malformed payloads, you should use a library to construct multipart messages.

Si recibe un código de estado 400 para una carga con formato incorrecto, compruebe el formato de las nuevas líneas y los espacios en blanco, y asegúrese de que no haya problemas de codificación.If you do receive a 400 status for a malformed payload, check the formatting of newlines and whitespaces, and check for encoding issues. Por ejemplo, pruebe a usar charset=utf-8 (ejemplo: Content-Type: text/html; charset=utf-8).For example, try using charset=utf-8 (example: Content-Type: text/html; charset=utf-8).

Vea Requisitos y limitaciones de HTML de entrada y Límites de tamaño de solicitudes POST.See requirements and limitations for input HTML and size limits for POST requests.

Información de solicitudes y respuestas para solicitudes de páginas POSTRequest and response information for POST pages requests

Solicitar datosRequest data DescripciónDescription
ProtocoloProtocol Todas las solicitudes usan el protocolo HTTPS SSL/TLS.All requests use the SSL/TLS HTTPS protocol.
Encabezado AuthorizationAuthorization header

Bearer {token}, donde {token} es un token de acceso de OAuth 2.0 válido para la aplicación registrada.Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

Si falta o no es válido, la solicitud producirá errores con el código de estado 401.If missing or invalid, the request fails with a 401 status code. Vea Authentication and permissions (Autenticación y permisos).See Authentication and permissions.

Encabezado Content-TypeContent-Type header

text/html o application/xhtml+xml para el contenido HTML, sin importar si se envía directamente en el cuerpo del mensaje o en el elemento “Presentación” necesario de las solicitudes de varias partes.text/html or application/xhtml+xml for the HTML content, whether it's sent directly in the message body or in the required "Presentation" part of multipart requests.

Las solicitudes de varias partes son necesarias al enviar datos binarios y usar el tipo de contenido multipart/form-data; boundary=part-boundary, donde {part-boundary} es una cadena que señala el principio y el final de cada elemento de datos.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.

Encabezado AcceptAccept header application/json

Datos de respuestaResponse data DescripciónDescription
Código de correctoSuccess code Código de estado HTTP 201.A 201 HTTP status code.
Cuerpo de la respuestaResponse body Una representación de OData de la nueva página en formato JSON.A OData representation of the new page in JSON format.
ErroresErrors Si la solicitud no se completa correctamente, la API mostrará los errores del objeto **@api.diagnostics** en el cuerpo de la respuesta.If the request fails, the API returns errors in the **@api.diagnostics** object in the response body.
Encabezado de ubicaciónLocation header La URL de recursos de la nueva página.The resource URL for the new page.
Encabezado X-CorrelationIdX-CorrelationId header GUID que identifica la solicitud de forma única.A GUID that uniquely identifies the request. Puede usar este valor, además del valor del encabezado de fecha, al trabajar con el soporte técnico de Microsoft para solucionar problemas.You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Crear la URL raíz del servicio de Microsoft GraphConstructing the Microsoft Graph service root URL

La URL raíz del servicio de Microsoft Graph usa el formato siguiente para todas las llamadas que se realicen a Microsoft Graph:The Microsoft Graph service root URL uses the following format for all calls to Microsoft Graph:

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

El segmento version de la URL representa la versión de Microsoft Graph que se quiere utilizar.The version segment in the URL represents the version of Microsoft Graph that you want to use. Use v1.0 para código de producción estable.Use v1.0 for stable production code. Use beta para probar una característica que esté en desarrollo.Use beta to try out a feature that's in development. Las características y la funcionalidad de la versión beta pueden cambiar, por lo que no se debe usar en el código de producción.Features and functionality in beta may change, so you shouldn't use it in your production code.

Use me para contenido de OneNote al que puede obtener acceso el usuario actual (contenido compartido y del que sea propietario).Use me for OneNote content that the current user can access (owned and shared). Use users/{id} para contenido de OneNote que el usuario especificado (en la URL) compartió con el usuario actual.Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. Use Microsoft Graph para obtener identificadores de usuario.Use Microsoft Graph to get user IDs.

PermisosPermissions

Para crear páginas de OneNote, necesitará solicitar los permisos adecuados.To create OneNote pages, you'll need to request appropriate permissions. Seleccione el nivel inferior de permisos que necesita la aplicación para funcionar correctamente.Choose the lowest level of permissions that your app needs to do its work.

Seleccione entre:Choose from:

  • Notes.CreateNotes.Create
  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

Para obtener más información sobre los ámbitos de permiso y cómo funcionan, vea Referencias de permisos de Microsoft Graph.For more information about permission scopes and how they work, see Microsoft Graph permissions reference.

Vea tambiénSee also