API e automatização

Escritas simultâneas em uma API de arquivos: como evitar sobrescritas e resolver conflitos

Um guia geral para detectar condições de corrida em escritas, verificar se a API documenta controles condicionais, coordenar atualizações e recuperar alterações de forma verificável.

Apification
Diagrama de dois processos que atualizam um arquivo e uma estratégia para resolver o conflito entre versões

O que é uma sobrescrita simultânea

Imagine que dois processos, A e B, baixam o mesmo arquivo no estado V1. A altera o título e salva uma cópia; depois, B altera um número e salva sua cópia, que ainda parte de V1. Se cada escrita substituir todo o conteúdo, a segunda poderá apagar o título atualizado por A. O resultado pode parecer correto à primeira vista, embora uma alteração tenha desaparecido sem aviso.

A condição de corrida não exige que as operações comecem exatamente ao mesmo tempo: basta que se sobreponham entre a leitura e a escrita. O risco pode surgir quando vários trabalhadores de uma integração, uma pessoa e uma automação ou tarefas separadas atuam sobre o mesmo recurso. A questão principal não é apenas quem escreveu por último, mas sobre qual versão cada atualização foi construída.

O que segue são padrões gerais de projeto e diagnóstico, não uma descrição do comportamento de uma API específica nem uma garantia sobre a Apification. Verifique os recursos e as respostas da API que você usa antes de basear uma integração neles.

  • Exemplo: A lê V1; B lê V1; A salva V2; B salva sua cópia de V1 e pode apagar a alteração de A.
O que é uma sobrescrita simultânea

Reconheça o risco no fluxo de leitura, modificação e escrita

Mapeie o percurso de cada operação: como o processo obtém o arquivo, se modifica o conteúdo inteiro ou apenas uma parte, quanto tempo passa antes de salvar e qual resposta interpreta como sucesso. Uma operação de substituição completa merece atenção especial se a cópia enviada se baseia em uma leitura anterior. Também pode haver risco quando um processo transforma documentos fora da API e depois envia o resultado novamente.

Procure possíveis pontos de sobreposição: vários trabalhos podem atuar sobre o mesmo identificador; há novas tentativas; fluxos diferentes compartilham recursos; ou as atualizações demoram. Como prática geral de diagnóstico, registre o recurso afetado, a origem da operação, os horários de leitura e escrita e o resultado informado pela API. Não registre credenciais nem conteúdo confidencial.

  • Mapeie todos os possíveis responsáveis por escrever no recurso, incluindo usuários, processos agendados e novas tentativas.
  • Verifique se cada operação substitui o arquivo inteiro ou aplica uma alteração parcial.
Reconheça o risco no fluxo de leitura, modificação e escrita

Verifique o contrato antes de usar ETag ou If-Match

Antes de implementar uma proteção, consulte a documentação oficial e o contrato OpenAPI da API específica. Verifique se a resposta de leitura inclui um identificador de versão ou ETag e se a operação de escrita aceita uma condição como If-Match ou outro mecanismo expressamente documentado. O fato de um cabeçalho existir em outra API ou aparecer em um exemplo de código não demonstra que a API utilizada o aceita.

Se a documentação confirmar o mecanismo, siga as instruções para obter e enviar o valor da versão e interpretar uma rejeição por estado desatualizado. As evidências disponíveis não confirmam que a Apification aceite ETag, If-Match ou outro controle condicional; não presuma que esses recursos estão disponíveis sem verificar a documentação da operação aplicável.

  • Anote qual mecanismo a API documenta, onde a versão é obtida e qual resposta indica um conflito.
  • Se não houver documentação explícita, considere o controle condicional não confirmado.

Se não houver controle condicional documentado, considere coordenar as escritas

Como padrão geral de integração, você pode coordenar os trabalhos enviados pelo seu próprio sistema para evitar que dois deles escrevam simultaneamente no mesmo recurso. Uma opção é usar uma fila ou exclusão por identificador: pode haver atividade em arquivos diferentes, mas apenas um trabalho por vez é processado para cada arquivo. Defina como a ordem será preservada e o que acontecerá se um trabalho falhar ou ficar parado.

Essa coordenação local não controla usuários nem outros sistemas que escrevam diretamente no recurso e não é uma garantia global. Também não repita automaticamente uma escrita com falha sem saber o resultado: em caso de timeout, nem sempre é possível deduzir apenas pelo cliente se a alteração foi aplicada. Verifique o estado atual pelos meios documentados pela API antes de decidir o que fazer.

  • Se optar por uma fila, agrupe os trabalhos por recurso e limite a um o número de escritores coordenados ativos por grupo.
  • Defina limites de espera e um procedimento para interromper e retomar o processamento.
  • Evite repetir às cegas depois de um timeout.

Resolva um conflito sem apagar alterações válidas

Se a API informar um conflito ou você detectar que o estado mudou desde a leitura, não continue salvando sobre a cópia antiga. Leia novamente o estado disponível e compare-o com aquele usado pelo processo. Se as alterações afetarem partes independentes e a API permitir uma atualização segura, prepare uma nova alteração com base no estado atual. Se forem incompatíveis, preserve as duas propostas e solicite uma decisão humana, em vez de escolher uma delas silenciosamente.

Um trabalho acadêmico da Escola Politécnica Nacional descreve uma implementação com colunas de versão para detectar alterações simultâneas: quando ocorria uma alteração posterior à leitura, era possível forçar uma nova tentativa ou notificar o conflito; nessa implementação, alterações simultâneas conflitantes eram rejeitadas. É um exemplo de controle otimista em uma aplicação, não uma evidência de que uma API de arquivos ou a Apification implemente esse mecanismo nem de que suas respostas sejam iguais. Fonte: Biblioteca Digital da Escola Politécnica Nacional, https://bibdigital.epn.edu.ec/bitstream/15000/26284/1/CD14960.pdf.

Como orientação geral, mantenha um registro verificável do estado observado, da alteração que se pretendia aplicar, do motivo de qualquer nova tentativa ou intervenção e do resultado final. Limite as novas tentativas e leia novamente antes de cada tentativa autorizada. Se não for possível comparar ou combinar o conteúdo com segurança, encaminhe o caso para revisão.

  • Leia novamente o estado atual antes de reconstruir uma atualização.
  • Tente novamente apenas depois de verificar a nova versão e as regras de combinação aplicáveis.
  • Solicite revisão humana quando as alterações forem incompatíveis ou não puderem ser comparadas.

Teste condições de corrida, timeouts e respostas tardias

Como teste geral de integração, prepare dois processos e coordene-os para que ambos leiam o mesmo estado antes de tentar salvar. Altere uma parte diferente em cada processo e observe se o resultado final preserva as duas alterações ou se uma desaparece. Repita o teste invertendo a ordem das escritas. O resultado descreve o comportamento observado naquele ambiente de teste; não demonstra que a API ofereça um mecanismo específico.

Inclua casos com demora antes de salvar, timeout depois do envio da solicitação, resposta tardia e nova tentativa. Verifique o estado final com uma nova leitura e confirme que os registros permitem reconstruir a sequência. Se a API documentar um controle condicional, teste também a resposta quando uma versão tiver mudado. Não considere uma resposta de sucesso do cliente, por si só, prova de que o estado final é o esperado.

  • Teste duas leituras do mesmo estado e escritas nas duas ordens.
  • Inclua timeout, resposta tardia e nova tentativa; inspecione o estado final depois de cada cenário.

Use o histórico do Cloud para recuperação, não para prevenção

O Apification Cloud permite consultar o histórico de um item, baixar versões anteriores e restaurar conteúdo. Esses recursos podem fazer parte de um procedimento de recuperação: identifique o item, examine o histórico, baixe uma versão pertinente para inspecioná-la e decida se deve restaurá-la.

O histórico não impede que dois processos provoquem uma sobrescrita nem determina, por si só, qual era a intenção de cada responsável pela escrita. Antes de restaurar, confirme se a versão escolhida contém o que você precisa e considere se uma alteração posterior também deve ser preservada. Não presuma que a API expõe as mesmas ações que o Cloud: verifique separadamente as operações documentadas pela API.

  • Examine ou baixe a versão candidata antes de restaurá-la.
  • Considere a restauração uma forma de recuperar conteúdo, não um mecanismo de coordenação de escritas.

Lista de verificação antes da produção

Antes da implantação, confirme o contrato de leitura e escrita, os possíveis responsáveis por escrever e a unidade real de atualização. Verifique se há um mecanismo condicional documentado; se isso não estiver confirmado, decida se a coordenação local de trabalhos se encaixa no seu fluxo e tenha em mente seus limites. Defina como os conflitos serão detectados e quando será necessário ler novamente, tentar outra vez ou solicitar uma revisão.

Valide o procedimento de recuperação com uma versão de teste e confirme que os registros expliquem o resultado sem expor segredos. Teste a concorrência, a ordem inversa, os timeouts e as respostas tardias. A Apification permite integrar o Cloud e seus serviços por meio de API REST, OpenAPI e webhooks; a disponibilidade de um controle de versão específico em uma operação deve ser confirmada na documentação dessa operação.

  • Contrato verificado; ETag, If-Match ou outro controle é usado apenas se estiver documentado.
  • A coordenação local, se adotada, tem escopo e limites definidos.
  • Conflitos, novas tentativas, timeouts e respostas tardias foram testados.
  • Procedimentos de revisão e restauração de versões foram verificados.
  • Há registros suficientes para auditar o fluxo, sem credenciais nem dados confidenciais.

Perguntas frequentes

Posso usar If-Match com qualquer API de arquivos?

Não presuma que sim. Verifique se a documentação da API indica que ela aceita esse mecanismo, como obter a versão e qual resposta retorna em caso de conflito.

Coordenar as escritas elimina todo o risco de sobrescrita?

Não necessariamente. Uma fila local pode coordenar os trabalhos que passam por ela, mas não controla, por si só, usuários ou outros sistemas que escrevem diretamente no mesmo recurso.

O histórico do Apification Cloud evita condições de corrida?

Não. O Cloud permite examinar o histórico, baixar versões anteriores e restaurar conteúdo. Esses recursos ajudam a investigar e recuperar, mas não substituem a prevenção ou a coordenação de escritas simultâneas.

Fontes e leituras

Documentação consultada para preparar este artigo.

Explore Apification

Artigos relacionados

Voltar ao blog