Fehlerbehebung bei S3-Batch-Operationen
Mit Amazon S3 Batch Operations können Sie umfangreiche Operationen an Amazon S3-Objekten durchführen. Dieser Leitfaden hilft Ihnen bei der Behebung häufiger Probleme, die auftreten können.
Informationen zur Behebung von Problemen mit S3 Batch Replication finden Sie unter Fehlerbehebung bei einer Replikation.
Es gibt zwei Haupttypen von Fehlern, die zu Fehlern im Batch-Betrieb führen:
-
API-Fehler – Die angeforderte API (z. B.
CreateJob) konnte nicht ausgeführt werden. -
Auftragsfehler – Die erste API-Anfrage war erfolgreich, aber der Job schlug fehl, z. B. aufgrund von Problemen mit dem Manifest oder den Berechtigungen für Objekte, die im Manifest angegeben sind.
NoSuchJobException
Typ: API-Fehler
Die Meldung NoSuchJobException tritt auf, wenn S3 Batch Operations den angegebenen Auftrag nicht finden kann. Dieser Fehler kann in verschiedenen Szenarien auftreten, die über den einfachen Ablauf eines Auftrags hinausgehen. Zu den häufigsten Ursachen gehören folgende.
Ablauf eines Jobs – Jobs werden 90 Tage nach Erreichen eines Endstatus (
Complete,CancelledoderFailed) automatisch gelöscht.Falsche Job-ID – Die in der Job-ID verwendete Job-ID
DescribeJoboder stimmtUpdateJobStatusnicht mit der vonCreateJobzurückgegebenen ID überein.Falsche Region – Es wird versucht, auf einen Job zuzugreifen, der sich in einer anderen Region befindet als der, in der er erstellt wurde.
Falsches Konto – Es wird eine Job-ID von einem anderen AWS-Konto verwendet.
Formatfehler bei der Job-ID – Tippfehler, zusätzliche Zeichen oder falsche Formatierung in der Job-ID.
Zeitliche Probleme – Der Jobstatus wird unmittelbar nach der Erstellung überprüft, bevor der Job vollständig registriert ist.
Zu den damit verbundenen Fehlermeldungen gehören die folgenden.
No such jobThe specified job does not exist
Bewährte Verfahren zur Vermeidung von NoSuchJobException API-Fehlern
Job-IDs sofort speichern – Speichern Sie die Job-ID aus der
CreateJobAntwort, bevor Sie nachfolgende API-Aufrufe durchführen.Implementieren Sie die Wiederholungslogik – Fügen Sie exponentiellen Backoff hinzu, wenn Sie den Jobstatus unmittelbar nach der Erstellung überprüfen.
Überwachung einrichten – Erstellen Sie CloudWatch-Alarme, um den Abschluss von Aufträgen vor Ablauf von 90 Tagen zu verfolgen. Weitere Informationen finden Sie unter Verwendung von CloudWatch-Alarmen im Amazon-CloudWatch-Benutzerhandbuch.
Verwenden Sie einheitliche Regionen – Stellen Sie sicher, dass für alle Auftragsvorgänge dieselbe Region für die Auftragserstellung verwendet wird.
Eingabe validieren – Überprüfen Sie das Format der Job-ID, bevor Sie API-Aufrufe tätigen.
Wenn Aufträge auslaufen
Aufträge im Terminal-Status werden nach 90 Tagen automatisch gelöscht. Um den Verlust von Stelleninformationen zu vermeiden, sollten Sie Folgendes beachten.
Abschlussberichte vor Ablauf herunterladen – Anweisungen zum Abrufen und Speichern von Auftragsergebnissen finden Sie unter .
Archivieren Sie Auftragsmetadaten in Ihren eigenen Systemen – Speichern Sie wichtige Auftragsinformationen in Ihren Datenbanken oder Überwachungssystemen.
Automatische Benachrichtigungen vor Ablauf der Frist von 90 Tagen einrichten – Verwenden Sie Amazon EventBridge, um Regeln zu erstellen, die Benachrichtigungen auslösen, wenn Jobs abgeschlossen sind. Weitere Informationen finden Sie unter Amazon-S3-Ereignisbenachrichtigungen.
NoSuchJobExceptionFehlerbehebung für
Verwenden Sie den folgenden Befehl, um zu überprüfen, ob der Auftrag in Ihrem Konto und Ihrer Region existiert.
aws s3control list-jobs --account-id111122223333--regionus-east-1Verwenden Sie den folgenden Befehl, um alle Job-Status zu durchsuchen. Mögliche Jobstatus sind
Active,Cancelled,Cancelling,Complete,Completing,Failed,Failing,New,Paused,Pausing,Preparing,ReadyundSuspended.aws s3control list-jobs --account-id111122223333--job-statusesyour-job-statusVerwenden Sie den folgenden Befehl, um zu prüfen, ob der Auftrag in anderen Regionen existiert, in denen Sie üblicherweise Aufträge erstellen.
aws s3control list-jobs --account-id111122223333--regionjob-region-1aws s3control list-jobs --account-id111122223333--regionjob-region-2-
Überprüfen Sie das Format der Auftragskennung. Job-IDs enthalten in der Regel 36 Zeichen, z. B.
12345678-1234-1234-1234-123456789012. Überprüfen Sie auf zusätzliche Umgebungen, fehlende Zeichen oder Probleme mit der Groß- und Kleinschreibung und stellen Sie sicher, dass Sie die vollständige Auftragskennung verwenden, die vom BefehlCreateJobzurückgegeben wird. -
Verwenden Sie den folgenden Befehl, um die CloudTrail-Protokolle auf Ereignisse zur Auftragserstellung zu überprüfen.
aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \ --filter-pattern "{ $.eventName = CreateJob }" \ --start-timetimestamp
AccessDeniedException
Typ: API-Fehler
Diese AccessDeniedException tritt auf, wenn eine S3 Batch Operations-Anforderung aufgrund unzureichender Berechtigungen, nicht unterstützter Vorgänge oder Richtlinieneinschränkungen blockiert wird. Dies ist einer der häufigsten Fehler bei Batch-Operationen. Es hat die folgenden geläufigen Ursachen:
Fehlende IAM-Berechtigungen – Der IAM-Identität fehlen die erforderlichen Berechtigungen für Batch Operations APIs.
Unzureichende S3-Berechtigungen – Fehlende Berechtigungen für den Zugriff auf Quell- oder Ziel-Buckets und Objekte.
Probleme mit der Jobausführungsrolle – Der Jobausführungsrolle fehlen die Berechtigungen zur Ausführung des angegebenen Vorgangs.
Nicht unterstützte Operationen – Es wird versucht, Operationen zu verwenden, die in der aktuellen Region oder dem aktuellen Bucket-Typ nicht unterstützt werden.
Probleme beim kontoübergreifenden Zugriff – Fehlende Berechtigungen für den kontoübergreifenden Bucket- oder Objektzugriff.
Ressourcenbasierte Richtlinieneinschränkungen – Bucket-Richtlinien oder Objekt-ACLs blockieren den Vorgang.
Einschränkungen durch die Service-Kontrollrichtlinie (SCP) – Richtlinien auf Organisationsebene, die den Vorgang verhindern.
Verwandte Fehlermeldungen:
Access DeniedUser: arn:aws:iam::account:user/username is not authorized to perform: s3:operationCross-account pass role is not allowedThe bucket policy does not allow the specified operation
Bewährte Verfahren zur Vermeidung von AccessDeniedException-API-Fehlern
Verwenden Sie das Prinzip der geringsten Berechtigung – Gewähren Sie nur die Mindestberechtigungen, die für Ihre spezifischen Operationen erforderlich sind.
Berechtigungen vor großen Aufträgen testen – Führen Sie kleine Testaufträge aus, um Berechtigungen zu validieren, bevor Sie Tausende von Objekten verarbeiten.
Verwenden Sie den IAM-Richtliniensimulator – Testen Sie Richtlinien vor der Bereitstellung mit dem IAM-Richtliniensimulator. Weitere Informationen finden Sie unter Testen von IAM-Richtlinien mit dem IAM-Richtliniensimulator im IAM-Benutzerhandbuch.
Richten Sie die richtige kontenübergreifende Einrichtung ein – Überprüfen Sie Ihre Konfiguration für den kontoübergreifenden Zugriff auf kontoübergreifende Jobkonfigurationen. Weitere Informationen finden Sie im IAM-Tutorial: Delegieren des Zugriffs in allen AWS-Konten mithilfe von IAM-Rollen im IAM-Benutzerhandbuch.
Berechtigungsänderungen überwachen – Richten Sie CloudTrail-Benachrichtigungen für IAM-Richtlinienänderungen ein, die sich auf Batch Operations auswirken könnten.
Rollenanforderungen dokumentieren – Sorgen Sie für eine klare Dokumentation der erforderlichen Berechtigungen für jeden Jobtyp.
Verwenden Sie gängige Berechtigungsvorlagen – Verwenden Sie die Beispiele für Berechtigungen und Richtlinienvorlagen:
Kontoübergreifende Ressourcen in IAM im IAM-Benutzerhandbuch.
Steuern des Zugriffs auf VPC-Endpunkte mithilfe von Endpunktrichtlinien im AWS PrivateLink-Handbuch.
AccessDeniedException-Fehlerbehebung
Befolgen Sie diese Schritte systematisch, um Probleme mit Berechtigungen zu erkennen und zu lösen.
Prüfen Sie Von S3 Batch Operations unterstützte Vorgänge für unterstützte Operationen nach Region. Bestätigen Sie, dass Verzeichnis-Buckets nur an regionalen und zonalen Endpunkten verfügbar sind. Überprüfen Sie, ob der Vorgang für die Speicherklasse Ihres Buckets unterstützt wird.
Verwenden Sie den folgenden Befehl, um festzustellen, ob Sie Aufträge auflisten können.
aws s3control list-jobs --account-id111122223333Verwenden Sie den folgenden Befehl, um die IAM-Berechtigungen für die anfordernde Identität zu überprüfen. Das Konto, auf dem der Job ausgeführt wird, benötigt die folgenden Berechtigungen:
s3:CreateJob,s3:DescribeJob,s3:ListJobs-s3:UpdateJobPriority,s3:UpdateJobStatus-iam:PassRole.aws sts get-caller-identity111122223333Verwenden Sie den folgenden Befehl, um zu prüfen, ob die Rolle existiert und übernommen werden kann.
aws iam get-role --role-namerole-name-
Verwenden Sie den folgenden Befehl, um die Vertrauensrichtlinie der Rolle zu überprüfen. Die Person, die die Stelle ausübt, muss über die folgenden Eigenschaften verfügen:
Eine Vertrauensbeziehung, die es
batchoperations.s3.amazonaws.comermöglicht, die Rolle zu übernehmen.Die Operationen, die der Batch-Vorgang ausführt (z. B.
s3:PutObjectTaggingbei Tagging-Vorgängen).Zugriff auf die Quell- und Ziel-Buckets.
Berechtigung zum Lesen der Manifest-Datei.
Berechtigung, Abschlussberichte zu schreiben.
aws iam get-role --role-namerole-name--query 'Role.AssumeRolePolicyDocument' Verwenden Sie den folgenden Befehl, um den Zugriff auf das Manifest und die Source Buckets wiederherzustellen.
aws s3 ls s3://bucket-name-
Testen Sie den Vorgang, der von der Stapelverarbeitung durchgeführt wird. Wenn der Stapelvorgang beispielsweise eine Markierung vornimmt, markieren Sie ein Musterobjekt im Quell-Bucket.
Überprüfen Sie Bucket-Richtlinien auf Richtlinien, die den Vorgang verweigern könnten.
Prüfen Sie Objekt-ACLs, wenn Sie mit älteren Zugriffskontrollen arbeiten.
Stellen Sie sicher, dass keine Service-Kontrollrichtlinien (SCPs) den Vorgang blockieren.
Bestätigen Sie, dass VPC-Endpunktrichtlinien Batch-Operationen zulassen, wenn Sie VPC-Endpunkte verwenden.
Verwenden Sie den folgenden Befehl, um CloudTrail zur Ermittlung von Berechtigungsfehlern zu verwenden.
aws logs filter-log-events --log-group-name CloudTrail/S3BatchOperations \ --filter-pattern "{ $.errorCode = AccessDenied }" \ --start-timetimestamp
SlowDownError
Typ: API-Fehler
Die Ausnahme SlowDownError tritt auf, wenn Ihr Konto die Anforderungsratengrenze für S3 Batch Operations APIs überschritten hat. Dies ist ein Mechanismus zur Drosselung, um den Dienst vor einer Überlastung durch zu viele Anfragen zu schützen. Es hat die folgenden geläufigen Ursachen:
Hohe API-Anforderungshäufigkeit – Zu viele API-Aufrufe in einem kurzen Zeitraum.
Gleichzeitige Auftragsvorgänge – Mehrere Anwendungen oder Benutzer erstellen/verwalten Jobs gleichzeitig.
Automatisierte Skripts ohne Ratenbegrenzung – Skripte, die keine geeigneten Backoff-Strategien implementieren.
Zu häufiges Abfragen des Jobstatus – Der Jobstatus wird häufiger als nötig überprüft.
Burst-Traffic-Muster – Plötzliche Spitzenwerte bei der API-Nutzung zu Spitzenzeiten.
Regionale Kapazitätsgrenzen – Überschreitung der zugewiesenen Anforderungskapazität für Ihre Region.
Verwandte Fehlermeldungen:
SlowDownPlease reduce your request rateRequest rate exceeded
Bewährte Verfahren zur Vermeidung von SlowDownError-API-Fehlern
Implementieren Sie eine clientseitige Ratenbegrenzung – Fügen Sie Verzögerungen zwischen API-Aufrufen in Ihren Anwendungen hinzu.
Verwenden Sie exponentielles Backoff mit Jitter – Ordnen Sie Wiederholungsverzögerungen nach dem Zufallsprinzip an, um donnernde Herdenprobleme zu vermeiden.
Richten Sie die richtige Wiederholungslogik ein – Implementieren Sie automatische Wiederholungsversuche mit zunehmender Verzögerung bei vorübergehenden Fehlern.
Verwenden Sie ereignisgesteuerte Architekturen – Ersetzen Sie Polling durch EventBridge-Benachrichtigungen für Jobstatusänderungen.
Verteilung der Arbeitslast über einen bestimmten Zeitraum – Gestaffeln Sie die Auftragserstellung und die Statusprüfungen auf verschiedene Zeiträume.
Überwachung von Ratenlimits und Warnmeldungen – Richten Sie CloudWatch-Alarme ein, um zu erkennen, wenn Sie sich den Grenzwerten nähern.
Die meisten AWS SDKs enthalten eine integrierte Wiederholungslogik für Fehler bei der Ratenbegrenzung. Konfigurieren Sie sie wie folgt:
AWS CLI – Verwendung von
cli-read-timeoutundcli-connect-timeoutParametern.AWS SDK für Python (Boto3) – Konfigurieren Sie Wiederholungsmodi und maximale Versuche in Ihrer Client-Konfiguration.
AWS SDK für Java – Verwendung
RetryPolicyundClientConfigurationEinstellungen.AWS SDK für JavaScript – Konfiguration
maxRetriesundretryDelayOptions.
Weitere Informationen zu Wiederholungsmustern und bewährten Methoden finden Sie unter Wiederholungsversuch mit Backoff-Muster im AWS Prescriptive Guidance.
SlowDownError-Fehlerbehebung
Implementieren Sie in Ihrem Code sofort exponentielles Backoff.
Beispiel des exponentiellen Backoffs in der Bash
for attempt in {1..5}; do if aws s3control describe-job --account-id111122223333--job-idjob-id; then break else wait_time=$((2**attempt)) echo "Rate limited, waiting ${wait_time} seconds..." sleep $wait_time fi done-
Verwenden Sie CloudTrail, um die Quelle eines hohen Anfragevolumens zu ermitteln.
aws logs filter-log-events \ --log-group-name CloudTrail/S3BatchOperations \ --filter-pattern "{ $.eventName = CreateJob || $.eventName = DescribeJob }" \ --start-timetimestamp\ --query 'events[*].[eventTime,sourceIPAddress,userIdentity.type,eventName]' Überprüfung der Abfragefrequenz.
Prüfen Sie den Auftragsstatus aktiver Aufträge nicht öfter als alle 30 Sekunden.
Verwenden Sie, wenn möglich, Benachrichtigungen über den Abschluss eines Auftrags anstelle von Abfragen.
Implementieren Sie Jitter in Ihre Polling-Intervalle, um synchronisierte Anfragen zu vermeiden.
-
Optimieren Sie Ihre API-Nutzungsmuster.
Stapeln Sie mehrere Vorgänge, wenn möglich.
Verwenden Sie
ListJobs, um den Status von mehreren Aufträgen in einem Aufruf zu erhalten.Zwischenspeichern von Auftragsinformationen, um überflüssige API-Aufrufe zu vermeiden.
Verteilen Sie die Schaffung von Arbeitsplätzen über einen längeren Zeitraum, anstatt viele Arbeitsplätze gleichzeitig zu schaffen.
-
Verwenden Sie CloudWatch-Metriken für API-Aufrufe, um Ihre Anfragemuster zu überwachen.
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
Type: Job failure
Die Ausnahme InvalidManifestContent tritt auf, wenn es Probleme mit dem Format, dem Inhalt oder der Struktur der Manifestdatei gibt, die verhindern, dass S3 Batch Operations den Auftrag verarbeitet. Es hat die folgenden geläufigen Ursachen:
Formatverletzungen – Fehlende erforderliche Spalten, falsche Trennzeichen oder fehlerhafte CSV-Struktur.
Probleme mit der Inhaltskodierung – Falsche Zeichenkodierung, STL-Markierungen oder Nicht-UTF-8-Zeichen.
Probleme mit Objektschlüsseln – Ungültige Zeichen, falsche URL-Kodierung oder Schlüssel, die Längenbeschränkungen überschreiten.
Größenbeschränkungen – Das Manifest enthält mehr Objekte, als der Vorgang unterstützt.
Formatfehler bei der Versions-ID – Falsch formatierte oder ungültige Versions-IDs für versionierte Objekte.
Probleme mit dem ETag-Format – Falsches ETag-Format oder fehlende Anführungszeichen für Operationen, die ETags erfordern.
Inkonsistente Daten – Gemischte Formate innerhalb desselben Manifests oder inkonsistente Spaltenanzahl.
Verwandte Fehlermeldungen:
Required fields are missing in the schema: + missingFieldsInvalid Manifest ContentThe S3 Batch Operations job failed because it contains more keys than the maximum allowed in a single jobInvalid object key formatManifest file is not properly formattedInvalid version ID formatETag format is invalid
Bewährte Verfahren zur Vermeidung von InvalidManifestContent-Auftragsfehlern
Vor dem Upload überprüfen – Testen Sie das Manifestformat mit kleinen Aufträgen, bevor Sie große Datensätze verarbeiten.
Konsistente Kodierung verwenden – Verwenden Sie für Manifestdateien immer die UTF-8-Kodierung ohne BOM.
Implementieren Sie Standards für die Manifestgenerierung – Erstellen Sie Vorlagen und Validierungsverfahren für die Manifesterstellung.
Sonderzeichen richtig handhaben – Objekt-Schlüssel, die Sonderzeichen haben, mit URL-Kodierung versehen.
Objektanzahl überwachen – Verfolgen Sie die Größe des Manifests und teilen Sie große Jobs proaktiv auf.
Existenz von Objekten überprüfen – Stellen Sie sicher, dass Objekte existieren, bevor Sie sie in Manifeste aufnehmen.
AWS Tools für die Manifestgenerierung verwenden – Nutzen von AWS CLI
s3api list-objects-v2, um ordnungsgemäß formatierte Objektlisten zu generieren.
Häufige Probleme mit Manifesten und Lösungen:
Fehlende erforderliche Spalten – Stellen Sie sicher, dass Ihr Manifest alle erforderlichen Spalten für Ihren Operationstyp enthält. Die am häufigsten fehlenden Spalten sind Bucket und Key.
Falsches CSV-Format – Verwenden Sie Kommatrennzeichen, sorgen Sie für eine einheitliche Spaltenanzahl in allen Zeilen und vermeiden Sie eingebettete Zeilenumbrüche innerhalb von Feldern.
Sonderzeichen in Objektschlüsseln – URL-kodieren Objektschlüssel, die Leerzeichen, Unicode-Zeichen oder XML-Sonderzeichen (<, >, &, „, ') enthalten.
Große Manifestdateien – Teilen Sie Manifeste mit mehr als dem Operationslimit in mehrere kleinere Manifeste auf und erstellen Sie separate Jobs.
Ungültige Versions-IDs – Stellen Sie sicher, dass es sich bei den Versions-IDs um richtig formatierte alphanumerische Zeichenketten handelt. Entfernen Sie die Versions-ID-Spalte, wenn sie nicht benötigt wird.
Probleme mit der Kodierung – Speichern Sie Manifestdateien als UTF-8 ohne BOM. Vermeiden Sie das Kopieren von Manifesten über Systeme, die die Kodierung verändern könnten.
Ausführliche Angaben zum Format des Manifests und Beispiele finden Sie im Folgenden:
InvalidManifestContent-Fehlerbehebung
Laden Sie die Manifest-Datei herunter und prüfen Sie sie. Überprüfen Sie manuell, ob das Manifest den Formatanforderungen entspricht:
CSV-Format mit Komma-Begrenzungszeichen.
UTF-8-Kodierung ohne BOM.
Konsistente Anzahl von Spalten in allen Zeilen.
Keine Leerzeilen oder nachgestellte Umgebungen.
Objektschlüssel werden korrekt URL-kodiert, wenn sie Sonderzeichen enthalten.
Verwenden Sie den folgenden Befehl, um die Manifest-Datei herunterzuladen.
aws s3 cp s3://amzn-s3-demo-bucket1/manifest-key./manifest.csv-
Überprüfen Sie die für Ihr Vorhaben erforderlichen Spalten:
Alle Vorgänge:
Bucket,KeyKopiervorgänge:
VersionId(fakultativ)Wiederherstellungsvorgänge:
VersionId(fakultativ)Ersetzen von Tag-Operationen: Keine zusätzlichen Spalten erforderlich.
Ersetzen Sie ACL-Operationen: Keine zusätzlichen Spalten erforderlich.
Wiederherstellung einleiten:
VersionId(optional)
-
Prüfen Sie die Grenzen der Objektanzahl:
Kopieren: Maximal 1 Milliarde Objekte.
Löschen: Maximal 1 Milliarde Objekte.
Wiederherstellen: Maximal 1 Milliarde Objekte.
Kennzeichnung: maximal 1 Milliarde Objekte.
ACL: maximal 1 Milliarde Objekte.
-
Erstellen Sie ein Testmanifest mit ein paar Objekten aus Ihrem ursprünglichen Manifest.
-
Verwenden Sie den folgenden Befehl, um zu überprüfen, ob eine Auswahl von Objekten aus dem Manifest vorhanden ist.
aws s3 ls s3://amzn-s3-demo-bucket1/object-key -
Überprüfen Sie die Details des Auftragsfehlers und sehen Sie sich die Fehlerursache und alle spezifischen Fehlerdetails in der Auftragsbeschreibung an.
aws s3control describe-job --account-id111122223333--job-idjob-id