Table of contents
TOC
Collapse the table of content
Expand the table of content
Última actualización: 25/07/2018

Actualizar el contenido de la página de OneNote

Se aplica a: blocs de notas para consumidores de OneDrive | blocs de notas para empresa de Office 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 tiene éxito, la API de OneNote devuelve un código de estado de 204 HTTP.

Crear el URI de la solicitud

Para crear el URI de la solicitud, comience con la dirección URL raíz del servicio:

Blocs de notas en OneDrive
https://www.onenote.com/api/v1.0/me/notes/

Blocs de notas en OneDrive para la Empresa
https://www.onenote.com/api/v1.0/me/notes/
https://www.onenote.com/api/v1.0/users/{id}/notes/

Blocs de notas del sitio de SharePoint
https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

Blocs de notas de grupos unificados
https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/


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 URI completo de su solicitud tendrá el aspecto de uno de estos ejemplos:

https://www.onenote.com/api/v1.0/me/notes/pages/{id}/content

https://www.onenote.com/api/v1.0/myorganization/sitecollections/{id}/sites/{id}/notes/pages/{id}/content

https://www.onenote.com/api/v1.0/myorganization/groups/{id}/notes/pages/{id}/content

Obtenga más información sobre service root URL.

Crear el 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.

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-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.

destino
Elemento que se va a actualizar. El valor debe ser uno de los siguientes identificadores:

IdentificadorDescripció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

Este es el ID generado desde la API de OneNote, y se requiere 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.

cuerpoPalabra clave que tiene como destino el primer div en la página. No use # como prefijo.
títuloPalabra clave que tiene como destino el título de página. No use # como prefijo.

acción
La acción a realizar en el elemento de destino. Consulte acciones admitidas para elementos.

AcciónDescripción
anexar

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.

insertAgrega 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.
anteponer

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).

posición
La ubicación donde agregar el contenido provisto, relativa al elemento de destino. Queda predeterminado como after si se omite.

PosiciónDescripción
after (valor predeterminado)

-Con append: último elemento secundario del elemento de destino.

- Con insert: siguiente elemento del mismo nivel del elemento de destino.

antes

-Con append: primer elemento secundario del elemento de destino.

- Con insert: anterior elemento del mismo nivel del elemento de destino.

contenido
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).

IDs generados

La API de OneNote genera valores idpara los elementos en la página que se pueden actualizar. 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 id definidos en el HTML de entrada de las solicitudes crear-página y actualizar-página.

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.

ElementoReemplazarAnexar elemento secundarioInsertar elemento del mismo nivel
cuerpo
(tiene como destino el primer div en la página)
nono
div
(posición absoluta)
nono
div
(en un elemento div)
(solo identificador)
img, object
(en un elemento div)
no
ol, ul (solo identificador)
tabla (solo identificador)no
p, li, h1-h6 (solo identificador)no
títulonono

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  |  Insertar elementos del mismo nivel  |  Reemplazar elementos  |  Completar solicitudes PATCH

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 *cuerpo*

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

La acción insert agrega un elemento relacionado al elemento de destino. El atributo position determina si el elemento relacionado se insertará antes o después del elemento de destino. La posición predeterminada es after. Consulte elementos que admiten insertar.****

[
  {
    '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

Puede usar tanto el data-id o el id generado como valor de destino para reemplazar elementosimg y object que se encuentran dentro de un div. Para reemplazar el título de una página, use la palabra clave title. Para todos los demás elementos que admiten reemplazo, debe usar el Id. generado.********

[
  {
     'target':'#para1',
     'action':'insert',
     'position':'before',
     'content':'<img src="image-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

Este ejemplo muestra cómo cambiar el título de una página. Para cambiar el título, use la palabra clave title como el valor del elemento de destino. No use # con el elemento de destino title.********

[
  {
    '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':'#task1',
    '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://www.onenote.com/api/v1.0/me/notes/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#para-id',
    'action':'insert',
    'position':'before',
    'content':'<img src="image-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://www.onenote.com/api/v1.0/me/notes/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 solicitudDescripción
ProtocoloTodas 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 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.

Se necesitan solicitudes de varias partes cuando se envían datos binarios y se utiliza el tipo de contenido multipart/form-data; boundary=part-boundary, donde {part-boundary} es una cadena que señala el inicio y el final de cada parte de datos.

Datos de respuestaDescripción
ErroresSi la solicitud de actualización falla, la API devuelve errores en el objeto api.diagnostics en el cuerpo de la respuesta. La solicitud fallará si:
ErroresSi se produce un error en la solicitud, la API devuelve errores en el objeto @api.diagnostics en el cuerpo de la respuesta. La solicitud fallará si:
- El objeto JSON contiene atributos no válidos o está mal formado.
Faltan los atributos deldestino, de la acción, o delcontenido.
El elemento de destino no admite una acción especificada.
- El formato del valor de destino no es válido. Ejemplo, un data-id no está prefijado con un #.
El elemento de destino no es compatible con la acción especificada.
- El valor de la acción o de la posición no es válido.
Encabezado X-CorrelationIdGUID 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 OneNote

La dirección URL raíz del servicio de OneNote utiliza el siguiente formato para todas las llamadas a la API de OneNote.

https://www.onenote.com/api/{version}/{location}/notes/


El segmento version de la URL representa la versión de la API de OneNote que desea utilizar.

  • Utilice v1.0 para un código de producción estable.
  • Use beta para probar una característica que esté en desarrollo. Las características y funciones pueden cambiar en la versión beta, por lo que le recomendamos que no la use en su código de producción.


El segmento location de la URL representa la ubicación de los blocs de notas a los que desea acceder.

Blocs de notas en OneDrive (consumidor)
Utilice me para el contenido de OneNote al que puede acceder el usuario actual (contenido compartido y del que sea propietario).

Blocs de notas en OneDrive para la Empresa
Use me para el contenido de OneNote que sea propiedad del usuario actual.

Utilice users/{id} para el contenido de OneNote que el usuario especificado (en la URL) haya compartido con el usuario actual. Use la API de Azure AD Graph para obtener id. de usuario.

Blocs de notas del sitio de SharePoint
Los sitios de grupo y otros sitios de SharePoint pueden contener blocs de notas de OneNote en sus bibliotecas de documentos.

Utilice myOrganization/siteCollections/{id}/sites/{id} para el contenido de OneNote en un sitio de la cuenta empresarial en la que el usuario actual haya iniciado sesión. Solo se admite la cuenta empresarial actual, a la que se accede empleando la palabra clave myOrganization. Descubra cómo obtener id. de sitio.

Blocs de notas de grupo de Office 365
Los grupos de Office 365 son parte de la experiencia conectada de Office 365. Los miembros del grupo pueden compartir blocs de notas, archivos y correos electrónicos.

Utilice myOrganization/groups/{id} para el contenido de OneNote en el grupo especificado del que el usuario actual sea miembro. Los grupos de Office 365 (que devuelven el unified groupType) son el único tipo de grupo admitido. Use la API de Azure AD Graph para obtener id. de usuario.


Utilizar el método FromUrl para obtener la colección y los id. de sitios

Puede usar el método FromUrl para obtener la colección y los id. de sitios para una URL de sitio absoluta y específica. Debe realizar esta llamada solo cuando sea necesario y luego guardar los valores para usarlos en el futuro.

El formato de la URL de sitio depende de su configuración, por ejemplo https://domain.sharepoint.com/site-a o https://domain.com/sites/site-a.

Ejemplo de solicitud:

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')
Authorization: Bearer {token}
Accept: application/json

Ejemplo de respuesta:

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata",
  "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5",
  "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"
}

Requisitos para usar FromUrl y trabajar con blocs de notas del sitio de SharePoint:

  • Solo puede crear blocs de notas de OneNote, grupos de secciones, secciones y páginas en sitios que tengan una biblioteca de documentos predeterminada. (Algunas plantillas de sitio no crean una biblioteca de documentos predeterminada). Sin embargo, las solicitudes GET devuelven contenido de OneNote de todas las bibliotecas de documentos del sitio.
  • La URL raíz del servicio de OneNote es inmutable, lo que significa que no puede usar una ruta de sitio de la API de REST de SharePoint y luego añadirle el punto de conexión notes.
  • El usuario en cuyo nombre está realizando la llamada debe ser miembro del sitio.
  • FromUrl funciona solo con sitios que hayan sido indexados. Puede llevar varias horas indexar un nuevo sitio.

Permisos

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.

PlataformaÁmbito de permisos
Consumidoroffice.onenote_update_by_app, office.onenote_update
EmpresaNotes.ReadWrite.CreatedByApp, 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.

Recursos adicionales

© 2018 Microsoft