As exportações de relatórios tornam-se não confiáveis quando um filtro de tempo, limite de página e chegada tardia são tratados como detalhes não relacionados. Um resultado que parece completo pode omitir registros que compartilham um carimbo de data/hora ou contar o mesmo relatório duas vezes. Anote as regras de seleção antes de construir o ciclo de exportação.
Escolha o horário que será filtrado
Relatórios agregados ter um período de avaliação; o cobrador também tem um horário de recebimento. RFC 9990 define a estrutura do relatório agregado, incluindo seu intervalo de datas. Uma exportação filtrada por horário de recebimento responde o que chegou durante a janela, não necessariamente quais mensagens foram avaliadas durante ela. Nomeie o campo escolhido e preserve ambos os significados quando disponíveis.
Use carimbos de data/hora UTC com uma convenção de limite explícita. O exemplo hipotético de tempo de recebimento abaixo usa uma janela entreaberta: incluir início, excluir fim. As exportações diárias adjacentes não se sobrepõem apenas porque compartilham a meia-noite. Para um provedor com semântica documentada diferente, traduza deliberadamente e desduplique, em vez de fingir que seu limite final é exclusivo.
Siga o mecanismo de continuação do serviço
Não ache que todo endpoint usa números de página ou que uma página curta sempre termina o resultado. Documentação de paginação do GitHub demonstra os seguintes cabeçalhos de link, quando fornecidos. Outros serviços usam cursores opacos. Siga o contrato real, mantenha o filtro ativo e pare somente sob a condição de conclusão definida.
Pergunte se a paginação observa um instantâneo estável. Se os recém-chegados puderem alterar a associação à página, a paginação deslocada poderá pular ou repetir registros. Use ordem estável e cursores vinculados a instantâneos quando houver suporte. Para um projeto proposto, um tempo de recebimento estável, uma ordem de identidade e um cursor vinculado ao instantâneo/filtro podem tornar a continuação auditável. Use a chave de identidade completa do provedor como desempate; apenas um ID de relatório não precisa ser exclusivo entre os repórteres. Estas são recomendações de design, não garantias verificadas do fornecedor.
Teste limites com entradas conhecidas
Suponha um instantâneo fixo para um relator e inquilino, filtrado por horário de recebimento para um dia UTC. O relatório 0 chegou um segundo antes do dia e contém 10 observações. Os relatórios 1 e 2 chegaram ao meio-dia e possuem 30 e 20 observações; o relatório 3 chegou às 18h e tem 50. O relatório 4 chegou exatamente na meia-noite seguinte e tem 50. Sob uma regra de inclusão-início/exclusão-fim, selecione os IDs 1, 2 e 3: 30 + 20 + 50 = 100 observações. Com o tamanho de página assumido de dois e desempate de identidade estável, os registros selecionados ocupam páginas de dois e um.
Estes são fatos de entrada inventados e aritmética esperada, não uma exportação ou teste de paginação executado. Verifique as identidades e os totais: substituir o relatório 4 fora da janela pelo relatório 3 preservaria 100, mas selecionaria o conjunto errado. Este exemplo filtra todos os tempos de recebimento do relatório; ele não infere carimbos de data/hora de mensagens individuais a partir de um intervalo de relatório agregado. Uma consulta de corte de coleção ou de período histórico precisa de suas próprias regras documentadas.
Preservar evidências de integridade
Armazene o filtro original, versão, sequência de continuação, contagem de linhas, identidades distintas e status final com os dados exportados. Se uma página falhar, rotule a exportação como incompleta e retome ou reinicie no mecanismo compatível do provedor. Nunca mostre um resultado parcial como uma métrica mensal completa.
Revise janelas vazias, filtros alterados, cursores repetidos e expiração do cursor. Um cursor expirado pode exigir um novo instantâneo e reconciliação, em vez de continuar a partir de uma página adivinhada. Para relatórios históricos do período de avaliação, permita um limite de cobrança e explique as correções tardias. O leitor deverá ser capaz de dizer quais observações foram incluídas e quais fontes esperadas estavam ausentes.