Initiate Job (POST jobs) - Amazon S3 Glacier

Wenn Sie mit dem Archivierungsspeicher in Amazon Simple Storage Service (Amazon S3) noch nicht vertraut sind, empfehlen wir Ihnen, sich zunächst über die S3-Glacier-Speicherklassen in Amazon S3 (S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval und S3 Glacier Deep Archive) zu informieren. Weitere Informationen finden Sie unter S3-Glacier-Speicherklassen und Speicherklassen für die Archivierung von Objekten im Amazon S3-Benutzerhandbuch.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Initiate Job (POST jobs)

Dieser Vorgang initiiert die folgenden Typen von Amazon S3 Glacier (S3 Glacier)-Aufträgen:

  • archive-retrieval: Ein Archiv abrufen

  • inventory-retrieval: Bestand eines Tresors erfassen

Initiieren eines Archiv- oder Tresorinventarabrufs

Das Abrufen eines Archivs oder des Tresorinventars ist ein asynchroner Vorgang, für den Sie einen Auftrag initiieren müssen. Nach dem Start kann die Aufgabe nicht abgebrochen werden. Das Abrufen erfolgt in zwei Schritten:

  1. Initiieren Sie einen Abrufauftrag mit der Operation Initiate Job (POST jobs).

    Wichtig

    Eine Richtlinie für den Datenabruf kann dazu führen, dass die Anforderung zur Abrufinitiierung zu einer PolicyEnforcedException-Ausnahme führt und fehlschlägt. Weitere Informationen zu Datenabrufrichtlinien finden Sie unter Richtlinien für den Datenabruf in S3 Glacier. Weitere Informationen zur PolicyEnforcedException-Ausnahme finden Sie unter Fehlermeldungen.

  2. Laden Sie nach Abschluss des Auftrags die Bytes mit der Operation Get Job Output (GET output) herunter.

Die Abrufanforderung wird asynchron ausgeführt. Wenn Sie einen Abrufauftrag initiieren, erstellt S3 Glacier einen Auftrag und gibt eine Auftrags-ID in der Antwort zurück. Wenn S3 Glacier den Auftrag abgeschlossen hat, können Sie die Auftragsausgabe (d. h. die Archiv- oder Inventardaten) abrufen. Weitere Informationen über das Abrufen der Auftragsausgabe finden Sie in den Hinweisen zum Get Job Output (GET output)-Vorgang.

Der Auftrag muss abgeschlossen sein, bevor Sie die Ausgabe abrufen können. Verwenden Sie eine der folgenden Optionen, um festzustellen, wann ein Auftrag abgeschlossen ist:

  • Eine Amazon-SNS-Benachrichtigung verwenden: Sie können ein Amazon-SNS-Thema angeben, an das S3 Glacier nach Abschluss des Auftrags eine Benachrichtigung senden kann. Geben Sie dazu ein SNS-Thema für jede Auftragsanforderung an. Die Benachrichtigung wird erst gesendet, nachdem S3 Glacier den Auftrag abgeschlossen hat. Zusätzlich zur Angabe eines SNS-Themas für jede Auftragsanforderung können Sie Tresorbenachrichtigungen für einen Tresor konfigurieren, sodass Auftragsbenachrichtigungen für alle Abrufvorgänge gesendet werden. Weitere Informationen finden Sie unter Set Vault Notification Configuration (PUT notification-configuration).

  • Auftragsdetails abrufen: Sie können eine Describe Job (GET JobID)-Anforderung senden, um Informationen zum Auftragsstatus zu erhalten, während der Auftrag noch ausgeführt wird. Es ist jedoch effizienter, wenn Sie sich durch eine Amazon-SNS-Benachrichtigung darüber informieren lassen, dass ein Auftrag abgeschlossen ist.

Anmerkung

Die Informationen, die Sie in der Benachrichtigung erhalten, sind identisch mit den Informationen, die durch den Describe Job (GET JobID)-Aufruf ermittelt werden.

Wenn Sie für ein bestimmtes Ereignis sowohl die Benachrichtigung im Tresor konfigurieren als auch ein SNS-Thema bei der Initiierungsanforderung für den Auftrag angeben, sendet S3 Glacier beide Benachrichtigungen. Weitere Informationen finden Sie unter Set Vault Notification Configuration (PUT notification-configuration).

Die Inventarliste des Tresors

S3 Glacier aktualisiert ein Tresorinventar etwa einmal pro Tag, beginnend mit dem Tag, an dem Sie erstmals ein Archiv in den Tresor hochladen. Wenn dem Tresor seit der letzten Inventur keine Archive hinzugefügt oder aus ihm gelöscht wurden, wird das Inventurdatum nicht aktualisiert. Wenn Sie einen Auftrag für eine Tresorinventur initiieren, gibt S3 Glacier den letzten generierten Bestand zurück. Dieser ist ein Point-in-Time-Snapshot und enthält keine Echtzeitdaten.

Wenn S3 Glacier die erste Inventur für den Tresor erstellt, kann es in der Regel einen halben Tag und sogar bis zu einem Tag dauern, bis der Bestand abgerufen werden kann.

Möglicherweise finden Sie es nicht nützlich, ein Tresorinventar für jeden Archiv-Upload abzurufen. Sie können jedoch auch eine clientseitige Datenbank haben, die Metadaten über die Archive zuordnet, die Sie in S3 Glacier hochladen. Dann finden Sie es möglicherweise nützlich, wenn die Tresorinventur die Informationen in Ihrer Datenbank nach Bedarf mit dem aktuellen Tresorinventar abgleicht. Weitere Informationen über die Datenfelder, die bei einer Inventarabfrage zurückgegeben werden, finden Sie unter Antworttext.

Inventarabfrage für einzelne Bereiche

Sie können die Anzahl der abgerufenen Tresorinventarelemente beschränken, indem Sie nach dem Archiverstellungsdatum filtern oder ein Limit festlegen.

Filtern nach dem Archiverstellungsdatum

Sie können Inventarelemente für Archive abrufen, die zwischen dem StartDate und dem EndDate erstellt wurden, indem Sie die Werte für diese Parameter in der Initiate Job-Anforderung angeben. Dadurch werden Archive zurückgegeben, die am oder nach dem StartDate und vor dem EndDate erstellt wurden. Wenn Sie nur das StartDate ohne das EndDate angeben, wird die Inventarliste für alle Archive abgerufen, die am oder nach dem StartDate erstellt wurden. Wenn Sie nur das EndDate ohne das StartDate angeben, wird die Inventarliste für alle Archive erstellt, die vor dem EndDate erstellt wurden.

Beschränken der Inventarelemente für einzelne Abrufvorgänge

Sie können die Anzahl der zurückgegebenen Inventarelemente beschränken, indem Sie den Limit-Parameter in der Initiate Job-Anforderung festlegen. Die Ausgabe für den Inventarauftrag enthält Inventarelemente bis zum festgelegten Limit. Wenn mehr Inventarelemente vorhanden sind, wird das Ergebnis paginiert. Nachdem ein Auftrag abgeschlossen ist, können Sie mithilfe der Describe Job (GET JobID)-Operation eine Markierung abrufen, die Sie für eine nachfolgende Initiate Job-Anforderung verwenden können. Die Markierung kennzeichnet den Startpunkt, ab dem die nächste Gruppe der Inventarelemente abgerufen wird. Sie können durch das gesamte Inventar blättern, indem Sie wiederholt Initiate Job-Anforderungen mit der Markierung aus der vorherigen Describe Job-Ausgabe ausführen. Verfahren Sie so, bis eine Markierung von Describe Job mit Null zurückgegeben wird. Dies bedeutet, dass keine Inventarelemente mehr verfügbar sind.

Sie können die Limit-Parameter zusammen mit den Datenbereichsparametern verwenden.

Abrufen eines Archivbereichs

Sie können den Abrufvorgang für das gesamte Archiv oder einen Bereich des Archivs initiieren. Beim Abrufen von Archivbereichen haben Sie die Möglichkeit einen Bytebereich anzugeben oder das gesamte Archiv abzurufen. Der Bereich muss in Megabytewerten (MB) angegeben werden. Das bedeutet, der Startwert muss 1 MB oder ein Vielfaches davon sein und der Bereichsendwert plus 1 muss durch 1 MB teilbar sein oder dem Ende des Archivs entsprechen. Wenn beim Abrufen eines Archivbereichs keine ganzen Megabytewerte angegeben werden, wird als Antwort 400 zurückgegeben. Um sicherzustellen, dass Sie Prüfsummenwerte für Daten erhalten, die Sie mit der Funktion Get Job Output (Get Job Output (GET output)) herunterladen, muss der Bereich mit dem Struktur-Hash abgeglichen sein. Weitere Informationen zum Abgleichen von Bereichen mit dem Struktur-Hash finden Sie unter Erhalten von Prüfsummen bei Daten-Download.

Expedited-, Standard- und Bulk-Kontingente

Beim Initiieren eines Archivabrufauftrags können Sie eine der folgenden Optionen im Feld Tier des Anforderungstexts angeben:

  • Expedited – „Expedited“-Abrufe ermöglichen Ihnen den schnellen Zugriff auf Ihre Daten, wenn gelegentliche dringende Anforderungen zum Wiederherstellen von Archiven erforderlich sind. Daten, die unter Verwendung des "Expedited"-Kontingents abgerufen werden, stehen normalerweise innerhalb von 1 bis 5 Minuten zur Verfügung, außer wenn es sich um sehr große Archive (250 MB und mehr) handelt.

  • Standard – Mit „Standard“-Abrufen können Sie innerhalb von mehreren Stunden auf jedes Ihrer Archive zugreifen. Daten, die über das Standardkontingent abgerufen werden, sind in der Regel innerhalb von drei bis fünf Stunden verfügbar. Diese Option ist für Auftragsanforderungen, für die kein Kontingent angegeben wird, das Standardkontingent.

  • Bulk – „Bulk“-Abrufe sind die kostengünstigste Stufe für S3 Glacier. Sie ermöglichen Ihnen, große Datenmengen bis hin zu Petabytes innerhalb von einem Tag abzurufen. Daten, die über das Bulk-Kontingent abgerufen werden, sind in der Regel innerhalb von 5 bis 12 Stunden verfügbar.

Weitere Informationen zu Expedited- und Bulk-Abrufen finden Sie unter Abrufen von S3-Glacier-Archiven mithilfe der AWS-Konsole.

Anforderungen

Verwenden Sie zum Initiieren eines Auftrags die HTTP-POST-Methode und beschränken Sie den Umfang der Anforderung auf die jobs-Unterressource des Tresors. Sie legen die Details der Auftragsanforderung im JSON-Dokument für Ihre Anforderung fest. Der Auftragstyp wird im Feld Type angegeben. Optional können Sie auch ein SNSTopic-Feld festlegen, um ein Amazon-SNS-Thema anzugeben, an das S3 Glacier nach Beendigung des Auftrags die Benachrichtigung übermitteln kann.

Anmerkung

Damit eine Benachrichtigung an Amazon SNS übermittelt wird, müssen Sie das Thema selbst erstellen, falls es noch nicht vorhanden ist. S3 Glacier erstellt das Thema nicht für Sie. Das Thema muss über Berechtigungen zum Empfangen von Veröffentlichungen aus einem S3-Glacier-Tresor verfügen. S3 Glacier überprüft nicht, ob der Tresor berechtigt ist, das Thema zu veröffentlichen. Wenn die Berechtigungen nicht ordnungsgemäß konfiguriert sind, erhalten Sie unter Umständen selbst nach Beendigung des Auftrags keine Benachrichtigung.

Syntax

Nachfolgend sehen Sie die Anforderungssyntax für das Initiieren eines Auftrags.

POST /AccountId/vaults/VaultName/jobs HTTP/1.1 Host: glacier.Region.amazonaws.com Date: Date Authorization: SignatureValue x-amz-glacier-version: 2012-06-01 { "jobParameters": { "ArchiveId": "string", "Description": "string", "Format": "string", "InventoryRetrievalParameters": { "EndDate": "string", "Limit": "string", "Marker": "string", "StartDate": "string" }, "OutputLocation": { "S3": { "AccessControlList": [ { "Grantee": { "DisplayName": "string", "EmailAddress": "string", "ID": "string", "Type": "string", "URI": "string" }, "Permission": "string" } ], "BucketName": "string", "CannedACL": "string", "Encryption": { "EncryptionType": "string", "KMSContext": "string", "KMSKeyId": "string" }, "Prefix": "string", "StorageClass": "string", "Tagging": { "string" : "string" }, "UserMetadata": { "string" : "string" } } }, "RetrievalByteRange": "string", "SelectParameters": { "Expression": "string", "ExpressionType": "string", "InputSerialization": { "csv": { "Comments": "string", "FieldDelimiter": "string", "FileHeaderInfo": "string", "QuoteCharacter": "string", "QuoteEscapeCharacter": "string", "RecordDelimiter": "string" } }, "OutputSerialization": { "csv": { "FieldDelimiter": "string", "QuoteCharacter": "string", "QuoteEscapeCharacter": "string", "QuoteFields": "string", "RecordDelimiter": "string" } } }, "SNSTopic": "string", "Tier": "string", "Type": "string" } }
Anmerkung

Der AccountId-Wert ist die AWS-Konto-ID des Kontos, dem der Tresor gehört. Sie können entweder eine AWS-Konto-ID oder optional einen einzelnen Bindestrich („-“) angeben. Bei Angabe eines Bindestrichs verwendet Amazon S3 Glacier die AWS-Konto-ID, die mit den zum Signieren der Anforderung verwendeten Anmeldeinformationen verknüpft ist. Wenn Sie eine Konto-ID verwenden, darf diese keine Bindestriche („-“) enthalten.

Anforderungstext

Die Anforderung akzeptiert die folgenden Daten im JSON-Format im Text der Anforderung.

jobParameters

Bietet Optionen für die Angabe von Auftragsinformationen.

Typ: jobParameters-Objekt

Required: Yes

Antworten

S3 Glacier erstellt den Auftrag. In der Antwort wird der URI des Auftrags zurückgegeben.

Syntax

HTTP/1.1 202 Accepted x-amzn-RequestId: x-amzn-RequestId Date: Date Location: location x-amz-job-id: jobId x-amz-job-output-path: jobOutputPath

Antwort-Header

Header Beschreibung
Location

Der relative URI-Pfad des Auftrags. Sie können diesen URI-Pfad verwenden, um den Auftragsstatus zu ermitteln. Weitere Informationen finden Sie unter Describe Job (GET JobID).

Typ: Zeichenfolge

Standard: keiner

x-amz-job-id

Die ID des Auftrags. Dieser Wert wird ebenfalls als Teil des Location-Headers angegeben.

Typ: Zeichenfolge

Standard: keiner

x-amz-job-output-path

Der Pfad des Speicherorts, an dem die Auswahlergebnisse gespeichert werden

Typ: Zeichenfolge

Standard: keiner

Antworttext

Dieser Vorgang gibt keinen Antworttext zurück.

Fehler

Dieser Vorgang umfasst zusätzlich zu den möglichen Fehlern, die allen Amazon S3-Glacier-Vorgängen gemeinsam sind, die folgenden Fehler. Informationen zu Amazon-S3-Glacier-Fehlern und eine Liste der Fehlercodes finden Sie unter Fehlermeldungen.

Code Beschreibung HTTP-Statuscode Typ
InsufficientCapacityException Wird zurückgegeben, wenn die vorhandene Kapazität nicht ausreicht, um diese beschleunigte Anforderung zu verarbeiten. Dieser Fehler gilt nur für beschleunigte Abrufe und nicht für Standard- oder Massenabrufe. 503 Service Unavailable Server

Beispiele

Beispielanforderung: Initiieren eines Auftrags zum Abrufen eines Archivs

POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20170210T120000Z x-amz-glacier-version: 2012-06-01 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 { "Type": "archive-retrieval", "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", "Description": "My archive description", "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example", "Tier" : "Bulk" }

Das folgende Beispiel zeigt den Text einer Anforderung, durch die ein abzurufender Archivbereich mithilfe des RetrievalByteRange-Feldes festgelegt wird.

{ "Type": "archive-retrieval", "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", "Description": "My archive description", "RetrievalByteRange": "2097152-4194303", "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example", "Tier" : "Bulk" }

Beispielantwort

HTTP/1.1 202 Accepted x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

Beispielanforderung: Initiieren eines Auftrags zum Abrufen des Inventars

Die folgende Anforderung initiiert einen Auftrag für eine Inventarabfrage, durch die eine Liste der Archive im examplevault-Tresor angefordert wird. Da das Format im Text der Anforderung auf CSV festgelegt ist, wird das Inventar im CSV-Format zurückgegeben.

POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20170210T120000Z Content-Type: application/x-www-form-urlencoded x-amz-glacier-version: 2012-06-01 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 { "Type": "inventory-retrieval", "Description": "My inventory job", "Format": "CSV", "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-InventoryRetrieval-topic-Example" }

Beispielantwort

HTTP/1.1 202 Accepted x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

Beispielanforderungen: Initiieren eines Inventarabrufs unter Verwendung von Datenfiltern mit festem Limit und einer Folgeanforderung zum Abrufen der nächsten Seite der Inventarelemente

Die folgende Anforderung initiiert einen Auftrag zum Abrufen des Tresorinventars durch Filtern der Daten und Festlegen eines Limits.

{ "ArchiveId": null, "Description": null, "Format": "CSV", "RetrievalByteRange": null, "SNSTopic": null, "Type": "inventory-retrieval", "InventoryRetrievalParameters": { "StartDate": "2013-12-04T21:25:42Z", "EndDate": "2013-12-05T21:25:42Z", "Limit" : "10000" }, }

Die folgende Anforderung ist ein Beispiel für eine Folgeanforderung zum Abrufen der nächsten Seite der Inventarelemente mithilfe einer Markierung, die durch Describe Job (GET JobID) übermittelt wurde.

{ "ArchiveId": null, "Description": null, "Format": "CSV", "RetrievalByteRange": null, "SNSTopic": null, "Type": "inventory-retrieval", "InventoryRetrievalParameters": { "StartDate": "2013-12-04T21:25:42Z", "EndDate": "2013-12-05T21:25:42Z", "Limit": "10000", "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0" }, }

Beispielantwort

HTTP/1.1 202 Accepted x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-output-path: test/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/

Zugehörige Abschnitte