Resultados de la página utilizando OData
Utilice el encabezado de solicitud Prefer: odata.maxpagesize para controlar la cantidad de registros devueltos. Si no especifica un número, se pueden devolver hasta 5000 registros por cada solicitud. No puede solicitar un tamaño de página superior a 5000.
Nota
Dataverse no admite la opción de consulta $skip, por lo que no puede usar la combinación de $top y $skip para la paginación. Obtenga información sobre cómo utilizar la opción de consulta $top para limitar la cantidad de filas
El siguiente ejemplo devuelve solo los dos primeros registros de contacto:
Solicitud:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2
Respuesta:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
"value": [
{
"@odata.etag": "W/\"72201545\"",
"fullname": "Yvonne McKay (sample)",
"contactid": "49b0be2e-d01c-ed11-b83e-000d3a572421"
},
{
"@odata.etag": "W/\"80648695\"",
"fullname": "Susanna Stubberod (sample)",
"contactid": "70bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Cuando hay más registros de los solicitados, la anotación @odata.nextLink proporciona una URL que puede usar con GET para devolver la siguiente página de datos, como se muestra en el siguiente ejemplo:
Solicitud:
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253ccontactid%2520last%253d%2522%257bD5026A4D-D01C-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257b49B0BE2E-D01C-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.maxpagesize=2
Respuesta:
HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.maxpagesize=2
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#contacts(fullname)",
"value": [
{
"@odata.etag": "W/\"80648710\"",
"fullname": "Nancy Anderson (sample)",
"contactid": "72bf4d48-34cb-ed11-b596-0022481d68cd"
},
{
"@odata.etag": "W/\"80648724\"",
"fullname": "Maria Campbell (sample)",
"contactid": "74bf4d48-34cb-ed11-b596-0022481d68cd"
}
],
"@odata.nextLink": "[Organization URI]/api/data/v9.2/contacts?$select=fullname&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253ccontactid%2520last%253d%2522%257bF2318099-171F-ED11-B83E-000D3A572421%257d%2522%2520first%253d%2522%257bBB55F942-161F-ED11-B83E-000D3A572421%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
}
Debe almacenar en caché los resultados devueltos o el valor de URL @odata.nextLink y utilizarlos para volver a las páginas anteriores.
No cambie el valor de la URL @odata.nextLink ni le anexe opciones de consulta. Para cada solicitud posterior de páginas adicionales, debe usar el mismo valor de preferencia de odata.maxpagesize que usó en la solicitud original. Puede continuar paginando los datos hasta que no se incluya ninguna anotación @odata.nextLink en los resultados.
En los ejemplos anteriores, la información codificada se estableció como el valor del parámetro $skiptoken en el valor de URL @odata.nextLink. El servidor establece esta información codificada para controlar la paginación. No debe modificar la información codificada ni codificarla más. Utilice el valor de URL proporcionado para recuperar la página siguiente.
No utilice la opción de consulta $top al paginar registros
Use la opción de consulta $top para limitar el número de resultados devueltos. No use $top con el encabezado de solicitud Prefer: odata.maxpagesize. Si incluye ambos, $top se ignora.
El siguiente ejemplo solo devuelve las primeras tres filas de cuenta:
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3
Ordenación y paginación
La forma en que se ordena una página marca una gran diferencia al paginar datos. Si la información sobre cómo se ordenan los resultados es ambigua, Dataverse no puede devolver datos paginados de manera consistente o eficiente.
Especifique un pedido para su consulta. Con FetchXml, si no agrega ningún elemento de pedido a su consulta, Dataverse agrega un pedido basado en la clave principal de la tabla. Sin embargo, QueryExpression no lo hace, y cuando su consulta especifica resultados distinct, no se devuelven valores de clave principal, por lo que Dataverse no puede agregar este orden predeterminado. Debe especificar un orden de paginación. Sin ningún orden especificado, los resultados de la consulta de distinct pueden devolverse en orden aleatorio. OData no proporciona ninguna opción para devolver resultados distintos, pero aún así debes aplicar un orden al recuperar resultados paginados.
La paginación es dinámica. Cada solicitud se evalúa de forma independiente a medida que se recibe. Una cookie de paginación indica la página anterior de Dataverse. Con estos datos de cookie de paginación, Dataverse puede comenzar con el siguiente registro después del último en la página anterior.
La paginación funciona mejor en el futuro. Si regresa y recupera una página que recuperó anteriormente, los resultados pueden ser diferentes porque se podrían agregar, eliminar o modificar registros desde la última vez que recuperó la página. En otras palabras, si el tamaño de su página es 50 y regresa, obtendrá 50 registros, pero es posible que no sean los mismos 50 registros. Si continúa avanzando por las páginas de un conjunto de datos, puede esperar que todos los registros se devuelvan en una secuencia coherente.
La ordenación determinista es importante
Orden determinista significa que hay una manera de calcular un orden de manera consistente. Con un conjunto de registros determinado, los registros siempre se devuelven en el mismo orden. Si necesita pedidos y paginación consistentes, debe incluir algunos valores únicos o una combinación de valores de columna y especificar un orden para que se evalúen.
Ejemplo no determinista
Veamos un ejemplo que es nodeterminista. Este conjunto de datos contiene solo información de estado y estado y se filtra para devolver solo registros en un estado abierto. Los resultados se ordenan por estado. Se solicitan las tres primeras páginas. Los resultados tienen este aspecto:
| Valor | Estado | Página |
|---|---|---|
| Apertura | Activas | 1 Inicio |
| Apertura | Activas | 1 |
| Apertura | Activas | 1 Fin |
| Apertura | Activas | |
| Apertura | Activas | |
| Apertura | Inactivas | |
| Apertura | Inactivas |
La cookie de paginación guarda información sobre el último registro de la página. Cuando se solicita la página siguiente, no se incluye el último registro de la primera página. Sin embargo, dados los datos no deterministas, no hay garantía de que los otros dos registros de la primera página no estén incluidos en la segunda página.
Para lograr un orden determinista, agregue pedidos en columnas que contengan valores únicos o valores semiúnicos.
Ejemplo determinista
Esta consulta es como la no determinista, pero incluye la columna Id. de caso que incluye valores únicos. También se ordena por Estado y por Id. de caso. Los resultados tienen este aspecto:
| Valor | Estado | Id. de caso | Página |
|---|---|---|---|
| Apertura | Activas | Caso-0010 | 1 Inicio |
| Apertura | Activas | Caso-0021 | 1 |
| Apertura | Activas | Caso-0032 | 1 Fin |
| Apertura | Activas | Caso-0034 | |
| Apertura | Activas | Caso-0070 | |
| Apertura | Inactivas | Caso-0015 | |
| Apertura | Inactivas | Caso-0047 |
En la siguiente página, la cookie tendrá el Case-0032 almacenado como el último registro en la primera página, por lo que la página dos comenzará con el siguiente registro en el conjunto después de ese registro. Los resultados tienen este aspecto:
| Valor | Estado | Id. de caso | Página |
|---|---|---|---|
| Apertura | Activas | Caso-0010 | 1 Inicio |
| Apertura | Activas | Caso-0021 | 1 |
| Apertura | Activas | Caso-0032 | 1 Fin |
| Apertura | Activas | Caso-0034 | 2 Inicio |
| Apertura | Activas | Caso-0070 | 2 |
| Apertura | Inactivas | Caso-0015 | 2 Fin |
| Apertura | Inactivas | Caso-0047 |
Dado que esta consulta ordena valores de columna únicos, el orden es coherente.
Procedimientos recomendados para órdenes al paginar datos
Nota
Cuando sea posible, las consultas deben ordenarse según la clave principal de la tabla porque Dataverse está optimizada para ordenar según la clave principal de forma predeterminada. Ordenar por campos no únicos o complejos genera una sobrecarga excesiva y consultas más lentas.
Cuando recupera un conjunto limitado de datos para mostrar en una aplicación, o si necesita devolver más de 5000 filas de datos, necesita paginar los resultados. Las elecciones que haga para determinar el orden de los resultados pueden determinar si las filas de cada página de datos que recupere se superponen con otras páginas. Sin un orden adecuado, el mismo registro puede aparecer en más de una página.
Para evitar que el mismo registro aparezca en más de una página, aplique los siguientes procedimientos recomendados:
Lo mejor es incluir una columna que tenga un identificador único. Por ejemplo:
- Columnas de clave principal de tabla
- Columnas de autonumeración
- Id. de usuario/contacto
Si no puede incluir una columna con un identificador único, incluya varios campos que probablemente darán como resultado combinaciones únicas. Por ejemplo:
- Nombre + apellido + dirección de correo electrónico
- Nombre completo + dirección de correo electrónico
- Dirección de correo electrónico + nombre de la empresa
Antipatrones para órdenes al paginar datos
Las siguientes son opciones de orden que se deben evitar:
Órdenes que no incluyen identificadores únicos
Órdenes en campos calculados
Órdenes que tienen campos únicos o múltiples que es poco probable que proporcionen unicidad, como:
- Estatus y estado
- Elecciones o Sí/No
- Nombre los valores por sí mismos. Por ejemplo
name,firstname,lastname - Campos de texto como títulos, descripciones y texto de varias líneas
- Campos numéricos no únicos
Pasos siguientes
Aprenda a agregar datos.
Nota
¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)
La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).