Iniciar trabajo (POSTtrabajos) - Amazon S3 Glacier
Inicialización de un trabajo de recuperación de archivo o de inventario de almacén SolicitudesRespuestasEjemplosSecciones relacionadas

Esta página es solo para los clientes actuales del servicio S3 Glacier que utilizan Vaults y el original de 2012. REST API

Si busca soluciones de almacenamiento de archivos, le sugerimos que utilice las clases de almacenamiento S3 Glacier en Amazon S3, S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval y S3 Glacier Deep Archive. Para obtener más información sobre estas opciones de almacenamiento, consulte Clases de almacenamiento de S3 Glacier y Almacenamiento de datos a largo plazo con clases de almacenamiento de S3 Glacier en la Guía del usuario de Amazon S3. Estas clases de almacenamiento utilizan Amazon S3API, están disponibles en todas las regiones y se pueden gestionar en la consola de Amazon S3. Ofrecen funciones como el análisis de costos de almacenamiento, Storage Lens, funciones avanzadas de cifrado opcionales y más.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Iniciar trabajo (POSTtrabajos)

Esta operación inicia los siguientes tipos de trabajos de Amazon S3 Glacier (S3 Glacier):

  • archive-retrieval: recuperación de un archivo

  • inventory-retrieval: inventario de un almacén

Inicialización de un trabajo de recuperación de archivo o de inventario de almacén

Las operaciones de recuperación de un archivo o de un inventario del almacén son asincrónicas, por lo que es necesario iniciar un trabajo. Una vez iniciado, el trabajo no se puede cancelar. La recuperación es un proceso que consta de dos pasos:

  1. Inicie un trabajo de recuperación utilizando la operación Iniciar trabajo (POSTtrabajos).

    importante

    Si se utiliza una política de recuperación de datos, puede producirse una excepción PolicyEnforcedException en la solicitud de inicio del trabajo de recuperación. Para obtener más información sobre las políticas de recuperación de datos, consulte Políticas de recuperación de datos de S3 Glacier. Para obtener más información sobre la excepción PolicyEnforcedException, consulte Respuestas de error.

  2. Una vez completado el trabajo, descargue los bytes utilizando la operación Obtención de la salida del trabajo (GET output).

La solicitud de recuperación se ejecuta de forma asíncrona. Cuando se inicia un trabajo de recuperación, S3 Glacier crea un trabajo y devuelve un ID de trabajo en la respuesta. Una vez que S3 Glacier finaliza el trabajo, se puede obtener la salida del trabajo (los datos del archivo o del inventario). Para obtener más información acerca de cómo obtener la salida de un trabajo, consulte la operación Obtención de la salida del trabajo (GET output).

El trabajo debe completarse antes de poder obtener la salida. Para determinar cuándo se ha completado un trabajo, cuenta con las siguientes opciones:

  • Utilice una SNS notificación de Amazon: puede especificar un SNS tema de Amazon en el que S3 Glacier pueda publicar una notificación una vez finalizado el trabajo. Puede especificar un SNS tema por solicitud de trabajo. La notificación se envía solo cuando S3 Glacier haya completado el trabajo. Además de especificar un SNS tema por solicitud de trabajo, puede configurar las notificaciones del almacén para que las notificaciones de trabajo se envíen en todas las recuperaciones. Para obtener más información, consulte Establecimiento de la configuración de notificación del almacén (PUT configuración-notificaciones).

  • Puede obtener información sobre el trabajo: puede realizar una solicitud Descripción del trabajo (GET JobID) para obtener información sobre el estado de un trabajo mientras está en curso. Sin embargo, es más eficiente utilizar una SNS notificación de Amazon para determinar cuándo se ha completado un trabajo.

nota

La información que se obtiene través de las notificaciones es la misma que se obtiene llamando a Descripción del trabajo (GET JobID).

Si, para un evento específico, agrega la configuración de notificaciones al almacén y también especifica un SNS tema en su solicitud de inicio de trabajo, S3 Glacier envía ambas notificaciones. Para obtener más información, consulte Establecimiento de la configuración de notificación del almacén (PUT configuración-notificaciones).

El inventario del almacén

A partir del día que se carga por primera vez un archivo en el almacén, S3 Glacier actualiza el inventario del almacén aproximadamente una vez al día. Si no se han agregando ni eliminado archivos en el almacén desde el último inventario, la fecha del inventario no se actualiza. Al iniciar un trabajo de inventario de bóvedas, S3 Glacier devuelve el último inventario que generó, que es una point-in-time instantánea y no datos en tiempo real.

Una vez que S3 Glacier crea el primer inventario de almacén, debe transcurrir entre medio día y un día para que el inventario pueda recuperarse.

Es posible que no le parezca útil recuperar un inventario del almacén cada vez que carga un archivo. Sin embargo, imagine que tiene una base de datos del cliente asociada con los metadatos de los archivos que se cargan en S3 Glacier. En ese caso, el inventario del almacén podría resultarle útil para, en función de sus necesidades, conciliar la información de la base de datos con el inventario del almacén real. Para obtener más información acerca de los campos de datos que se devuelven en la salida de un trabajo de inventario, consulte Cuerpo de respuesta.

Recuperación del inventario por intervalos

Puede limitar el número de elementos del inventario que se van a recuperar utilizando como filtro la fecha de creación del archivo o definiendo un límite.

Filtrado por la fecha de creación del archivo

Puede recuperar los elementos de los archivos creados entre StartDate y EndDate especificando valores para estos parámetros en la solicitud Initiate Job. De ese modo, se devolverán los archivos creados el día de StartDate o los que se crearon entre esa fecha y EndDate. Si solo se proporciona StartDate y no EndDate, se recuperará el inventario de todos los archivos que se hayan creado en StartDate o con posterioridad a esa fecha. Si solo se proporciona EndDate y no StartDate, se recuperará el inventario de todos los archivos que se hayan creado antes de EndDate.

Limitación de los elementos del inventario de cada recuperación

Puede limitar el número de artículos que se devuelven estableciendo el parámetro Limit de la solicitud Initiate Job. La salida del trabajo de inventario contendrá los elementos del inventario hasta el límite especificado en Limit. Si hay más elementos disponibles en el inventario, el resultado aparecerá paginado. Una vez que se ha completado un trabajo, se puede utilizar la operación Descripción del trabajo (GET JobID) para obtener un marcador y utilizarlo en otras solicitudes Initiate Job (Iniciar trabajo) posteriores. Este marcador indica el punto de partida en la recuperación del próximo conjunto de elementos del inventario. Puede desplazarse por las páginas de todo el inventario realizando reiteradamente solicitudes Initiate Job (Iniciar trabajo) con el marcador de la salida de Describe Job anterior. Puede realizar esta operación hasta que obtenga de Describe Job (Describir trabajo) un marcador que devuelva null, lo que indica que no hay más elementos de inventario disponibles.

Puede utilizar el parámetro Limit junto con los parámetros de intervalos de fechas.

Recuperación del archivo por intervalos

Puede iniciar una recuperación de todo el archivo o de un intervalo. En el caso de la recuperación de archivos por intervalos, debe especificar el intervalo de bytes que se va a devolver o todo el archivo. El intervalo especificado debe estar alineado en megabytes (MB). En otras palabras, el valor inicial del intervalo debe ser divisible por 1 MB, mientras que el valor final del intervalo más 1 debe ser divisible por 1 MB o igual que el final del archivo. Si la recuperación del archivo por intervalos no está alineada en megabytes, esta operación devuelve una respuesta 400. Además, para garantizar que se obtienen los valores de la suma de comprobación de los datos descargados con Get Job Output (Obtener salida de trabajo) (Obtención de la salida del trabajo (GET output)), el intervalo debe estar alineado con un algoritmo hash en árbol. Para obtener más información sobre los intervalos alineados con un algoritmo hasta en árbol, consulte Recuperación de sumas de comprobación al descargar datos.

Niveles Expedited, Standard y Bulk

Al iniciar un trabajo de recuperación de archivo, puede especificar una de las siguientes opciones en el campo Tier del cuerpo de la solicitud:

  • Expedited: el nivel rápido le permite acceder rápidamente a sus datos cuando es necesario utilizar solicitudes urgentes ocasionales para restaurar archivos. En todos los archivos excepto en los de mayor tamaño (más de 250 MB), los datos a los que se obtiene acceso con el nivel rápido suelen estar disponibles en un plazo comprendido entre 1 y 5 minutos.

  • Standard: el nivel estándar permite acceder a los archivos en un plazo de varias horas. Los datos a los que se obtiene acceso con el nivel Standard normalmente están disponibles en un plazo de 3 a 5 horas. Esta es la opción predeterminada para las solicitudes de los trabajos que no especifican el nivel.

  • Bulk: el nivel en bloque es el nivel de S3 Glacier con los costos más bajos, lo que le permite recuperar grandes cantidades de datos, incluso petabytes, de forma económica y en un mismo día. Los datos a los que se obtiene acceso con el nivel Bulk normalmente están disponibles en un plazo de 5 a 12 horas.

Para obtener más información sobre las recuperaciones Expedited y Bulk, consulte Recuperación de archivos de S3 Glacier mediante la consola de AWS.

Solicitudes

Para iniciar un trabajo, utilice el HTTP POST método y dirija la solicitud al jobs subrecurso del almacén. Los detalles de la solicitud de trabajo se especifican en el JSON documento de la solicitud. El tipo de trabajo se especifica con el campo Type. Si lo desea, puede especificar un SNSTopic campo para indicar un SNS tema de Amazon en el que S3 Glacier puede publicar una notificación después de completar el trabajo.

nota

Para publicar una notificación en AmazonSNS, debes crear el tema tú mismo si aún no existe. S3 Glacier no lo crea automáticamente. El tema debe tener los permisos necesarios para recibir publicaciones de un almacén de S3 Glacier. S3 Glacier no comprueba si el almacén tiene permiso para publicar en el tema. Si los permisos no están configurados correctamente, es posible que no reciba ninguna notificación aunque se complete el trabajo.

Sintaxis

A continuación, se muestra la sintaxis de la solicitud para iniciar un trabajo.

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

El AccountId valor es el Cuenta de AWS ID de la cuenta propietaria de la bóveda. Puede especificar un Cuenta de AWS ID o, si lo desea, un único - '' (guión), en cuyo caso Amazon S3 Glacier utilizará el Cuenta de AWS ID asociado a las credenciales utilizadas para firmar la solicitud. Si usa un ID de cuenta, no incluya ningún guion (“-”) en el ID.

Cuerpo de la solicitud

La solicitud acepta los siguientes datos en JSON formato en el cuerpo de la solicitud.

jobParameters

Ofrece opciones para especificar la información del trabajo.

Tipo: jobParameters objeto

Obligatorio: sí

Respuestas

S3 Glacier crea el trabajo. En la respuesta, devuelve el URI nombre del trabajo.

Sintaxis

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

Encabezados de respuesta

Encabezado Descripción
Location

La URI ruta relativa del trabajo. Puede utilizar esta URI ruta para buscar el estado del trabajo. Para obtener más información, consulte Descripción del trabajo (GET JobID).

Tipo: cadena

Valor predeterminado: None
x-amz-job-id

ID del trabajo. Este valor también forma parte del encabezado Location.

Tipo: cadena

Valor predeterminado: None
x-amz-job-output-path

Ruta de la ubicación en la que se almacenan los resultados del trabajo Select.

Tipo: cadena

Valor predeterminado: None

Cuerpo de respuesta

Esta operación no devuelve ningún cuerpo de respuesta.

Errores

Esta operación incluye los siguientes errores, además de los posibles errores comunes a todas las operaciones de Amazon S3 Glacier. Para obtener información sobre los errores de Amazon S3 Glacier y una lista de códigos de error, consulte Respuestas de error.

Código Descripción HTTPCódigo de estado Tipo
InsufficientCapacityException Esta excepción se devuelve si no hay capacidad suficiente para procesar la solicitud Expedited. Este error solo se aplica a las recuperaciones Expedited; no se aplica a las recuperaciones estándar ni de tipo Bulk. 503 Service Unavailable Server

Ejemplos

Solicitud de ejemplo: inicio de un trabajo de recuperación de un archivo

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

A continuación, se muestra un ejemplo del cuerpo de una solicitud donde se especifica el intervalo del archivo que se va a recuperar mediante el campo 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"
}

Respuesta de ejemplo

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

Solicitud de ejemplo: inicio de un trabajo de recuperación de un inventario

En la siguiente solicitud, se inicia un trabajo de recuperación de inventario para obtener una lista de archivos del almacén examplevault. El Format valor indicado CSV en el cuerpo de la solicitud indica que el inventario se devuelve en ese CSV formato.

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

Respuesta de ejemplo

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

Solicitudes de ejemplo: inicie un trabajo de recuperación de inventario utilizando el filtrado de fechas con un límite establecido y una solicitud posterior para recuperar la siguiente página de elementos de inventario.

La siguiente solicitud inicia un trabajo de recuperación de un inventario del almacén donde se aplica un filtro de fecha y se establece un límite. 


{
    "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 siguiente solicitud es un ejemplo de una solicitud posterior para recuperar la siguiente página de elementos del inventario a través de un marcado obtenido de Descripción del trabajo (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"
    }, 
}

Respuesta de ejemplo

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/

Secciones relacionadas