Procedimientos recomendados para trabajar con las API de OneNote en Microsoft Graph.

En este artículo se proporcionan recomendaciones para trabajar con las API de OneNote en Microsoft Graph. Estas recomendaciones se basan en respuestas a preguntas comunes sobre Microsoft Q&A.

Use $select para seleccionar el conjunto mínimo de propiedades que necesita.

Cuando consulta un recurso (por ejemplo, las secciones dentro de un bloc de notas), realiza una solicitud similar a la siguiente.

GET ~/notebooks/{id}/sections

Esta solicitud recupera todas las propiedades de las secciones. Pero puede que no necesite todas las propiedades. Puede usar el parámetro de consulta $select para que devuelva solo las propiedades que quiera, como se muestra en el siguiente ejemplo de consulta.

GET ~/notebooks/{id}/sections?$select=id,displayName

El mismo enfoque se aplica a otras API de OneNote.

Use $expand en lugar de realizar varias llamadas a la API.

Supongamos que quiere recuperar todos los grupos de sección, secciones y blocs de notas del usuario en una vista jerárquica. Pueden conseguirlo mediante el procedimiento siguiente:

• Llame a GET ~/notebooks para obtener la lista de blocs de notas.

• Para todos los blocs de notas recuperados, llame a GET ~/notebooks/{notebookId}/sections para recuperar la lista de secciones.

• Para todos los blocs de notas recuperados, llame a GET ~/notebooks/{notebookId}/sectionGroups para recuperar la lista de grupos de secciones.

• Opcionalmente, itere recursivamente por los grupos de sección.

Este enfoque funcionará (con algunos recorridos de ida y vuelta secuenciales adicionales al servicio); sin embargo, un mejor enfoque es usar el parámetro de $expand consulta.

GET ~/notebooks?$expand=sections,sectionGroups($expand=sections)

Este enfoque produce los mismos resultados en un recorrido de ida y vuelta de red, con un mejor rendimiento.

Cuando quiera obtener todas las páginas de un usuario, hágalo para cada sección por separado

Microsoft Graph expone un punto de conexión para recuperar todas las páginas; sin embargo, no se recomienda usar este punto de conexión para obtener todas las páginas a las que el usuario tiene acceso. Cuando el usuario tiene demasiadas secciones y se intenta obtener todas las páginas, la llamada da como resultado un código 400 de estado HTTP y el siguiente mensaje: "Se supera el número máximo de secciones para esta solicitud. Para obtener páginas para cuentas con un gran número de secciones, se recomienda obtener páginas para una sección a la vez". Para obtener más información sobre este código de error, vea Códigos de error de OneNote.

Para obtener todas las páginas a las que un usuario tiene acceso, el procedimiento recomendado es realizar llamadas independientes para obtener las páginas de cada sección.

Por ejemplo, en lugar de usar esta llamada (se pagina esta API, por lo que no podrá recuperar todas las páginas a la vez):

GET ~/pages

Es mejor usar la siguiente llamada varias veces (especialmente si no necesita todas las secciones):

GET ~/sections/{id}/pages

Si se obtienen los metadatos de la página, se anula el orden predeterminado de lastModifiedDateTime. Es más rápido obtener páginas cuando no es necesario ordenarlas por lastModifiedDateTime. Para ello, puede ordenarlas por cualquier otra propiedad; por ejemplo:

GET ~/sections/{id}/pages?$select=id,title,createdDateTime&$orderby=createdDateTime