Recursos · 86
Exportações API: paginação, retoma e reconciliação
Definir o que se lê, quando continuar e como comprovar a cobertura.
Atualizado · 3 min
O que este guia ajuda a alcançar
- Definir a coleção
- Tratar o cursor como continuação
- Reconhecer o fim previsto
- Retomar após escrita durável
- Reconciliar cobertura
Verificação rápida
- Uma página vazia termina a exportação?
- Ter um cursor concede acesso?
- Deduplicar evita todas as perdas?
Método passo a passo
- 1
Definir a coleção
Fixar filtros, ordenação e desempate. Dois registos podem ter o mesmo timestamp. Distinguir uma coleção que muda durante a leitura de uma fotografia efetivamente garantida pelo serviço.
Resultado: âmbito e ordem documentados.
- 2
Tratar o cursor como continuação
Um token opaco não autoriza acesso. Verificar identidade e permissões em cada pedido, associar a continuação aos parâmetros e explicar validade e reutilização.
Resultado: contrato do token e controlos de acesso.
- 3
Reconhecer o fim previsto
Uma página curta ou vazia nem sempre significa fim. No contrato AIP-158, o fim é indicado pela ausência de next_page_token. Detetar tokens repetidos e pedidos sem progresso.
Resultado: condição de fim e alerta de ciclo.
- 4
Retomar após escrita durável
Guardar o checkpoint depois de registar o lote. Deduplicar com identificadores estáveis. Se a fotografia expirar, escolher nova leitura ou reconciliação de forma explícita.
Resultado: recuperação testada sem garantias inexistentes.
- 5
Reconciliar cobertura
Comparar identificadores únicos, estados, exclusões e referência temporal. Contagens iguais podem corresponder a objetos diferentes. Testar criações, alterações e eliminações durante a leitura.
Resultado: evidência do âmbito efetivamente exportado.
Continuar ou retomar?
Ler o contrato antes de interpretar a página.
Fim declarado?
Terminar apenas com o sinal previsto pelo serviço.
Token válido e com progresso?
Detetar expiração, repetição e parâmetros incoerentes.
Lote registado?
Atualizar checkpoint depois de escrita durável.
Cobertura reconciliada?
Comparar identificadores e âmbito de referência.
Uma página vazia com token válido pode exigir outro pedido.
Planilha reutilizável
Preencha com suas observações autorizadas. Estes campos são um modelo de trabalho, não resultados observados.
| Campo | Informações a serem registradas |
|---|---|
| Coleção | Filtros, ordem, desempate e referência |
| Continuação | Token, validade e fim |
| Retoma | Checkpoint e escrita durável |
| Resultado | Identificadores, exclusões e reconciliação |
Exemplo prático fictício
Situação ilustrativa
Exemplo fictício: durante uma exportação por offset são acrescentados produtos no início da lista.
Decisão e evidências esperadas
O teste encontra repetições e ausências. Usa-se uma fotografia disponível ou declara-se a leitura dinâmica e reconciliam-se os identificadores.
Distinguir os mecanismos
| Mecanismo | Finalidade | Verificação ou limitação |
|---|---|---|
| Offset | Acesso simples por posição | Inserções podem deslocar registos |
| Cursor | Continuação segundo contrato | Por si só não garante fotografia |
| Fotografia | Estabiliza âmbito quando disponível | Conhecer validade, custo e expiração |
Indicadores de gestão
| Indicador | O que mede | Primeira ação |
|---|---|---|
| Identificadores únicos | Objetos exportados sem repetições | Investigar sobreposições |
| Progresso | Tokens e páginas que avançam | Interromper ciclos |
| Cobertura verificada | Comparação com referência definida | Explicar ausências e alterações |
Erros comuns
- Inserções podem deslocar registos
- Por si só não garante fotografia
- Conhecer validade, custo e expiração
Perguntas frequentes
Uma página vazia termina a exportação?
Depende do contrato. Verificar o sinal de continuação em vez de deduzir o fim apenas pelo tamanho.
Ter um cursor concede acesso?
Não. Cada pedido aplica controlos de autorização.
Deduplicar evita todas as perdas?
Não. Retira repetições identificadas, mas não recupera registos nunca lidos.
Referências oficiais
As referências apoiam o método. Adapte as verificações ao seu contexto; elas não são uma certificação. Os títulos das referências originais e os documentos de origem podem estar em outro idioma.
Referências consultadas em .
