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 Tresorbestandsabrufs

Das Abrufen eines Archivs oder des Tresorbestands 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 einen Tresorbestand 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 Job für ein Tresorinventar initiieren, gibt S3 Glacier das zuletzt generierte Inventar zurück, bei dem es sich um einen point-in-time Snapshot und nicht um Echtzeitdaten handelt.

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, einen Tresorbestand 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 Tresorbestand 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 Tresorbestandselemente 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 S3 Glacier-Archive abrufen.

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 ein einzelnes '-' (Bindestrich) angeben. In diesem Fall verwendet Amazon S3 Glacier die AWS-Konto ID, die den Anmeldeinformationen zugeordnet ist, die zum Signieren der Anfrage verwendet wurden. 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

Erforderlich: Ja

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 Tresorbestands 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

• Describe Job (GET JobID)

• Get Job Output (GET output)

• Identitäts- und Zugriffsverwaltung für Amazon S3 Glacier