Risoluzione dei problemi relativi a Operazioni in batch S3 - Amazon Simple Storage Service
NoSuchJobExceptionInvalidManifestContent

Risoluzione dei problemi relativi a Operazioni in batch S3

Operazioni in batch Amazon S3 consente di eseguire operazioni in batch su larga scala su oggetti Amazon S3. Questa guida ti aiuta a risolvere i problemi più comuni che potresti riscontrare.

Per risolvere i problemi con S3 Batch Replication, consulta Risoluzione dei problemi nella replica.

Sono disponibili due tipi principali di errori relativi a Operazioni in batch:

  1. Errore dell’API: l’API richiesta (ad esempio CreateJob) non è stata eseguita.

  2. Errore del processo: la richiesta API iniziale è stata completata ma il processo non è riuscito, ad esempio, a causa di problemi con il manifesto o le autorizzazioni agli oggetti specificati nel manifesto.

NoSuchJobException

Tipo: errore dell’API

NoSuchJobException si verifica quando Operazioni in batch S3 non riesce a individuare il processo specificato. Questo errore può verificarsi in diversi scenari oltre la semplice scadenza del processo. Le cause più comuni sono descritte di seguito.

  1. Scadenza del processo: i processi vengono eliminati automaticamente 90 giorni dopo aver raggiunto lo stato terminale (Complete, Cancelled o Failed).

  2. ID del processo errato: l’ID del processo utilizzato in DescribeJob o UpdateJobStatus non corrisponde all’ID restituito daCreateJob.

  3. Regione errata: tentativo di accedere a un processo in una Regione diversa da quella in cui è stato creato.

  4. Account errato: utilizzo di un ID del processo di un account AWS diverso.

  5. Errori di formato dell’ID del processo: errori di battitura, caratteri aggiuntivi o formattazione errata nell’ID del processo.

  6. Problemi relativi alla tempistica: verifica dello stato del processo subito dopo la creazione, prima che il processo sia completamente registrato.

I messaggi di errore correlati sono descritti di seguito.

  1. No such job

  2. The specified job does not exist

Best practice per prevenire errori delle API NoSuchJobException

  1. Archivia immediatamente gli ID del processo: salva l’ID del processo dalla risposta CreateJob prima di effettuare le chiamate API successive.

  2. Implementa la logica dei tentativi: aggiungi un backoff esponenziale quando controlli lo stato del processo subito dopo la creazione.

  3. Configura il monitoraggio: crea allarmi CloudWatch per monitorare il completamento del processo prima della scadenza dei 90 giorni. Per i dettagli, consulta Utilizzo degli allarmi Amazon CloudWatch nella Guida per l’utente di Amazon CloudWatch.

  4. Utilizza Regioni coerenti: assicurati che tutte le operazioni del processo utilizzino la stessa Regione per la creazione del processo.

  5. Convalida l’input: controlla il formato dell’ID del processo prima di effettuare chiamate API.

Scadenza dei processi

I processi nello stato terminale vengono eliminati automaticamente dopo 90 giorni. Per evitare di perdere informazioni del processo, considera quanto segue.

  1. Scarica i report di completamento prima della scadenza: per istruzioni su come recuperare e archiviare i risultati del processo, consulta .

  2. Archivia i metadati del processo nei tuoi sistemi: archivia le informazioni critiche del processo nei database o nei sistemi di monitoraggio.

  3. Imposta notifiche automatizzate prima della scadenza di 90 giorni: utilizza Amazon EventBridge per creare regole che attivano le notifiche al completamento del processo. Per ulteriori informazioni, consulta Notifiche di eventi Amazon S3.

NoSuchJobExceptionRisoluzione dei problemi di

  1. Utilizza il comando seguente per verificare che il processo sia presente nell’account e nella Regione.

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

  2. Utilizza il seguente comando per cercare tutti gli stati del processo. I possibili stati del processo sono 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. Utilizza il comando seguente per verificare se il processo è presente in altre Regioni in cui di solito si creano processi.

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

  4. Convalida il formato dell’ID del processo. Gli ID del processo in genere contengono 36 caratteri, ad esempio 12345678-1234-1234-1234-123456789012. Verifica la presenza di spazi aggiuntivi, caratteri mancanti o problemi di distinzione tra maiuscole e minuscole e verifica di utilizzare l’ID del processo completo restituito dal comando CreateJob.

  5. Utilizza il comando seguente per verificare la presenza di eventi di creazione di processi nei log di CloudTrail.

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

AccessDeniedException

Tipo: errore dell’API

AccessDeniedException si verifica quando una richiesta di Operazioni in batch S3 viene bloccata a causa di autorizzazioni insufficienti, operazioni non supportate o restrizioni delle policy. Questo è uno degli errori più comuni in Operazioni in batch. Le cause comuni sono le seguenti:

  1. Autorizzazioni IAM mancanti: l’identità IAM non dispone delle autorizzazioni necessarie per le API di Operazioni in batch.

  2. Autorizzazioni S3 insufficienti: autorizzazioni mancanti per accedere ai bucket di origine o destinazione e agli oggetti.

  3. Problemi relativi al ruolo di esecuzione del processo: il ruolo di esecuzione del processo non dispone delle autorizzazioni per eseguire l’operazione specificata.

  4. Operazioni non supportate: tentativo di utilizzare operazioni non supportate nella Regione o nel tipo di bucket correnti.

  5. Problemi di accesso multi-account: autorizzazioni mancanti per l’accesso multi-account a bucket o oggetti.

  6. Restrizioni delle policy basate sulle risorse: policy di bucket o ACL degli oggetti bloccano l’operazione.

  7. Restrizioni delle policy di controllo dei servizi: policy a livello di organizzazione impediscono l’operazione.

Messaggi di errore correlati:

  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

Best practice per prevenire errori delle API AccessDeniedException

  1. Utilizza il principio del privilegio minimo: concedi solo le autorizzazioni minime richieste per le operazioni specifiche.

  2. Verifica le autorizzazioni prima di eseguire processi di grandi dimensioni: esegui piccoli processi di test per convalidare le autorizzazioni prima di elaborare migliaia di oggetti.

  3. Utilizza il simulatore di policy IAM: testa le policy prima dell’implementazione utilizzando il simulatore di policy IAM. Per ulteriori informazioni, consulta Test delle policy IAM con il simulatore di policy IAM nella Guida per l’utente IAM.

  4. Implementa una corretta configurazione multi-account: controlla la configurazione dell’accesso multi-account per le configurazioni dei processi multi-account. Per ulteriori informazioni, consulta Tutorial IAM: delega dell’accesso tra account AWS tramite i ruoli IAM nella Guida per l’utente IAM.

  5. Monitora le modifiche alle autorizzazioni: configura gli avvisi CloudTrail per le modifiche alle policy IAM che potrebbero influire su Operazioni in batch.

  6. Documenta i requisiti dei ruoli: mantieni una documentazione chiara delle autorizzazioni richieste per ogni tipo di processo.

  7. Utilizza modelli di autorizzazione comuni: utilizza gli esempi di autorizzazione e i modelli di policy:

    1. Concessione di autorizzazioni per le operazioni in batch

    2. Risorse multi-account in IAM nella Guida per l’utente IAM.

    3. Controllo dell’accesso agli endpoint VPC utilizzando le policy degli endpoint nella Guida di AWS PrivateLink.

Risoluzione dei problemi relativi ad AccessDeniedException

Segui sistematicamente queste fasi per identificare e risolvere i problemi di autorizzazione.

  1. Consulta Operazioni supportate dalle operazioni in batch S3 per le operazioni supportate per Regione. Verifica che le operazioni del bucket di directory siano disponibili solo negli endpoint regionali e zonali. Verifica che l’operazione sia supportata per la classe di archiviazione del bucket.

  2. Utilizza il seguente comando per determinare se puoi elencare i processi.

    
 aws s3control list-jobs --account-id 111122223333

  3. Utilizza il comando seguente per verificare le autorizzazioni IAM per l’identità richiedente. L’account che esegue il processo richiede le seguenti autorizzazioni: s3:CreateJob, s3:DescribeJob, s3:ListJobs-s3:UpdateJobPriority, s3:UpdateJobStatus-iam:PassRole.

    
aws sts get-caller-identity 111122223333

  4. Utilizza il comando seguente per verificare che il ruolo sia presente e utilizzabile.

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

  5. Utilizza il comando seguente per esaminare la policy di attendibilità del ruolo. Il ruolo che esegue il processo deve disporre di:

    1. Una relazione di attendibilità che consente a batchoperations.s3.amazonaws.com di assumere il ruolo.

    2. Le operazioni eseguite da Operazioni in batch (ad esempio s3:PutObjectTagging per le operazioni di tagging).

    3. Accesso ai bucket di origine e di destinazione.

    4. Autorizzazione a leggere il file manifesto.

    5. Autorizzazione a scrivere report di completamento.

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

  6. Utilizza il comando seguente per testare l’accesso ai bucket di origine e al manifesto.

    
aws s3 ls s3://bucket-name

  7. Testa l’operazione eseguita da Operazioni in batch. Ad esempio, se Operazioni in batch esegue il tagging, applica un tag a un oggetto di esempio nel bucket di origine.

  8. Esamina le policy di bucket per individuare quelle che potrebbero negare l’operazione.

    1. Controlla le ACL degli oggetti se utilizzi controlli degli accessi legacy.

    2. Verifica che nessuna policy di controllo dei servizi blocchi l’operazione.

    3. Verifica che le policy degli endpoint VPC consentano Operazioni in batch se si utilizzano endpoint VPC.

  9. Utilizza il comando seguente per utilizzare CloudTrail per identificare gli errori di autorizzazione.

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

SlowDownError

Tipo: errore dell’API

L’eccezione SlowDownError si verifica quando l’account ha superato il limite di velocità delle richieste per le API di Operazioni in batch S3. Questo è un meccanismo di limitazione (della larghezza di banda della rete) per proteggere il servizio dal sovraccarico dovuto a troppe richieste. Le cause comuni sono le seguenti:

  1. Elevata frequenza di richieste API: troppe chiamate API in un breve periodo di tempo.

  2. Operazioni sul processo simultanee: più applicazioni o utenti creano e gestiscono processi contemporaneamente.

  3. Script automatizzati senza limiti di velocità: script che non implementano strategie di backoff adeguate.

  4. Polling troppo frequenti dello stato del processo: verifica dello stato del processo eseguita più spesso del necessario.

  5. Modelli di traffico aumentato: picchi improvvisi nell’utilizzo delle API durante i periodi di elaborazione di punta.

  6. Limiti di capacità regionale: superamento della capacità di richiesta allocata per la Regione.

Messaggi di errore correlati:

  1. SlowDown

  2. Please reduce your request rate

  3. Request rate exceeded

Best practice per prevenire errori delle API SlowDownError

  1. Implementa la limitazione della velocità sul lato client: aggiungi ritardi tra le chiamate API nelle applicazioni.

  2. Utilizza il backoff esponenziale con jitter: applica la randomizzazione dei ritardi dei tentativi per evitare problemi di thundering herd.

  3. Imposta una logica dei tentativi adeguata: implementa tentativi automatici con ritardi crescenti per gli errori transitori.

  4. Utilizza architetture basate sugli eventi: sostituisci il polling con le notifiche EventBridge per le modifiche allo stato del processo.

  5. Distribuisci il carico nel tempo: organizza la creazione di processi e i controlli dello stato in diversi periodi di tempo.

  6. Monitora e avvisa ai limiti di velocità: configura gli allarmi CloudWatch per rilevare quando ti stai avvicinando ai limiti.

La maggior parte degli AWS SDK include una logica dei tentativi integrata per gli errori di limitazione della velocità. Configurali come segue:

  1. AWS CLI: utilizza i parametri cli-read-timeout e cli-connect-timeout.

  2. AWS SDK per Python (Boto3): configura le modalità dei tentativi e il numero massimo di tentativi nella configurazione del client.

  3. AWS SDK per Java: utilizza le impostazioni RetryPolicy e ClientConfiguration.

  4. AWS SDK per JavaScript: configura maxRetries e retryDelayOptions.

Per ulteriori informazioni sui modelli dei tentativi e sulle best practice, consulta Nuovo tentativo con schema di backoff nel Prontuario AWS.

Risoluzione dei problemi relativi a SlowDownError

  1. Nel codice, implementa immediatamente il backoff esponenziale.

    Esempio di backoff esponenziale in 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. Utilizza CloudTrail per identificare l’origine dell’elevato volume di richieste.

    
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. Verifica la frequenza di polling.

    1. Evita di controllare lo stato del processo più di una volta ogni 30 secondi per i processi attivi.

    2. Se possibile, utilizza le notifiche di completamento del processo anziché il polling.

    3. Implementa jitter negli intervalli di polling per evitare richieste sincronizzate.

  4. Ottimizza i modelli di utilizzo delle API.

    1. Se possibile, esegui più operazioni in batch.

    2. Utilizza ListJobs per ottenere lo stato di più processi in una sola chiamata.

    3. Memorizza nella cache le informazioni sui processi per ridurre le chiamate API ridondanti.

    4. Suddividi la creazione dei processi nel tempo anziché crearne molti contemporaneamente.

  5. Utilizza le metriche CloudWatch per le chiamate API per monitorare i modelli di richiesta.

    
   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: errore del processo

L’eccezione InvalidManifestContent si verifica quando ci sono problemi con il formato, il contenuto o la struttura del file manifesto che impediscono a Operazioni in batch S3 di elaborare il processo. Le cause comuni sono le seguenti:

  1. Violazioni del formato: colonne obbligatorie mancanti, delimitatori errati o struttura CSV non valida.

  2. Problemi di codifica del contenuto: codifica errata dei caratteri, indicatori BOM o caratteri non UTF-8.

  3. Problemi con le chiavi dell’oggetto: caratteri non validi, codifica URL non corretta o chiavi che superano i limiti di lunghezza.

  4. Limiti relativi alle dimensioni: il manifesto contiene più oggetti di quelli supportati dall’operazione.

  5. Errori di formato dell’ID della versione: ID della versione non validi o non corretti per gli oggetti con controllo delle versioni.

  6. Problemi relativi al formato di ETag: formato di ETag errato o virgolette mancanti per le operazioni che richiedono ETag.

  7. Dati incoerenti: formati misti all’interno dello stesso manifesto o numero di colonne non coerente.

Messaggi di errore correlati:

  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

Best practice per prevenire gli errori dei processi InvalidManifestContent

  1. Convalida prima del caricamento: testa il formato del manifesto con piccoli processi prima di elaborare set di dati di grandi dimensioni.

  2. Utilizza una codifica coerente: utilizza sempre la codifica UTF-8 senza BOM per i file manifesto.

  3. Implementa gli standard di generazione dei manifesti: crea modelli e procedure di convalida per la creazione di manifesti.

  4. Gestisci correttamente i caratteri speciali: gli URL codificano le chiavi degli oggetti che contengono caratteri speciali.

  5. Monitora il numero di oggetti: monitora le dimensioni del manifesto e suddividi i lavori di grandi dimensioni in modo proattivo.

  6. Convalida la presenza degli oggetti: verifica la presenza degli oggetti prima di includerli nei manifesti.

  7. Utilizza strumenti AWS per la generazione di manifesti: utilizza AWS CLI s3api list-objects-v2 per generare elenchi di oggetti formattati correttamente.

Problemi e soluzioni comuni relativi ai manifesti:

  1. Colonne obbligatorie mancanti: assicurati che il manifesto includa tutte le colonne obbligatorie per il tipo di operazione. Le colonne mancanti più comuni sono Bucket e Chiave.

  2. Formato CSV non corretto: utilizza le virgole come delimitatori, assicura un numero di colonne uniforme su tutte le righe ed evita gli embedding delle interruzioni di riga nei campi.

  3. Caratteri speciali nelle chiavi degli oggetti: gli URL codificano le chiavi degli oggetti che contengono spazi, caratteri Unicode o caratteri speciali XML (<, >, &, ", ').

  4. File manifesti di grandi dimensioni: suddividi i manifesti con un numero di operazioni superiore al limite in diversi manifesti più piccoli e crea processi separati.

  5. ID della versione non validi: assicurati che gli ID della versione siano stringhe alfanumeriche formattate correttamente. Rimuovi la colonna ID della versione se non è necessaria.

  6. Problemi di codifica: salva i file manifesto come UTF-8 senza BOM. Evita di copiare i manifesti attraverso sistemi che potrebbero alterare la codifica.

Per le specifiche dettagliate e gli esempi relativi al formato del manifesto, consulta quanto segue:

  1. Specifica di un manifest

  2. Operazioni supportate dalle operazioni in batch S3

  3. Denominazione di oggetti Amazon S3

Risoluzione dei problemi relativi a InvalidManifestContent

  1. Scarica e controlla il file manifesto. Verifica manualmente che il manifesto soddisfi i requisiti di formato:

    1. Formato CSV con virgola come delimitatore.

    2. Codifica UTF-8 senza BOM.

    3. Numero coerente di colonne per tutte le righe.

    4. Senza righe vuote o spazi finali.

    5. Le chiavi dell’oggetto sono codificate correttamente nell’URL se contengono caratteri speciali.

    Utilizza il seguente comando per scaricare il file manifesto.

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

  2. Controlla le colonne obbligatorie per l’operazione:

    1. Tutte le operazioni: Bucket, Key

    2. Operazioni di copia: VersionId (facoltativo)

    3. Operazioni di ripristino: VersionId (facoltativo)

    4. Operazioni di sostituzione di tag: non sono necessarie colonne aggiuntive.

    5. Operazioni di sostituzione di ACL: non sono necessarie colonne aggiuntive.

    6. Avvia ripristino: VersionId (facoltativo)

  3. Controlla i limiti del numero di oggetti:

    1. Copia: massimo 1 miliardo di oggetti.

    2. Eliminazione: massimo 1 miliardo di oggetti.

    3. Ripristino: massimo 1 miliardo di oggetti.

    4. Tagging: massimo 1 miliardo di oggetti.

    5. ACL: massimo 1 miliardo di oggetti.

  4. Crea un manifesto di test con alcuni oggetti del manifesto originale.

  5. Utilizza il seguente comando per verificare se esiste un esempio di oggetti del manifesto.

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

  6. Controlla i dettagli dell’errore del processo e verifica il motivo ed eventuali dettagli specifici dell’errore nella descrizione del processo.

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