Solução de problemas do recurso Operações em Lote do S3 - Amazon Simple Storage Service
NoSuchJobExceptionInvalidManifestContent

Solução de problemas do recurso Operações em Lote do S3

O recurso Operações em Lote do Amazon S3 permite executar operações em grande escala em objetos do Amazon S3. Este guia ajuda você a solucionar problemas que costumam ocorrer.

Para solucionar problemas com o Replicação em Lote do S3, consulte Solução de problemas de replicação.

Existem dois tipos principais de falha que geram erros de operação em lote:

  1. Falha na API: a API solicitada (como CreateJob) não foi executada.

  2. Falha no trabalho: a solicitação inicial da API foi bem-sucedida, mas o trabalho apresentou falha devido, por exemplo, a problemas com o manifesto ou com as permissões dos objetos especificados no manifesto.

NoSuchJobException

Tipo: falha na API.

A NoSuchJobException ocorre quando o recurso Operações em Lote do S3 não consegue localizar o trabalho especificado. Esse erro pode ocorrer em várias situações, não apenas quando o trabalho expira. Algumas causas comuns são descritas a seguir.

  1. Expiração do trabalho: os trabalhos são excluídos automaticamente noventa dias depois que atingem um estado de término (Complete, Cancelled ou Failed).

  2. ID do trabalho incorreto: o ID do trabalho usado em DescribeJob ou UpdateJobStatus não corresponde ao ID exibido por CreateJob.

  3. Região errada: tentativa de acessar um trabalho em uma região diferente daquela em que foi criado.

  4. Conta errada: uso de um ID de trabalho de uma conta da AWS diferente.

  5. Erros de formato de ID de trabalho: erros de digitação, caracteres extras ou formatação incorreta no ID do trabalho.

  6. Problemas de regulação de tempo: verificação do status do trabalho imediatamente após a criação, antes que ele seja totalmente registrado.

As mensagens de erro relacionadas incluem as apresentadas abaixo.

  1. No such job

  2. The specified job does not exist

Práticas recomendadas para evitar falhas de API NoSuchJobException

  1. Armazene os IDs de trabalho imediatamente: salve o ID do trabalho da resposta CreateJob antes de fazer chamadas de API subsequentes.

  2. Implemente a lógica de repetição: adicione um recuo exponencial ao verificar o status do trabalho imediatamente após a criação.

  3. Configure o monitoramento: crie alarmes do CloudWatch para monitorar a conclusão do trabalho antes da expiração de noventa dias. Para obter detalhes, consulte Usar alarmes do CloudWatch no “Guia do usuário do Amazon CloudWatch”.

  4. Use regiões consistentes: garanta que todas as operações de trabalho usem a mesma região para a criação de trabalhos.

  5. Valide a entrada: verifique o formato do ID do trabalho antes de fazer chamadas de API.

Quando os trabalhos expiram

Os trabalhos nos estados de término são excluídos automaticamente após noventa dias. Para evitar a perda de informações sobre o trabalho, considere as opções a seguir.

  1. Baixe os relatórios de conclusão antes da expiração: para obter instruções sobre como recuperar e armazenar os resultados do trabalho, consulte .

  2. Arquive os metadados do trabalho em seus próprios sistemas: armazene informações essenciais do trabalho em seus bancos de dados ou sistemas de monitoramento.

  3. Configure notificações automáticas antes do prazo de noventa dias: use o Amazon EventBridge para criar regras que acionem notificações quando os trabalhos forem concluídos. Para obter mais informações, consulte Notificações de eventos do Amazon S3.

NoSuchJobExceptionSolução de problemas do

  1. Use o comando a seguir para verificar se o trabalho existe na sua conta e região.

    
aws s3control list-jobs --account-id 111122223333 --region us-east-1

  2. Use o comando a seguir para pesquisar todos os status de trabalho. Os possíveis status de trabalho incluem Active, Cancelled, Cancelling, Complete, Completing, Failed, Failing, New, Paused, Pausing, Preparing, Ready e Suspended.

    
aws s3control list-jobs --account-id 111122223333 --job-statuses your-job-status

  3. Use o comando a seguir para verificar se o trabalho existe em outras regiões onde você normalmente cria trabalhos.

    
aws s3control list-jobs --account-id 111122223333 --region job-region-1 aws s3control list-jobs --account-id 111122223333 --region job-region-2

  4. Valide o formato do ID do trabalho. Os IDs de trabalho normalmente contêm 36 caracteres, como 12345678-1234-1234-1234-123456789012. Verifique se há espaços extras, caracteres ausentes ou problemas de distinção entre maiúsculas e minúsculas e verifique se você está usando o ID completo do trabalho exibido pelo comando CreateJob.

  5. Use o comando a seguir para verificar os eventos de criação de trabalho nos logs do CloudTrail.

    
    aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \ --filter-pattern "{ $.eventName = CreateJob }" \ --start-time timestamp

AccessDeniedException

Tipo: falha na API.

A AccessDeniedException ocorre quando uma solicitação do recurso Operações em Lote do S3 é bloqueada devido a permissões insuficientes, operações não permitidas ou restrições de política. Esse é um dos erros mais comuns no recurso Operações em Lote. As causas costumam ser as seguintes:

  1. Permissões do IAM ausentes: a identidade do IAM não tem as permissões necessárias para as APIs do recurso Operações em Lote.

  2. Permissões insuficientes do S3: permissões ausentes para acessar buckets e objetos de origem ou destino.

  3. Problemas de perfil de execução de trabalho: o perfil de execução de trabalho não tem permissões para realizar a operação especificada.

  4. Operações não compatíveis: tentativa de usar operações não permitidas na região atual ou no tipo de bucket.

  5. Problemas de acesso entre contas: permissões ausentes para acesso a buckets ou objetos entre contas.

  6. Restrições de políticas baseadas em recursos: políticas de bucket ou ACLs de objetos que bloqueiam a operação.

  7. Restrições de política de controle de serviços (SCP): políticas em nível organizacional que impedem a operação.

Mensagens de erro relacionadas:

  1. Access Denied

  2. User: arn:aws:iam::account:user/username is not authorized to perform: s3:operation

  3. Cross-account pass role is not allowed

  4. The bucket policy does not allow the specified operation

Práticas recomendadas para evitar falhas de API AccessDeniedException

  1. Use o princípio de privilégio mínimo: conceda somente as permissões mínimas necessárias para suas operações específicas.

  2. Teste as permissões antes de trabalhos grandes: execute pequenos trabalhos de teste para validar as permissões antes de processar milhares de objetos.

  3. Use o simulador de políticas do IAM: teste as políticas antes da implantação usando o simulador de políticas do IAM. Para ter mais informações, consulte Testar políticas do IAM com o simulador de políticas do IAM no “Guia do usuário do IAM”.

  4. Implemente a configuração adequada entre contas: verifique sua configuração de acesso entre contas para ver as configurações de trabalhos entre contas. Para ter mais informações, consulte Tutorial do IAM: Delegar acesso entre contas da AWS usando funções do IAM no “Guia do usuário do IAM”.

  5. Monitore as alterações de permissão: configure alertas do CloudTrail para modificações na política do IAM que possam afetar as operações em lote.

  6. Documente os requisitos do perfil: mantenha uma documentação clara das permissões necessárias para cada tipo de trabalho.

  7. Use modelos de permissão comuns: use os exemplos de permissão e os modelos de política:

    1. Conceder permissões para operações em lote

    2. Acesso a recursos entre contas no IAM no “Guia do usuário do IAM”.

    3. Control access to VPC endpoints using endpoint policies no “Guia do usuário do AWS PrivateLink”.

Solução de problemas de AccessDeniedException

Siga estas etapas sistematicamente para identificar e resolver problemas de permissão.

  1. Verifique Operações suportadas pelo S3 Batch Operations para saber quais operações são permitidas por região. Confirme se as operações do bucket de diretório estão disponíveis somente em endpoints regionais e zonais. Verifique se a operação é compatível com a classe de armazenamento do seu bucket.

  2. Use o comando a seguir para determinar se você pode listar trabalhos.

    
 aws s3control list-jobs --account-id 111122223333

  3. Use o comando a seguir para verificar as permissões do IAM para a identidade solicitante. A conta que executa o trabalho precisa das seguintes permissões:s3:CreateJob, s3:DescribeJob, s3:ListJobs-s3:UpdateJobPriority e s3:UpdateJobStatus-iam:PassRole.

    
aws sts get-caller-identity 111122223333

  4. Use o comando a seguir para verificar se o perfil existe e pode ser assumido.

    
aws iam get-role --role-name role-name

  5. Use o comando a seguir para analisar a política de confiança do perfil. O perfil que executa o trabalho deve ter o seguinte:

    1. A relação de confiança que permite que batchoperations.s3.amazonaws.com assuma esse perfil.

    2. As operações que a operação em lote está executando (como s3:PutObjectTagging para operações de atribuição de tags).

    3. Acesso aos buckets de origem e de destino.

    4. Permissão para ler o arquivo de manifesto.

    5. Permissão para escrever relatórios de conclusão.

    
aws iam get-role --role-name role-name --query 'Role.AssumeRolePolicyDocument'

  6. Use o comando a seguir para restringir o acesso ao manifesto e aos buckets de origem.

    
aws s3 ls s3://bucket-name

  7. Teste a operação que está sendo executada pela operação em lote. Por exemplo, se a operação em lote realizar a atribuição de tags, marque um objeto de amostra no bucket de origem.

  8. Analise as políticas de bucket para verificar se há políticas que possam negar a operação.

    1. Verifique as ACLs de objetos se estiver trabalhando com controles de acesso legados.

    2. Verifique se nenhuma política de controle de serviços (SCPs) está bloqueando a operação.

    3. Confirme se as políticas de endpoint da VPC permitem operações em lote se você estiver usando endpoints da VPC.

  9. Use o comando a seguir para utilizar o CloudTrail para identificar falhas de permissão.

    
aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \
    --filter-pattern "{ $.errorCode = AccessDenied }" \
    --start-time timestamp

SlowDownError

Tipo: falha na API.

A exceção SlowDownError ocorre quando sua conta excede o limite da taxa de solicitação para APIs do recurso Operações em Lote do S3. Esse é um mecanismo de controle de utilização para impedir que o serviço seja sobrecarregado por solicitações. As causas costumam ser as seguintes:

  1. Alta frequência de solicitações de API: há muitas chamadas de API em um curto espaço de tempo.

  2. Operações de trabalho simultâneas: várias aplicações ou usuários criam/gerenciam trabalhos simultaneamente.

  3. Scripts automatizados sem limitação de taxa: scripts que não implementam estratégias de recuo adequadas.

  4. Pesquisas muito frequentes de status do trabalho: verificação do status do trabalho em uma frequência maior do que a necessária.

  5. Padrões de tráfego intermitentes: picos repentinos no uso da API durante horários de processamento de pico.

  6. Limites de capacidade regional: a capacidade de solicitação alocada para sua região é excedida.

Mensagens de erro relacionadas:

  1. SlowDown

  2. Please reduce your request rate

  3. Request rate exceeded

Práticas recomendadas para evitar falhas de API SlowDownError

  1. Implemente a limitação de taxa do lado do cliente: adicione atrasos entre as chamadas de API em suas aplicações.

  2. Use o recuo exponencial com oscilação: randomize os atrasos de novas tentativas para evitar problemas de “rebanho trovejante”.

  3. Configure a lógica de repetição adequada: implemente novas tentativas automáticas com atrasos crescentes para erros transitórios.

  4. Use arquiteturas orientadas a eventos: substitua a sondagem por notificações do EventBridge para alterações no status do trabalho.

  5. Distribua a carga ao longo do tempo: escalone a criação de trabalhos e as verificações de status em diferentes espaços de tempo.

  6. Monitore e emita alerta sobre limites de taxa: configure os alarmes do CloudWatch para detectar quando você está se aproximando dos limites.

A maioria dos SDKs da AWS inclui lógica integrada de nova tentativa para erros de limitação de taxa. Configure-os desta forma:

  1. AWS CLI: use os parâmetros cli-read-timeout e cli-connect-timeout.

  2. AWS SDK para Python (Boto3): configure os modos de nova tentativa e o máximo de tentativas na configuração do cliente.

  3. AWS SDK para Java: use as configurações RetryPolicy e ClientConfiguration.

  4. AWS SDK para JavaScript: configure maxRetries e retryDelayOptions.

Para ter mais informações sobre padrões e práticas recomendadas de novas tentativas, consulte Retry with backoff pattern no “Guia de orientação prescritiva da AWS“.

Solução de problemas de SlowDownError

  1. Em seu código, implemente o recuo exponencial imediatamente.

    exemplo Exemplo de recuo exponencial no bash
    
for attempt in {1..5}; do
    if aws s3control describe-job --account-id 111122223333 --job-id job-id; then 
        break
    else 
        wait_time=$((2**attempt)) echo "Rate limited, waiting ${wait_time} seconds..." sleep $wait_time
        fi
done

  2. Use o CloudTrail para identificar a origem do alto volume de solicitações.

    
aws logs filter-log-events \
    --log-group-name CloudTrail/S3BatchOperations \
    --filter-pattern "{ $.eventName = CreateJob || $.eventName = DescribeJob }" \
    --start-time timestamp \
    --query 'events[*].[eventTime,sourceIPAddress,userIdentity.type,eventName]'

  3. Analise a frequência das sondagens.

    1. Evite verificar o status de trabalhos ativos mais de uma vez a cada 30 segundos.

    2. Quando possível, use notificações de conclusão de trabalho em vez de sondagens.

    3. Implemente oscilações em seus intervalos de sondagem para evitar solicitações sincronizadas.

  4. Otimize os padrões de uso da API.

    1. Realize várias operações em lote quando possível.

    2. Use ListJobs para obter o status de vários trabalhos em uma chamada.

    3. Armazene em cache as informações do trabalho para reduzir chamadas de API redundantes.

    4. Distribua a criação de trabalhos ao longo do tempo em vez de criar muitos trabalhos simultaneamente.

  5. Use as métricas do CloudWatch para chamadas de API para monitorar seus padrões de solicitação.

    
   aws logs put-metric-filter \
       --log-group-name CloudTrail/S3BatchOperations \
       --filter-name S3BatchOpsAPICallCount \      
       --filter-pattern "{ $.eventSource = s3.amazonaws.com && $.eventName = CreateJob }" \
       --metric-transformations \        
       metricName=S3BatchOpsAPICalls,metricNamespace=Custom/S3BatchOps,metricValue=1

InvalidManifestContent

Tipo: falha no trabalho.

A exceção InvalidManifestContent ocorre quando há problemas com o formato, o conteúdo ou a estrutura do arquivo de manifesto impedem que o recurso Operações em Lote do S3 processe o trabalho. As causas costumam ser as seguintes:

  1. Violações de formato: colunas obrigatórias ausentes, delimitadores incorretos ou estrutura de CSV malformada.

  2. Problemas de codificação de conteúdo: codificação de caracteres incorreta, marcadores BOM ou caracteres não UTF-8.

  3. Problemas de chave de objeto: caracteres inválidos, codificação de URL incorreta ou chaves que excedem os limites de tamanho.

  4. Limitações de tamanho: o manifesto contém mais objetos do que a operação permite.

  5. Erros de formato de ID de versão: IDs de versão inválidos ou incorretos para objetos versionados.

  6. Problemas com o formato de ETag: formato de ETag incorreto ou aspas ausentes para operações que exigem ETags.

  7. Dados inconsistentes: formatos mistos no mesmo manifesto ou contagens de colunas inconsistentes.

Mensagens de erro relacionadas:

  1. Required fields are missing in the schema: + missingFields

  2. Invalid Manifest Content

  3. The S3 Batch Operations job failed because it contains more keys than the maximum allowed in a single job

  4. Invalid object key format

  5. Manifest file is not properly formatted

  6. Invalid version ID format

  7. ETag format is invalid

Práticas recomendadas para evitar falhas de trabalho InvalidManifestContent

  1. Valide antes do upload: teste o formato do manifesto com pequenos trabalhos antes de processar grandes conjuntos de dados.

  2. Use codificação consistente: sempre use a codificação UTF-8 sem BOM para arquivos de manifesto.

  3. Implemente padrões de geração de manifestos: crie modelos e procedimentos de validação para a criação de manifestos.

  4. Manipule caracteres especiais adequadamente: codifique em URL as chaves de objeto que contêm caracteres especiais.

  5. Monitore a contagem de objetos: acompanhe o tamanho do manifesto e divida trabalhos grandes de forma proativa.

  6. Valide a existência do objeto: verifique se os objetos de fato existem antes de incluí-los nos manifestos.

  7. Use ferramentas da AWS para geração de manifestos: utilize a s3api list-objects-v2 da AWS CLI para gerar listas de objetos formatadas corretamente.

Problemas comuns de manifesto e soluções:

  1. Colunas obrigatórias ausentes: seu manifesto deve incluir todas as colunas obrigatórias para seu tipo de operação. As colunas ausentes mais comuns são “Bucket” e “Chave”.

  2. Formato CSV incorreto: use vírgulas como delimitadores, garanta contagens de colunas consistentes em todas as linhas e evite quebras de linha incorporadas nos campos.

  3. Caracteres especiais em chaves de objeto: codifique em URL chaves de objeto que contêm espaços, caracteres Unicode ou caracteres especiais XML (<, >, &, ", ').

  4. Arquivos de manifesto grandes: divida os manifestos que ultrapassarem o limite de operação em vários manifestos menores e crie trabalhos separados.

  5. IDs de versão inválidos: os IDs de versão devem ser strings alfanuméricas formatadas corretamente. Remova a coluna de “ID da versão” se ela não for necessária.

  6. Problemas de codificação: salve os arquivos de manifesto como UTF-8 sem BOM. Evite copiar manifestos por meio de sistemas que possam alterar a codificação.

Para ver especificações e exemplos detalhados em formato de manifesto, consulte o seguinte:

  1. Especificar um manifesto

  2. Operações suportadas pelo S3 Batch Operations

  3. Nomear objetos do Amazon S3

Solução de problemas de InvalidManifestContent

  1. Baixe o arquivo de manifesto e inspecione-o. Verifique manualmente se o manifesto atende aos requisitos de formato:

    1. Formato CSV delimitado por vírgula.

    2. Codificação de caracteres UTF-8 sem BOM.

    3. Número consistente de colunas em todas as linhas.

    4. Nenhuma linha vazia ou espaço à direita.

    5. Chaves de objeto codificadas corretamente em URL se contiverem caracteres especiais.

    Use o comando a seguir para baixar o arquivo do manifesto.

    
aws s3 cp s3://amzn-s3-demo-bucket1/manifest-key ./manifest.csv

  2. Marque as colunas necessárias para sua operação:

    1. Todas as operações: Bucket e Key.

    2. Operações de cópia: VersionId (opcional).

    3. Operações de restauração: VersionId (opcional).

    4. Operações de substituição de tag: não são necessárias colunas adicionais.

    5. Operações de substituição de ACL: não são necessárias colunas adicionais.

    6. Iniciar restauração: VersionId (opcional).

  3. Marque os limites de contagem de objeto:

    1. Cópia: no máximo 1 bilhão de objetos.

    2. Exclusão: no máximo 1 bilhão de objetos.

    3. Restauração: no máximo 1 bilhão de objetos.

    4. Marcação: no máximo 1 bilhão de objetos.

    5. ACL: no máximo 1 bilhão de objetos.

  4. Crie um manifesto de teste com alguns objetos do seu manifesto original.

  5. Use o comando a seguir para verificar se existe uma amostra de objetos do manifesto.

    
aws s3 ls s3://amzn-s3-demo-bucket1/object-key

  6. Verifique os detalhes da falha do trabalho e analise o motivo da falha e quaisquer detalhes específicos do erro na descrição do trabalho.

    
aws s3control describe-job --account-id 111122223333 --job-id job-id