Actualizar el contenido de la página de OneNote
Se aplica a: Blocs de notas para consumidores de OneDrive | Blocs de notas empresariales de Microsoft 365
Para actualizar el contenido de una página de OneNote, envíe una solicitud PATCH al punto de conexión content de la página.
PATCH ../notes/pages/{id}/content
Envíe un objeto de cambio JSON en el cuerpo del mensaje. Si la solicitud se completa correctamente, Microsoft Graph devuelve un código de estado HTTP 204.
Crear el URI de la solicitud
Para crear el URI de la solicitud, comience con la dirección URL raíz del servicio:
https://graph.microsoft.com/v1.0/me/onenote
Luego anexe el punto de conexión content de la página:
Obtenga el HTML de página y todos los valores de data-id definidos.
../pages/{id}/content
Obtenga el HTML de página y todos los valores de data-id definidos y todos los valores de id generados.
../pages/{page-id}/content?includeIDs=true
Los valores de data-id y de id se usan como identificadores target de los elementos que se quieren actualizar.
El identificador URI de solicitud completo tendrá un aspecto similar al siguiente:https://graph.microsoft.com/v1.0/me/onenote/pages/{id}/content
Obtenga más información sobre la dirección URL raíz del servicio.
Crear al cuerpo del mensaje
El código HTML de una página de OneNote contiene texto, imágenes y otro contenido organizado en estructuras tales como div, img y ol elementos. Para actualizar el contenido de la página de OneNote, puede agregar y reemplazar elementos HTML en la página.
Los cambios se envían en el cuerpo del mensaje como matriz de objetos de cambio JSON. Cada objeto especifica el nuevo contenido HTML del elemento de destino y qué hacer con el contenido.
La siguiente matriz define dos cambios. El primero inserta una imagen arriba del párrafo como un elemento relacionado, el segundo anexa un elemento a la lista como un último elemento secundario.
Nota:
Al actualizar una imagen en una página de OneNote, no se pueden usar vínculos www. El servicio no intentará descargar recursos aleatorios. En su lugar, la imagen debe formar parte de la solicitud, ya sea mediante una dirección URL de datos de imagen o un nombre de parte de una solicitud de varias partes.
[
{
'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>'
}
]
Vea más ejemplos.
Atributos para los objetos de cambio JSON
Use los atributos target, action, position y content para definir objetos JSON para solicitudes PATCH.
target
El elemento para actualizar. El valor debe ser uno de los siguientes identificadores:
Identificador | Descripción |
---|---|
#{data-id} | Este identificador se define opcionalmente en los elementos del HTML de entrada al crear una página o actualizar una página. Use # como prefijo. Ejemplo: |
id | Se trata del identificador generado en Microsoft Graph, y es necesario para la mayoría de las operaciones de reemplazo. No use # como prefijo. Ejemplo: No debe confundirse con los valores de id definidos en el HTML de entrada. Todos los valores de id enviados en el HTML de entrada se descartan. |
body | Palabra clave que tiene como destino el primer div en la página. No use # como prefijo. |
title | Palabra clave que tiene como destino el título de página. No use # como prefijo. |
action
La acción a realizar en el elemento de destino. Consulte acciones admitidas para elementos.
Acción | Descripción |
---|---|
append | Agrega el contenido especificado al destino como primer o último elemento secundario, tal y como se determina en el atributo position. Solo se aplica a los elementos body, div, ol y ul. |
insert | Agrega el contenido especificado como elemento del mismo nivel antes o después del elemento de destino, tal y como se determina en el atributo position. |
prepend | Agrega el contenido especificado al destino como primer elemento secundario. Acceso directo a append + before. Solo se aplica a los elementos body, div, ol y ul. |
replace | Reemplaza el destino por el contenido especificado. La mayoría de las acciones replace requieren el uso del identificador generado para el elemento de destino (excepto img y object dentro de un div, que también admiten el uso de data-id). |
position
La ubicación donde agregar el contenido provisto, relativa al elemento de destino. Queda predeterminado como after si se omite.
Posición | Descripción |
---|---|
after (valor predeterminado) | Con append: último elemento secundario del elemento de destino. Con insert: siguiente elemento del mismo nivel del elemento de destino. |
before | Con append: primer elemento secundario del elemento de destino. Con insert: anterior elemento del mismo nivel del elemento de destino. |
content
Cadena de HTML sintácticamente correcta que se agrega a la página y datos binarios de cualquier imagen o archivo. Si el contenido contiene datos binarios, la solicitud debe enviarse utilizando el tipo de contenido multipart/form-data
con una parte "Comandos" (véase un ejemplo).
Identificadores generados
Microsoft Graph genera valores de id para los elementos de la página que pueden actualizarse. Para obtener el identificador generado, use la expresión de cadena de consulta includeIDs=true
en la solicitud GET:
GET ../notes/pages/{page-id}/content?includeIDs=true
Nota:
La API descarta todos los valores de identificador definidos en el HTML de entrada de las solicitudes create-page y update-page.
En el siguiente ejemplo se muestran los identificadores generados para un párrafo y una imagen en el HTML de salida de una 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}" ... />
Los valores de id generados pueden cambiar después de la actualización de una página, por lo tanto debe obtener los valores actuales antes de crear una solicitud de PATCH que los utilice.
Puede especificar los elementos de destino con el valor de data-id o de id, de la manera siguiente:
- Para las acciones append y insert, puede usar cualquier identificador como valor de destino.
- Para las acciones replace, debe usar el identificador generado para todos los elementos excepto el título de página y las imágenes y los objetos que se encuentran dentro de un div.
- Para reemplazar un título, utilice la palabra clave title.
- Para reemplazar imágenes y objetos que se encuentran en un div, utilice data-id o id.
En el siguiente ejemplo se usa el valor de id como destino. No use el prefijo # con un identificador generado.
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'insert',
'position':'before',
'content':'<p>This paragraph goes above the target paragraph.</p>'
}
]
Acciones y elementos admitidos
Se pueden actualizar muchos elementos de la página, pero cada tipo de elemento admite acciones específicas. En la siguiente tabla se muestran los elementos de destino admitidos y las acciones de actualización que admiten.
Elemento | Reemplazar | Anexar elemento secundario | Insertar elemento del mismo nivel |
---|---|---|---|
body (tiene como destino el primer div en la página) |
no | sí | no |
div (posición absoluta) |
no | sí | no |
div (en un elemento div) |
sí (solo identificador) |
sí | sí |
img, object (en un elemento div) |
sí | no | sí |
ol, ul |
sí (solo identificador) |
sí | sí |
table |
sí (solo identificador) |
no | sí |
p, li, h1-h6 |
sí (solo identificador) |
no | sí |
title | sí | no | no |
Los siguientes elementos no admiten ninguna acción de actualización.
- img (posición absoluta)
- object (posición absoluta)
- tr, td
- meta
- head
- span
- a
- etiquetas de estilo
Solicitudes de ejemplo
Una solicitud de actualización contiene uno o más cambios que se representan como objetos de cambio JSON. Estos objetos pueden definir diferentes destinos en la página y diferentes acciones y contenido para los destinos.
En los siguientes ejemplos se incluyen objetos JSON usados en solicitudes PATCH y solicitudes PATCH completas:
- Anexar elementos secundarios
- Insertar elementos del mismo nivel
- Reemplazar elementos
- Solicitud PATCH completa
Anexar elementos secundarios
La acción append agrega un elemento secundario a un elemento body, div (dentro de un div), ol o ul. El atributo position determina si el elemento secundario se va a anexar antes o después del destino. La posición predeterminada es after.
Anexar a un div
En el ejemplo siguiente se agregan dos nodos secundarios al elemento div1. Agrega una imagen como primer elemento secundario y un párrafo como último elemento secundario.
[
{
'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>'
}
]
Anexar al elemento body
Puede usar el acceso directo body para anexar un elemento secundario en el interior del primer div de cualquier página.
En el siguiente ejemplo se agregan dos párrafos como primer elemento secundario y último elemento secundario en el primer div de la página. No use # con el destino body. En este ejemplo se usa la acción prepend como acceso directo a 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>'
}
]
Anexar a una lista
En el ejemplo siguiente se agrega un elemento de lista como último elemento secundario a la lista de destino. La propiedad list-style-type se define porque el elemento usa un estilo de lista no predeterminado.
[
{
'target':'#circle-ul',
'action':'append',
'content':'<li style="list-style-type:circle">Item at the end of the list</li>'
}
]
Insertar elementos del mismo nivel
La acción insert agrega un elemento del mismo nivel al elemento de destino. El atributo position determina si el elemento del mismo nivel se va a insertar antes o después del destino. La posición predeterminada es after. Vea elementos que admiten insert.
Insertar elementos del mismo nivel
En el ejemplo siguiente se agregan dos nodos del mismo nivel a la página. Agrega una imagen encima del elemento para1 y un párrafo debajo del 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>'
}
]
Reemplazar elementos
Puede utilizar el data-id o el id generado como valor de destino para reemplazar los elementos img y object que están dentro de un div. Para reemplazar el título de página, utilice la palabra clave title. Para todos los demás elementos que admiten replace, debe usar el identificador generado.
Reemplazar una imagen
En este ejemplo se reemplaza una imagen por un div mediante el data-id de la imagen como destino
[
{
'target':'#img1',
'action':'replace',
'content':'<div data-id="new-div"><p>This div replaces the image</p></div>'
}
]
Actualizar una tabla
En este ejemplo se muestra cómo actualizar una tabla mediante su identificador generado. No se admite la sustitución de elementos tr y td , pero puede reemplazar toda la tabla.
[
{
'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>'
}
]
Cambiar el título
En este ejemplo se muestra cómo cambiar el título de la página. Para cambiar el título, use la palabra clave title como valor de destino. No use el prefijo # con el destino title.
[
{
'target':'title',
'action':'replace',
'content':'New title'
}
]
Actualizar una tarea pendiente
En el siguiente ejemplo se usa la acción replace para cambiar un elemento de casilla de tarea pendiente a un estado completado.
[
{
'target':'p:{33f8a242-7c33-4bb2-90c5-8425a68cc5bf}{40}',
'action':'replace',
'content':'<p data-tag="to-do:completed" data-id="task1">First task</p>'
}
]
Vea Uso de etiquetas de nota para más información sobre el uso del atributo data-tag.
Ejemplos de solicitud PATCH completa
En los ejemplos siguientes se muestran solicitudes PATCH completas.
Solicitud con solo contenido de texto
En el siguiente ejemplo se muestra una solicitud PATCH que utiliza el tipo de contenido application/json. Puede usar este formato cuando el contenido no contiene datos binarios.
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>'
}
]
Solicitud de varias partes con contenido binario
En el ejemplo siguiente se muestra una solicitud PATCH de varias partes que incluye datos binarios. Las solicitudes de varias partes requieren una parte "Comandos" que especifica el tipo de contenido application/json y contiene la matriz de objetos de cambio JSON. Otras partes de datos pueden contener datos binarios. Los nombres de parte suelen ser cadenas anexadas con la hora actual en milisegundos o un GUID aleatorio.
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--
Información de solicitud y respuesta de las solicitudes PATCH
Datos de solicitud | 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 |
Datos de respuesta | Descripción |
---|---|
Errores | Un código de estado HTTP 204. La solicitud fallará si: |
Errores | Lea Códigos de error para API de OneNote de Microsoft Graph para obtener información sobre los errores de OneNote que puede devolver Microsoft Graph. |
Crear la URL raíz del servicio de Microsoft Graph
La dirección URL raíz del servicio OneNote utiliza el siguiente formato para todas las llamadas a la API de OneNote:
https://graph.microsoft.com/{version}/me/onenote/
El segmento version
de la URL representa la versión de Microsoft Graph que se quiere utilizar.
v1.0
corresponde al código de producción estable.
beta
corresponde a la prueba de una característica que se encuentra 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.
me
corresponde a contenido de OneNote al que el usuario actual tiene acceso (de su propiedad y compartido).
users/{id}
corresponde a contenido de OneNote que el usuario especificado (en la dirección URL) ha compartido con el usuario actual. Use la API de losusuarios.
Nota:
Para obtener los identificadores de usuario, realice una solicitud GET en https://graph.microsoft.com/v1.0/users
.
Permissions
Para actualizar páginas OneNote, tiene que solicitar los permisos adecuados. Elija el nivel más bajo de permisos que necesita la aplicación para hacer su trabajo.
- Notes.ReadWrite
- Notes.ReadWrite.All
Para obtener más información sobre los ámbitos de permiso y cómo funcionan, consulte los ámbitos de permisos de OneNote.