Lancement d'une tâche (POST jobs) - Amazon S3 Glacier
Initialisation d'une tâche d'extraction d'archive ou d'inventaire de coffre RequêtesRéponsesExemplesSections connexes

Si vous débutez dans le stockage d'archives dans Amazon Simple Storage Service (Amazon S3), nous vous recommandons dans un premier temps de vous familiariser avec les classes de stockage S3 Glacier dans Amazon S3, S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval et S3 Glacier Deep Archive. Pour plus d'informations, consultez les sections Classes de stockage S3 Glacier et Classes de stockage pour l'archivage d'objets dans le guide de l'utilisateur Amazon S3.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Lancement d'une tâche (POST jobs)

Cette opération lance les types de tâches Amazon S3 Glacier (S3 Glacier) suivants :

  • archive-retrieval : extrait une archive

  • inventory-retrieval : inventorie un coffre

Initialisation d'une tâche d'extraction d'archive ou d'inventaire de coffre

L'extraction d'une archive ou d'un inventaire de coffre sont des opérations asynchrones qui exigent que vous lanciez une tâche. Une fois lancée, la tâche ne peut pas être annulée. L'extraction est un processus en deux étapes :

  1. Initiez une tâche d'extraction à l'aide de l'opération Lancement d'une tâche (POST jobs).

    Important

    Une stratégie d'extraction de données peut entraîner l'échec de votre demande de lancement de tâche d'extraction et générer une PolicyEnforcedException. Pour plus d'informations sur les stratégies d'extraction de données, consultez la section Politiques d'extraction de données S3 Glacier. Pour plus d'informations sur l'exception PolicyEnforcedException, consultez la section Réponses d'erreur.

  2. Une fois la tâche terminée, téléchargez les octets à l'aide de l'opération Génération de sortie de tâche (GET output).

La demande d'extraction est exécutée de manière asynchrone. Lorsque vous lancez une tâche d'extraction, S3 Glacier crée une tâche et renvoie un ID de tâche dans la réponse. Une fois que S3 Glacier a terminé la tâche, vous pouvez obtenir la sortie de la tâche (données d'archive ou d'inventaire). Pour plus d'informations sur l'obtention de la sortie de la tâche, consultez l'opération Génération de sortie de tâche (GET output).

Pour recevoir la sortie de la tâche, la tâche doit être terminée. Pour déterminer si une tâche est terminée, vous disposez des options suivantes :

  • Utiliser une notification Amazon SNS – Vous pouvez spécifier la rubrique Amazon SNS sur laquelle S3 Glacier peut publier une notification après que la tâche est terminée. Vous pouvez spécifier une rubrique SNS par demande de tâche. La notification est envoyée uniquement après que S3 Glacier a terminé la tâche. En plus de spécifier une rubrique SNS par demande de tâche, vous pouvez configurer des notifications de coffre pour un coffre afin que les notifications de tâche soient envoyées pour toutes les extractions. Pour de plus amples informations, veuillez consulter Définition d'une configuration de notification de coffre (PUT notification-configuration).

  • Obtenir les détails de la tâche – Vous pouvez effectuer une demande Description de la tâche (GET JobID) pour obtenir les informations concernant le statut de la tâche pendant que celle-ci est en cours. Cependant, il est préférable d'utiliser une notification Amazon SNS pour déterminer à quel moment une tâche se termine.

Note

Les informations que vous obtenez via une notification sont identiques à celles que vous obtenez en appelant Description de la tâche (GET JobID).

Si, pour un événement spécifique, vous ajoutez la configuration des notifications du coffre et que vous spécifiez aussi une rubrique SNS dans votre demande de lancement de tâche, S3 Glacier envoie les deux notifications. Pour de plus amples informations, veuillez consulter Définition d'une configuration de notification de coffre (PUT notification-configuration).

L'inventaire du coffre

S3 Glacier met à jour un inventaire de coffre de façon quasi quotidienne, à partir du jour où vous commencez à charger une archive dans le coffre. Si aucun ajout ou aucune suppression d'archive n'a été effectué dans le coffre depuis le dernier inventaire, la date de l'inventaire n'est pas mise à jour. Lorsque vous lancez une tâche pour un inventaire de coffre, S3 Glacier renvoie le dernier inventaire qu'il a généré, qui correspond non pas à des données en temps réel, mais à un instantané à un moment donné.

Une fois que S3 Glacier a créé le premier inventaire du coffre, il faut généralement attendre entre une demi-journée et une journée complète avant de pouvoir extraire cet inventaire.

Vous ne trouverez peut-être pas utile d'extraire un inventaire de coffre pour chaque chargement d'archive. Cependant, supposez que vous tenez à jour une base de données côté client associant des métadonnées sur les archives que vous chargez sur S3 Glacier. Ensuite, vous trouverez peut-être l'inventaire de coffre très utile pour rapprocher, au besoin, les informations contenues dans votre base de données avec l'inventaire de coffre réel. Pour plus d'informations sur les champs de données renvoyés dans la sortie d'une tâche d'inventaire, consultez Corps de la réponse.

Extraction d'un inventaire par plage

Vous pouvez limiter le nombre d'éléments dans l'inventaire en filtrant par date de création de l'archive ou en définissant une limite.

Filtrage par la date de création de l'archive

Vous pouvez extraire des éléments d'inventaire pour des archives créées entre la valeur de StartDate et la valeur de EndDate en spécifiant les valeurs de ces paramètres dans la demande Lancement d'une tâche. Les archives créées à la ou après la StartDate et avant la EndDate sont renvoyées. Si vous n'indiquez que le paramètre StartDate sans le paramètre EndDate, vous extrayez l'inventaire pour toutes les archives créées à la ou après la StartDate. Si vous n'indiquez que le paramètre EndDate sans le paramètre StartDate, vous recevez l'inventaire correspondant à toutes les archives créées avant la EndDate.

Limitation des éléments de l'inventaire par extraction

Vous pouvez limiter le nombre d'éléments d'inventaire renvoyés en définissant le paramètre Limit dans la demande Lancement d'une tâche. La sortie de la tâche d'inventaire contient tous les éléments d'inventaire jusqu'à la valeur Limit spécifiée. Si plusieurs éléments d'inventaire sont disponibles, le résultat est paginé. Une fois qu'une tâche est terminée, vous pouvez utiliser l'opération Description de la tâche (GET JobID) pour obtenir un marqueur que vous utiliserez dans une demande Lancement d'une tâche ultérieure. Le marqueur indique le point de départ de l'extraction de la prochaine série d'éléments d'inventaire. Vous pouvez parcourir l'ensemble de votre inventaire en faisant des demandes de Lancement d'une tâche avec le marqueur de la sortie Description de la tâche précédente. Vous procédez ainsi jusqu'à ce que vous obteniez un marqueur de Description de la tâche renvoyant la valeur null, ce qui indique qu'il ne reste plus d'élément d'inventaire disponible.

Vous pouvez utiliser le paramètre Limit avec les paramètres de plage de dates.

Extraction d'une plage d'archive

Vous pouvez lancer l'extraction d'une archive pour l'archive entière ou une plage de l'archive. Pour extraire une plage d'archive, vous spécifiez une plage d'octets à renvoyer ou l'archive entière. Si ce champ est spécifié, la plage d'octets doit être alignée en termes de méga-octets (1024*1024). Autrement dit, la valeur de début de la plage doit être divisible par 1 Mo et la valeur de fin de la plage plus 1 doit être divisible par 1 Mo ou égale à la fin de l'archive. Si l'extraction de la plage de l'archive n'est pas alignée en termes de méga-octets, cette opération renvoie une réponse 400. En outre, afin de garantir que vous obteniez les valeurs de total de contrôle pour les données que vous téléchargez à l'aide de la demande Génération de sortie de tâche (Génération de sortie de tâche (GET output)), la plage doit être alignée avec le hachage d'arborescence. Pour plus d'informations sur les plages alignées avec le hachage d'arborescence, consultez la section Réception des totaux de contrôle lors du téléchargement de données.

Niveau Rapide, Standard et Groupé

Lorsque vous lancez une tâche d'extraction d'archive, vous pouvez spécifier l'une des options suivantes dans le champ Tier du corps de la demande :

  • Expedited : cette option vous permet d'accéder rapidement à vos données lorsque des demandes urgentes occasionnelles de restauration d'archives sont nécessaires. Pour toutes les archives à l'exception des plus volumineuses (plus de 250 Mo), les données auxquelles vous accédez du niveau Rapide sont généralement disponibles en 1 à 5 minutes.

  • Standard : cette option vous permet d'accéder à vos archives en quelques heures. L'accès aux données à l'aide du niveau Standard est généralement rendu disponible en 3 à 5 heures. Cette option par défaut correspond aux demandes de tâches qui ne spécifient pas l'option de niveau.

  • Bulk : cette option est le niveau le plus économique pour S3 Glacier. Elle vous permet d'extraire de grandes quantités de données (jusqu'à plusieurs pétaoctets) à peu de frais dans une même journée. L'accès aux données à l'aide du niveau Groupé est généralement rendu disponible en 5 à 12 heures.

Pour plus d'informations sur les récupérations rapides et en bloc, consultez Extraction d'archives S3 Glacier à l'aide de la console AWS.

Requêtes

Pour lancer une tâche, vous utilisez la méthode HTTP POST et limitez la portée de la demande à la sous-ressource jobs du coffre. Vous spécifiez les détails de la demande de tâche dans le document JSON de votre demande. Le type de tâche est spécifié dans le champ Type. Vous pouvez éventuellement spécifier un champ SNSTopic pour indiquer la rubrique Amazon SNS dans laquelle S3 Glacier peut publier une notification après avoir terminé la tâche.

Note

Pour publier une notification dans Amazon SNS, vous devez créer la rubrique vous-même si elle n'existe pas déjà. S3 Glacier ne crée pas la rubrique à votre place. Elle doit disposer des autorisations nécessaires pour recevoir les publications en provenance d'un coffre S3 Glacier. S3 Glacier ne vérifie pas si le coffre est autorisé à publier dans la rubrique. Si les autorisations ne sont pas configurées de façon appropriée, vous risquez de ne pas recevoir la notification même lorsque la tâche est terminée.

Syntaxe

Voici la syntaxe de la requête pour l'initiation d'une tâche.

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"
   }
}
Note

La valeur de AccountId est l'ID de Compte AWS du compte propriétaire du coffre. Vous pouvez spécifier un ID de Compte AWS ou éventuellement un simple « - » (trait d'union), auquel cas Amazon S3 Glacier utilise l'ID de Compte AWS associé aux informations d'identification utilisées pour signer la demande. Si vous utilisez un ID de compte, évitez d'y inclure des traits d'union (« - »).

Corps de la requête

La demande accepte les données suivantes au format JSON dans le corps de la demande.

jobParameters

Fournit des options de spécification des informations d'une tâche.

Type : objet jobParameters

Obligatoire : oui

Réponses

S3 Glacier crée la tâche. Dans la réponse, il retourne l'URI de la tâche.

Syntaxe

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

En-têtes de réponse

En-tête Description
Location

Le chemin d'accès par URI relatif de la tâche. Vous pouvez utiliser ce chemin d'accès par URI pour trouver l'état de la tâche. Pour de plus amples informations, veuillez consulter Description de la tâche (GET JobID).

Type : chaîne

Par défaut : aucun
x-amz-job-id

L'ID de la tâche. Cette valeur fait également partie de l'en-tête Location.

Type : chaîne

Par défaut : aucun
x-amz-job-output-path

Chemin vers l'emplacement auquel les résultats de tâches de sélection sont stockés.

Type : chaîne

Par défaut : aucun

Corps de la réponse

Cette opération ne renvoie pas de corps de réponse.

Erreurs

Cette opération inclut la ou les erreurs suivantes, en plus des erreurs possibles communes à toutes les opérations Amazon S3 Glacier. Pour en savoir plus sur les erreurs Amazon S3 Glacier et pour obtenir la liste des codes d'erreur, consultez Réponses d'erreur.

Code Description HTTP Status Code Type
InsufficientCapacityException Retournée s'il existe une capacité insuffisante pour traiter cette demande rapide. Cette erreur s'applique uniquement aux récupérations rapides et non aux récupérations standard ou en bloc. 503 Service Unavailable de bases de données

Exemples

Exemple de demande : Lancement d'une tâche d'extraction d'archive

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"
}

Voici un exemple de corps d'une demande qui spécifie une plage de l'archive à extraire à l'aide du champ RetrievalByteRange.

{
  "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"
}

Exemple de réponse

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

Exemple de demande : Lancement d'une tâche d'extraction d'inventaire

La demande suivante lance une tâche d'extraction d'inventaire pour obtenir une liste d'archives du coffre examplevault. Le paramètre Format défini sur CSV dans le corps de la demande indique que l'inventaire est renvoyé au format CSV.

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"
}

Exemple de réponse

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

Exemples de demandes : Initier une tâche d'extraction d'inventaire à l'aide d'un filtrage par date avec une limité définie, et demande consécutive d'extraction de la page suivante des éléments de l'inventaire.

La demande suivante lance une tâche d'extraction d'inventaire en utilisant le filtrage de dates et en définissant une limite. 


{
    "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"
    }, 
}

La demande suivante est un exemple de demande suivante d'extraction de la page suivante des éléments de l'inventaire à l'aide d'un marqueur obtenu de Description de la tâche (GET JobID). 

{
    "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"
    }, 
}

Exemple de réponse

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/

Sections connexes