Actualizar el contenido de la página de OneNote

  • Artículo

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:
'target':'#intro' tiene como destino el elemento <div data-id="intro" ...>
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:
'target':'div:{33f8a2...}{37}' tiene como destino el elemento <div id="div:{33f8a2...}{37}" ...>

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.

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

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

Bearer {token}, donde {token} es un token de acceso de OAuth 2.0 válido para la aplicación registrada.

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

application/json para la matriz de objetos de cambio JSON, tanto si se envía directamente en el cuerpo del mensaje como si se envía en la parte "Comandos" necesaria de las solicitudes de varias partes.

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.

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.

Contenido relacionado