Recursos · 86
Paginación de API: exportaciones sin pérdidas ni duplicados
Definir orden, tokens, permisos y recuperación cuando la colección cambia durante la lectura.
Actualizado · 3 min
Lo que esta guía ayuda a lograr
- Definir orden y alcance
- Tratar el token como continuación
- Detectar el final según el contrato
- Recuperar tras un fallo
- Conciliar el resultado
Comprobación rápida
- ¿Una página vacía indica el final?
- ¿Puede el cursor dar autorización?
- ¿Deduplicar evita pérdidas?
Método paso a paso
- 1
Definir orden y alcance
Documente filtros, orden y clave de desempate. Una fecha sola puede no bastar si varios objetos la comparten. Decida si la colección sigue viva o si la exportación usa una instantánea. No prometa una vista congelada cuando el proveedor no ofrece esa garantía.
Entregable: contrato de orden y coherencia.
- 2
Tratar el token como continuación
AIP-158 prevé tokens opacos y separa paginación y autorización: el token no concede acceso. Compruebe identidad y permisos en cada petición. Mantenga los parámetros de lectura conforme al contrato y trate caducidad o invalidación explícitamente.
Entregable: casos de token válido, caducado y no autorizado.
- 3
Detectar el final según el contrato
No suponga que una página corta es la última. Una API puede devolver menos elementos y proporcionar continuación. En AIP-158, un next_page_token vacío indica el final; adapte el cliente al contrato del proveedor real. Detecte también tokens repetidos sin avance.
Entregable: pruebas de finalización y bucles.
- 4
Recuperar tras un fallo
Guarde la continuación después de almacenar duraderamente el lote. Elimine duplicados mediante identificadores estables y separe recuperación de totales mostrados. Si caduca una instantánea, reinicie o concilie según una regla explícita; no concatene silenciosamente estados distintos.
Entregable: punto de recuperación y escenario de fallo.
- 5
Conciliar el resultado
Compare identificadores únicos, exclusiones, estados y total de referencia para el mismo corte. Pruebe creación, modificación y eliminación durante la lectura. Un número correcto no demuestra que sean los objetos correctos. Proteja archivos y trazas según sus datos.
Entregable: manifiesto de exportación y diferencias documentadas.
Una lectura paginada que puede recuperarse
En un contrato de tipo AIP-158, la continuación determina el siguiente paso. Una página corta no demuestra el final.
Definir la lectura
Conservar filtro, orden, parámetros e identidad autorizada.
Guardar el lote
Almacenar duraderamente objetos e identificadores.
Seguir la continuación
Un token presente lleva a otra petición con parámetros vinculados.
Conciliar al finalizar
Con token final vacío, comprobar exclusiones, referencia y cobertura.
Ejemplo ficticio: la conexión falla después de guardar un lote. La recuperación usa el punto guardado y comprueba identificadores ya tratados.
Hoja de cálculo reutilizable
Complete con sus observaciones autorizadas. Estos campos son una plantilla de trabajo, no resultados observados.
| Campo | Información a registrar |
|---|---|
| Colección | Filtros, orden, desempate y garantías |
| Continuación | Token, parámetros vinculados, caducidad y final |
| Recuperación | Lote duradero, identificadores únicos y punto guardado |
| Resultado | Manifiesto, exclusiones, corte y diferencias |
Ejemplo trabajado ficticio
Situación ilustrativa
Ejemplo ficticio: se añaden productos durante una exportación por offset y una fila cambia de página.
Decisión y pruebas esperadas
La prueba encuentra un duplicado y un producto ausente; el equipo usa una instantánea disponible o documenta lectura viva con conciliación.
Distinguir los mecanismos
| Mecanismo | Propósito | Verificación o limitación |
|---|---|---|
| Offset | Acceder a una posición numérica | Las inserciones pueden desplazar posiciones |
| Cursor | Continuar desde un marcador | No garantiza una instantánea por sí solo |
| Instantánea | Fijar un estado de referencia | Comprobar duración y coste |
Indicadores de gestión
| Indicador | Qué mide | Primera acción |
|---|---|---|
| Identificadores únicos | Objetos distintos conservados | Comparar con una referencia equivalente |
| Avance | Tokens y lotes que progresan | Detener bucles e investigar |
| Cobertura verificada | Objetos conciliados con la referencia | No confundir volumen con exhaustividad |
Errores comunes
- Las inserciones pueden desplazar posiciones
- No garantiza una instantánea por sí solo
- Comprobar duración y coste
Preguntas frecuentes
¿Una página vacía indica el final?
Consulte contrato y token de continuación. El tamaño de página por sí solo no debe decidirlo.
¿Puede el cursor dar autorización?
No. El servidor comprueba derechos independientemente del token de paginación.
¿Deduplicar evita pérdidas?
No. Elimina repeticiones pero no recupera objetos nunca leídos. Pruebe estabilidad del orden y cambios de colección.
Referencias oficiales
Las referencias respaldan el método. Adapte los controles a su contexto; no constituyen certificación. Los títulos de referencia originales y los documentos fuente pueden estar en otro idioma.
Referencias consultadas el .
