Paginación de los datos de Microsoft Graph en la aplicación
Algunas consultas GET en Microsoft Graph devuelven varias páginas de datos debido a la paginación del lado servidor o a la paginación del lado cliente. La paginación de datos ayuda a mejorar el rendimiento de la aplicación y el tiempo de respuesta de Microsoft Graph.
Nota:
Si busca información sobre la paginación en los SDK de Microsoft Graph, consulte Página a través de una colección mediante los SDK de Microsoft Graph.
Obtenga más información sobre la paginación a través del siguiente vídeo.
Cómo funciona la paginación
En la paginación del lado cliente, una aplicación cliente especifica el número de resultados que quiere que Microsoft Graph devuelva en una sola página mediante los parámetros de consulta $top, $skip o $skipToken . La compatibilidad con la paginación del lado cliente, incluido el número de resultados que el cliente puede solicitar en una sola página, depende de la API y de la consulta que se realice. Por ejemplo, el punto de /users
conexión admite $top
pero no $skip
.
En la paginación del lado servidor, el servicio Microsoft Graph devuelve un número predeterminado de resultados en una sola página sin que el cliente especifique el número de resultados que se devolverán mediante $top
. Por ejemplo, el GET /users
punto de conexión devuelve un valor predeterminado de 100 resultados en una sola página.
Cuando se requiere más de una solicitud de consulta para recuperar todos los resultados, Microsoft Graph devuelve una @odata.nextLink
propiedad en la respuesta que contiene una dirección URL a la página siguiente de resultados. Para recuperar la siguiente página de resultados, se envía el valor de dirección URL de la propiedad @odata.nextLink
a Microsoft Graph. Microsoft Graph seguirá devolviendo una referencia a la siguiente página de resultados de la @odata.nextLink
propiedad con cada respuesta hasta que no haya más páginas de resultados que recuperar. Para leer todos los resultados, debe seguir llamando a Microsoft Graph con la @odata.nextLink
propiedad devuelta en cada respuesta hasta @odata.nextLink
que la propiedad ya no se devuelva.
Por ejemplo, en el ejemplo siguiente se muestra la paginación del lado cliente donde el cliente usa el parámetro de $top
consulta para solicitar hasta cinco usuarios en el inquilino.
GET https://graph.microsoft.com/v1.0/users?$top=5
Si el resultado contiene más resultados, Microsoft Graph devuelve una @odata.nextLink
propiedad similar a la siguiente junto con la primera página de resultados:
"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=RFNwdAIAAQAAAD8...AAAAAAAA"
Use toda la dirección URL de la @odata.nextLink
propiedad en una solicitud GET para recuperar la siguiente página de resultados. En función de la API en la que se realice la consulta, el valor de dirección @odata.nextLink
URL contiene un $skiptoken
parámetro de consulta o $skip
. La dirección URL contiene también todos los demás parámetros de consulta presentes en la solicitud original. No intente extraer el $skiptoken
valor o $skip
y úselo en una solicitud diferente.
El comportamiento de paginación varía entre las distintas API de Microsoft Graph. Al trabajar con datos paginados tenga en cuenta lo siguiente:
- Una página de resultados puede contener cero resultados o más.
- Las distintas API pueden tener tamaños de página predeterminados y máximos diferentes.
- Las distintas API pueden comportarse de forma diferente si se especifica un tamaño de página (a través del parámetro de consulta
$top
) que supera el tamaño máximo de página para la API. Según la API, se puede omitir el tamaño de página solicitado, se puede usar el tamaño de página máximo predeterminado para la API o Microsoft Graph puede devolver un error. - No todos los recursos o relaciones admiten la paginación. Por ejemplo, las consultas en directoryRole no admiten la paginación. Esto incluye la lectura de los propios objetos de rol y los miembros del rol.
- Al paginar con recursos de directorio, los encabezados de solicitud personalizados (encabezados que no son encabezados Authorization o Content-Type), como el encabezado ConsistencyLevel , no se incluyen de forma predeterminada en las solicitudes de página posteriores. Si es necesario enviar esos encabezados en solicitudes posteriores, debe establecerlos explícitamente.
- Cuando se usa la
$count=true
cadena de consulta al realizar consultas en recursos de directorio, la@odata.count
propiedad solo se devuelve en la primera página del conjunto de resultados paginado.
Contenido relacionado
- Los SDK de Microsoft Graph proporcionan clases y métodos para ayudar con la paginación. Para obtener más información, consulte Página a través de una colección mediante los SDK de Microsoft Graph.