Initiate Job (POST jobs) - Amazon S3 Glacier
Initiieren eines Archiv- oder Tresorinventarabrufs AnforderungenAntwortenBeispieleZugehörige Abschnitte

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)

Diese Produktion initiiert die folgenden Typen von Amazon S3 Glacier (S3 Glacier) -Aufträgen:

  • archive-retrieval— Ruft ein Archiv ab

  • inventory-retrieval— Inventarisieren Sie einen Tresor

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 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 Abrufjob initiieren, erstellt S3 Glacier einen Job und gibt in der Antwort eine Job-ID zurück. Wenn S3 Glacier den Job abgeschlossen hat, können Sie die Auftragsausgabe abrufen (Archiv- oder Inventardaten). 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 SNS-Benachrichtigung verwenden — Sie können ein Amazon SNS SNS-Thema angeben, zu dem S3 Glacier nach Abschluss des Jobs eine Benachrichtigung posten kann. Geben Sie dazu ein SNS-Thema für jede Auftragsanforderung an. Die Benachrichtigung wird erst gesendet, nachdem S3 Glacier den Job 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 eineDescribe Job (GET JobID) Anfrage stellen, um Informationen zum Auftragsstatus zu erhalten, während ein Job in Bearbeitung ist. Es ist jedoch effizienter, eine Amazon SNS SNS-Benachrichtigung zu verwenden, um festzustellen, wann ein Job 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 Benachrichtigungskonfiguration im Tresor hinzufügen als auch ein SNS-Thema in Ihrer Initiierungs-Job-Anfrage 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 ungefähr einmal täglich, und zwar ab dem Tag, an dem Sie ein Archiv zum ersten Mal 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 keine Echtzeitdaten handelt.

Nachdem S3 Glacier das erste Inventar für den Tresor erstellt hat, dauert es in der Regel einen halben Tag bis zu einem Tag, bis das Inventar zum Abrufen verfügbar ist.

Möglicherweise finden Sie es nicht nützlich, ein Tresorinventar für jeden Archiv-Upload abzurufen. Nehmen wir jedoch an, dass Sie auf der Clientseite eine Datenbank verwalten, die Metadaten zu den Archiven verknüpft, die Sie auf 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

Wenn Sie einen Archivabrufauftrag starten, können Sie imTier Feld des Anforderungstexts eine der folgenden Optionen angeben:

  • Expedited— Expedited ermöglicht Ihnen den schnellen Zugriff auf Ihre Daten, wenn gelegentliche dringende Zugriffe für die Wiederherstellung der Archive 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— Standard Lässt den Zugriff auf Ihre Archive innerhalb einiger Stunden innerhalb einiger Stunden zu. 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 ist die kostengünstigste Stufe für S3 Glacier, sodass Sie große Datenmengen, sogar Petabyte, kostengünstig an einem Tag abrufen können. 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 derAWS 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 einSNSTopic Feld angeben, das ein Amazon SNS SNS-Thema angibt, an das S3 Glacier nach Abschluss des Jobs eine Benachrichtigung senden kann.

Anmerkung

Um eine Benachrichtigung auf Amazon SNS zu posten, müssen Sie das Thema selbst erstellen, falls es noch nicht existiert. S3 Glacier erstellt das Thema nicht für Sie. Das Thema muss über Berechtigungen verfügen, um Veröffentlichungen aus einem S3 Glacier-Tresor zu erhalten. 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

DerAccountId Wert ist dieAWS-Konto ID des Kontos, dem der Tresor gehört. Sie können entweder eineAWS-Konto ID oder optional ein einzelnes '-' (Bindestrich) angeben. In diesem Fall verwendet Amazon S3 Glacier dieAWS-Konto ID, die den Anmeldeinformationen zugeordnet ist, mit denen die Anfrage signiert wurde. Wenn Sie eine Konto-ID verwenden, fügen Sie keine Bindestriche ('-') in die ID ein.

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 schafft den Job. 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

Diese Produktion gibt keinen Antworttext zurück.

Fehler

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

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