Crear páginas de OneNote
Se aplica a: Blocs de notas para consumidores de OneDrive | Blocs de notas empresariales de Microsoft 365
Para crear una página de OneNote, envíe una solicitud POST al punto de conexión pages. Por ejemplo:
POST ../notes/sections/{id}/pages
Envíe el código HTML que define la página en el cuerpo del mensaje. Si la solicitud se completa correctamente, Microsoft Graph devuelve un código de estado HTTP 201.
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.
Crear el URI de la solicitud
Para crear el URI de la solicitud POST, empiece con la dirección URL raíz del servicio:
https://graph.microsoft.com/v1.0/me/onenote
Después, anexe el punto de conexión pages:
Crear una página en cualquier sección (especificado por el nombre de sección)
.../pages?sectionName=DefaultSectionCrear una página en cualquier sección (especificado por el 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:
Crear una página de OneNote en la sección predeterminada del bloc de notas predeterminado
../pages
La URI de la solicitud completa tendrá un aspecto similar a uno de estos ejemplos:
https://graph.microsoft.com/v1.0/me/onenote/sections/{id}/pageshttps://graph.microsoft.com/v1.0/me/onenote/pages?sectionName=Homework
Obtenga más información sobre la URL de raíz del servicio.
Usar el parámetro de URL sectionName
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:
Solo se puede hacer referencia a las secciones de nivel superior (no a las secciones dentro de grupos de secciones).
Si en el bloc de notas predeterminado no existe una sección con el nombre especificado, la API la creará. Los caracteres siguientes no pueden usarse en los nombres de sección:
? * \ / : < > | & # " % ~Los nombres de sección no distinguen mayúsculas de minúsculas, pero el uso de mayúsculas se conserva al crear las secciones. Por lo tanto, “Mi nueva sección” se mostrará de esa forma, pero “mi nueva sección” también coincidirá en las publicaciones posteriores.
Los nombres de sección necesitan tener el formato de codificación URL. Por ejemplo, los espacios tienen que codificarse como %20.
El parámetro sectionName solo es válido con la ruta
../notes/pages(pero no con../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. Aunque los usuarios pueden cambiar el nombre de las secciones, la API creará una sección con el nombre de sección que especifique.
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.
Crear el cuerpo del mensaje
El código HTML que define el contenido de la página se denomina HTML de entrada. El código HTML de entrada admite un subconjunto de HTML y CSS estándar, además de atributos personalizados. (Los atributos personalizados, como data-id y data-render-src, se describen en HTML de entrada y salida).
Envíe el código HTML de entrada en el cuerpo del mensaje de la solicitud POST. Puede enviar el HTML de entrada directamente en el cuerpo del mensaje mediante el application/xhtml+xml tipo de contenido o text/html , o bien puede enviarlo en la parte "Presentación" de una solicitud de varias partes.
En el ejemplo siguiente, se envía el código HTML de entrada directamente en el cuerpo del mensaje.
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.
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. Le recomendamos que use una biblioteca para crear mensajes de varias partes. Esto reduce el riesgo de crear cargas de trabajo con formato incorrecto.
Requisitos y limitaciones para código HTML de entrada en solicitudes de páginas POST
Al enviar código HTML de entrada, tenga en cuenta estos requisitos y limitaciones generales:
El código HTML de entrada necesita tener codificación UTF-8 y XHTML con un formato correcto. Todas las etiquetas de inicio del contenedor necesitan las etiquetas de cierre correspondientes. Todos los valores de atributo tienen que delimitarse con comillas dobles o simples.
El código JavaScript se quita, incluidos los archivos y CSS.
Los formularios HTML se quitan por completo.
Microsoft Graph admite un subconjunto de elementos HTML.
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. Para obtener información sobre los atributos admitidos, vea HTML de entrada y salida.
HTML y CSS admitido para páginas de OneNote
No se admiten todos los elementos, atributos y propiedades (en 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. Para obtener más información, vea Etiquetas HTML admitidas para páginas. Si una etiqueta no se muestra aquí, lo más probable es que se omita.
En la lista siguiente, se muestran los tipos de elementos básicos admitidos por Microsoft Graph:
-
<head>y<body> -
<title>y<meta>que establece el título de página y la fecha de creación -
<h1>a<h6>para los encabezados de sección -
<p>para párrafos -
<ul>,<ol>y<li>para listas y elementos de lista -
<table>,<tr>y<td>, incluidas las tablas anidadas -
<pre>para texto con formato previo (conserva el espacio en blanco y los saltos de línea) -
<b>y<i>para estilos de carácter negrita y cursiva
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. 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.
Ejemplo de solicitud
En esta solicitud de varias partes de ejemplo, se crea una página que contiene imágenes y un archivo incrustado. El elemento Presentation necesario contiene el código HTML de entrada que define la página. El elemento imageBlock1 contiene los datos de imágenes binarias y fileBlock1 contiene los datos de archivos binarios. 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.
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. 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.
Microsoft Graph es estricto en relación con algunos formatos, como nuevas líneas CRLF en el cuerpo de un mensaje de varias partes. Para reducir el riesgo de crear cargas de trabajo con formato incorrecto, necesita usar una biblioteca para crear mensajes de varias partes.
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. Por ejemplo, pruebe a usar charset=utf-8 (ejemplo: Content-Type: text/html; charset=utf-8).
Vea Requisitos y limitaciones de HTML de entrada y Límites de tamaño de solicitudes POST.
Información de solicitudes y respuestas para solicitudes de páginas POST
| Solicitar datos | Descripción |
|---|---|
| Protocolo | Todas las solicitudes usan el protocolo HTTPS SSL/TLS. |
| Encabezado Authorization |
Si falta o no es válido, la solicitud producirá errores con el código de estado 401. Vea Authentication and permissions (Autenticación y permisos). |
| Encabezado Content-Type |
Las solicitudes de varias partes son necesarias al enviar datos binarios y usar el tipo de contenido |
| Encabezado Accept | application/json |
| Datos de respuesta | Descripción |
|---|---|
| Código de correcto | Código de estado HTTP 201. |
| Cuerpo de la respuesta | Una representación de OData de la nueva página en formato JSON. |
| Errores | Si la solicitud no se completa correctamente, la API mostrará los errores del objeto @api.diagnostics en el cuerpo de la respuesta. |
| Encabezado de ubicación | La URL de recursos de la nueva página. |
| Encabezado X-CorrelationId | GUID que identifica la solicitud de forma única. Puede usar este valor, además del valor del encabezado de fecha, al trabajar con el soporte técnico de Microsoft para solucionar problemas. |
Crear la URL raíz del servicio de Microsoft Graph
La URL raíz del servicio de Microsoft Graph usa el formato siguiente para todas las llamadas que se realicen a 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. Use v1.0 para código de producción estable. Use beta para probar una característica que esté en desarrollo. 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.
Use me para contenido de OneNote al que puede obtener acceso el usuario actual (contenido compartido y del que sea propietario). Use users/{id} para contenido de OneNote que el usuario especificado (en la URL) compartió con el usuario actual. Use Microsoft Graph para obtener identificadores de usuario.
Limitaciones de tamaño de la sección de OneNote
Hay un límite en el número de páginas que puede agregar a una sección con la API de OneNote. Si alcanza este límite para una sección e intenta crear una nueva página en ella, verá una respuesta con el código de estado HTTP 507 y el mensaje "superó el número máximo de páginas permitido por sección". Para obtener más información sobre este código de error, consulte Códigos de error de OneNote.
Puede usar una de las siguientes soluciones:
- Crear una nueva sección y agregar nuevas páginas.
- Eliminar las páginas no utilizadas cuando una sección alcance el límite de páginas.
Permissions
Para crear páginas de OneNote, necesitará solicitar los permisos adecuados. Seleccione el nivel inferior de permisos que necesita la aplicación para funcionar correctamente.
Seleccione entre:
- Notes.Create
- Notes.ReadWrite
- Notes.ReadWrite.All
Para obtener más información sobre los ámbitos de permiso y cómo funcionan, vea Referencias de permisos de Microsoft Graph.