Compartir a través de

Resultados de página usando OData

Utiliza la paginación de OData con el encabezado de la solicitud Prefer: odata.maxpagesize para controlar el número de registros devueltos desde Microsoft Dataverse Web API. Si no especifica un número, cada solicitud puede devolver hasta 5000 filas de tabla. Para las tablas estándar y elásticas, puede especificar un tamaño máximo de página hasta 5000. El servicio omite las solicitudes de tamaño máximo de página superiores a 5000 para las tablas estándar y elásticas.

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 el uso de la opción de consulta $top para limitar el número 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 más páginas, use el mismo odata.maxpagesize valor de preferencia usado 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, el valor del $skiptoken parámetro en el valor de dirección @odata.nextLink URL contiene información codificada. El servidor establece esta información codificada para controlar la paginación. No modifique la información codificada ni codifique 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 a Dataverse cuál es la página anterior. 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 de 50 y retrocede, 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:

Estado Estado Página
Abrir Activo 1 Inicio
Abrir Activo 1
Abrir Activo 1 Fin
Abrir Activo
Abrir Activo
Abrir Inactivas
Abrir 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 orden 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, pero también se ordena utilizando el ID de caso. Los resultados tienen este aspecto:

Estado Estado Id. de caso Página
Abrir Activo Caso-0010 1 Inicio
Abrir Activo Caso-0021 1
Abrir Activo Caso-0032 1 Fin
Abrir Activo Caso-0034
Abrir Activo Caso-0070
Abrir Inactivas Caso-0015
Abrir Inactivas Caso-0047

En la siguiente página, la cookie tendrá Case-0032 almacenada como el último registro de la primera página, por lo que la página dos comenzará con el registro siguiente a dicho registro. Los resultados tienen este aspecto:

Estado Estado Id. de caso Página
Abrir Activo Caso-0010 1 Inicio
Abrir Activo Caso-0021 1
Abrir Activo Caso-0032 1 Fin
Abrir Activo Caso-0034 2 Inicio
Abrir Activo Caso-0070 2
Abrir Inactivas Caso-0015 2 Fin
Abrir 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 recupere un conjunto limitado de datos para mostrarlos en una aplicación, o si necesita devolver más de 5000 filas de datos (500 para tablas elásticas), debe 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 la tabla
  • Columnas autonumeradas
  • 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 la ordenación 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
    • Asigne nombres a los valores de forma independiente. 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.

Agregar datos

  • Last updated on