Processar lotes de arquivos com concorrência controlada

Por que não enviar tudo de uma vez

Ao automatizar o processamento de muitos arquivos, enviar todas as solicitações de uma vez pode dificultar o acompanhamento do que foi concluído, do que continua em andamento e do que falhou. Uma fila com um limite de tarefas ativas e um status por arquivo pode ajudar a organizar o trabalho, mas essas são decisões da sua integração, não um comportamento garantido por qualquer API.

As APIs oferecem modelos diferentes. A [API Batch da OpenAI](https://help.openai.com/es-es/articles/9197833-batch-api-faq) permite enviar solicitações para processamento assíncrono. A Microsoft documenta solicitações em lote para consultas e operações na [API REST/OData do SharePoint Online](https://learn.microsoft.com/es-es/sharepoint/dev/sp-add-ins/make-batch-requests-with-the-rest-apis). Esses exemplos têm escopos diferentes e não estabelecem uma regra comum de concorrência para outros serviços.

• Consulte primeiro a documentação do endpoint que você usará.
• Mantenha cada tarefa identificada por arquivo.
• Separe as funcionalidades documentadas pela API das decisões da sua fila.

Antes de começar: leia o contrato da API

Confira quais entradas o endpoint aceita, quais respostas retorna e se o resultado chega diretamente ou é processado de forma assíncrona. Verifique também se a documentação especifica limites, identificadores para consultar o andamento ou condições para repetir uma operação. Se determinado comportamento não estiver definido, não o presuma: consulte o provedor ou planeje um teste controlado.

Registre essas condições em uma ficha de integração e diferencie a aceitação de uma solicitação da conclusão do trabalho. A Apification permite integrar o Cloud e seus serviços por meio de REST API, OpenAPI e webhooks; isso não significa que todos os serviços compartilhem limites, status ou políticas de novas tentativas. Consulte a referência do serviço específico.

• Registre o endpoint, o método, o formato de entrada e a resposta esperada.
• Anote apenas os limites e as regras para novas tentativas que estiverem especificados.
• Identifique qual resposta confirma a aceitação e qual confirma a conclusão.

Crie uma fila com status por arquivo

Como decisão de projeto da sua aplicação, você pode representar cada arquivo como uma tarefa independente. Armazene um identificador interno, a referência ao arquivo e seus parâmetros; registre também o status local, as tentativas e o resultado ou erro relevante. Se a API retornar um identificador remoto, guardá-lo pode facilitar o acompanhamento quando o serviço documentar uma forma de consultar o status.

Use status locais com significados claros, por exemplo: pendente, em andamento, concluído e requer revisão. Não os apresente como status do provedor, a menos que a documentação dele os defina assim. Persistir esses registros ajuda a aplicação a identificar tarefas incompletas após uma interrupção, mas não determina, por si só, se uma operação remota foi executada. Proteja segredos e credenciais ao armazenar registros.

• Registre o resultado de cada tarefa, não apenas o total do lote.
• Diferencie os status locais dos status retornados pela API.
• Guarde o contexto necessário para investigar, sem registrar segredos.

Escolha e ajuste a concorrência

Não existe um número inicial universal que possa ser recomendado sem conhecer a API e as condições dela. Como diretriz de projeto, torne configurável o número de tarefas simultâneas e comece os testes com uma carga pequena. Observe as respostas e quaisquer restrições comunicadas pelo provedor; ajuste o limite de acordo com as regras documentadas e os resultados dos testes.

O tamanho total do lote e o número de tarefas simultâneas são conceitos diferentes: um lote grande pode ser processado em grupos menores. Se sua arquitetura usar vários consumidores, decida como o limite agregado será coordenado; não presuma que cada consumidor terá, individualmente, toda a capacidade permitida pela API.

• Comece com poucos itens e um limite configurável.
• Ajuste o limite conforme a documentação e as respostas observadas.
• Considere a atividade conjunta de todos os consumidores.

Classifique os erros e limite as novas tentativas

Classifique os erros de acordo com as respostas e as regras da API específica. Alguns podem exigir a correção do arquivo ou dos parâmetros; outros talvez justifiquem uma nova tentativa, se a documentação permitir. Não deduza uma política universal com base no texto do erro. Armazene o código e o contexto relevante para o diagnóstico, sem expor dados confidenciais.

Como decisão de projeto, você pode definir um número máximo de tentativas e um intervalo entre elas para os casos em que a documentação permita repetir a operação. Se uma solicitação ficar com status incerto, não a considere automaticamente falha nem a reenvie às cegas. Se a API documentar um mecanismo de idempotência, siga as condições dele; caso contrário, não presuma que seja seguro repetir a operação.

• Decida, para cada erro, se é preciso tentar novamente, corrigir ou revisar.
• Registre cada tentativa e evite ciclos indefinidos de novas tentativas.
• Tenha cautela com solicitações cujo resultado seja incerto.

Retome um lote interrompido

Ao reiniciar a aplicação, carregue o status persistido e mantenha as tarefas concluídas. Para as que ficaram em andamento, verifique se a API oferece uma forma documentada de consultar o status por meio de um identificador. Se não houver como resolver a incerteza, defina uma política explícita para esses casos ou encaminhe-os para revisão, em vez de reenviá-los automaticamente.

Mantenha uma identidade estável para cada tarefa e registre alterações no arquivo ou nos parâmetros como trabalhos distintos. A Apification permite consultar o histórico de itens do Cloud, baixar versões anteriores e restaurar conteúdo. Esses recursos ajudam a revisar alterações no Cloud, mas não substituem o acompanhamento de solicitações nem garantem que uma operação de API seja idempotente.

• Ignore as tarefas concluídas e revise as que ficaram em andamento.
• Não trate uma resposta perdida como confirmação de que a operação falhou.
• Registre alterações na entrada ou nos parâmetros para distinguir os trabalhos.

Fluxo operacional e testes

Um fluxo possível é validar os arquivos, criar uma tarefa persistida para cada item, processar as tarefas dentro do limite definido e registrar cada resposta. Ao final, mostre os resultados e separe as tarefas concluídas, as que precisam de correção e as que continuam incertas. Essas são decisões de projeto da sua integração, não garantias sobre o funcionamento de uma API externa.

Antes de usar o fluxo em produção, teste interrupções e situações em que a aplicação não consiga confirmar o resultado, como um timeout ou uma falha entre o envio e o registro da resposta. Verifique se a aplicação preserva o contexto necessário para investigar e se a política evita reenviar automaticamente tarefas concluídas ou com resultado desconhecido. Ajuste cada caso aos recursos documentados do serviço. A Apification oferece um assistente guiado para processar documentos, imagens, vídeo, áudio e dados, além de opções de integração por API; consulte a documentação do serviço para confirmar quais operações estão disponíveis pela API.

• Valide as entradas e defina o que significa concluir cada tarefa.
• Teste interrupções e status incertos sem presumir como o provedor responderá.
• Ao encerrar o lote, identifique pendências, erros corrigíveis e tarefas que precisam de revisão.

Perguntas frequentes