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

Si aún no se ha familiarizado con el almacenamiento de archivos en Amazon Simple Storage Service (Amazon S3), se recomienda que comience por obtener más información sobre las clases de almacenamiento de S3 Glacier en Amazon S3, S3 Glacier Instant Retrieval, S3 Glacier Flexible Retrieval y S3 Glacier Deep Archive. Para obtener más información, consulte Clases de almacenamiento de S3 Glacier y Clases de almacenamiento para archivar objetos en la Guía del usuario de Amazon S3.

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.

Inicialización de trabajos (POST trabajos)

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 Inicialización de trabajos (POST trabajos).

    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:

  • Puede usar una notificación de Amazon SNS: puede especificar un tema de Amazon SNS en el que S3 Glacier puede publicar una notificación cuando se complete el trabajo. Puede especificar un tema de SNS para cada solicitud de trabajo. La notificación se envía solo cuando S3 Glacier haya completado el trabajo. Además de especificar un tema de SNS para cada solicitud de trabajo, puede configurar las notificaciones en un almacén para que se envíen notificaciones de trabajo 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 eficaz usar las notificaciones de Amazon SNS para determinar cuándo se completa 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 en un evento concreto establece la configuración de las notificaciones en el almacén y también especifica un tema de SNS en la solicitud de inicio del 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. Cuando se inicia un trabajo para un inventario del almacén, S3 Glacier devuelve el último inventario generado, que es una instantánea realizada en un momento dado y no contiene 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 método HTTP POST y establezca el alcance de la solicitud en el subrecurso jobs del almacén. Los detalles de la solicitud de trabajo deben especificarse en el documento JSON de la solicitud. El tipo de trabajo se especifica con el campo Type. Si lo desea, puede especificar un campo SNSTopic para indicar un tema de Amazon SNS en el que S3 Glacier pueda publicar notificaciones cuando se complete el trabajo.

nota

Para publicar una notificación en Amazon SNS, debe crear el tema si este no existe aún. 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 valor AccountId es el ID de la Cuenta de AWS propietaria del almacén. Puede especificar un ID de Cuenta de AWS o, si lo desea, un solo carácter “-” (guion), en cuyo caso, Amazon S3 Glacier usa el ID de la Cuenta de AWS asociada con las credenciales empleadas para firmar la solicitud. Si usa un ID de cuenta, no incluya ningún guion (“-”) en el ID.

Cuerpo de la solicitud

El cuerpo de la solicitud admite los siguientes datos en formato JSON.

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 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 ruta relativa del URI del trabajo. Puede utilizar esta ruta de URI para buscar el estado del trabajo. Para obtener más información, consulte Descripción del trabajo (GET JobID).

Tipo: String

Valor predeterminado: None
x-amz-job-id

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

Tipo: String

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

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

Tipo: String

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.

Code Descripción Código de estado HTTP 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 Servidor

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. Format está establecido en CSV en el cuerpo de la solicitud, lo que indica que el inventario se devuelve con el formato 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"
}

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