Formularios HTML (AWS Signature Version 2)
Temas
Cuando se comunica con Amazon S3, por lo general utiliza la API REST o SOAP para realizar operaciones como PUT, GET, DELETE, y otras. Con POST, los usuarios cargan datos directamente en Amazon S3 a través de sus navegadores, que no pueden procesar la API de SOAP ni crear una solicitud PUT de REST.
nota
La compatibilidad con SOAP por HTTP está obsoleta, pero SOAP aún se encuentra disponible con HTTPS. Las características nuevas de Amazon S3 no son compatibles con SOAP. En vez de usar SOAP, le recomendamos que utilice la API de REST o los SDK de AWS.
Para que los usuarios puedan cargar contenido en Amazon S3 con sus navegadores, debe utilizar los formularios HTML. Los formularios HTML constan de una declaración de formulario y campos de formulario. Cada declaración de formulario incluye información de alto nivel acerca de la solicitud. Los campos de formulario incluyen información detallada acerca de la solicitud, así como la política que se utiliza para autenticarla y asegurar que cumpla con las condiciones que usted especifica.
nota
Los datos y límites del formulario (sin incluir los contenidos del archivo) no pueden exceder los 20 KB.
En esta sección se explica cómo utilizar los formularios HTML.
Codificar formulario HTML
El formulario y la política deben estar cifrados con UTF-8. Para aplicar la codificación UTF-8 en el formulario puede especificarlo en el encabezado HTML o como un encabezado de solicitud.
nota
La declaración de formulario HTML no acepta parámetros de autenticación por query string.
A continuación, mostramos un ejemplo de la codificación UTF-8 en el encabezado HTML:
<html> <head> ... <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> ... </head> <body>
A continuación, se muestra un ejemplo de la codificación UTF-8 en un encabezado de solicitud:
Content-Type: text/html; charset=UTF-8
Declaración de formulario HTML
La declaración de formulario tiene tres componentes: la acción, el método y el tipo de documento adjunto. Si cualquiera de estos valores se configura de manera inadecuada, la solicitud falla.
La acción especifica el URL que procesa la solicitud, que debe establecerse en el URL del bucket. Por ejemplo, si el nombre de su bucket es awsexamplebucket1 y la región es EE. UU. Oeste (Norte de California), la URL es https://awsexamplebucket1.s3.us-west-1.amazonaws.com/.
nota
El nombre de clave se especifica en un campo de formulario.
El método debe ser POST.
Se debe especificar el tipo de documento adjunto (enctype) y se debe establecer en datos de formulario/multiparte para cargas de archivos y cargas de área de texto. Para obtener más información, visite RFC 1867
ejemplo
El siguiente ejemplo es una declaración de formulario para el bucket "awsexamplebucket1".
<form action="https://awsexamplebucket1.s3.us-west-1.amazonaws.com/" method="post" enctype="multipart/form-data">
Campos de formulario HTML
En la siguiente tabla se describen los campos que se pueden utilizar en un formulario HTML.
nota
La variable ${filename} se reemplaza automáticamente con el nombre del archivo provisto por el usuario y es reconocida por todos los campos de formulario. Si el navegador o el cliente proporciona una ruta total o parcial al archivo, solo se utilizará el texto después de la última barra inclinada (/) o barra inversa (\). Por ejemplo, “C:\Program Files\directory1\file.txt” se interpretará como “file.txt”. Si no se brinda ningún archivo o nombre de archivo, la variable se reemplaza con una cadena vacía.
| Nombre del campo | Descripción | Obligatorio |
|---|---|---|
AWSAccessKeyId |
El ID de clave de acceso de AWS del propietario del bucket que otorga un acceso de usuario anónimo para una solicitud que cumple con el conjunto de restricciones en la política. Este campo es obligatorio si la solicitud incluye un documento de política. |
Condicional |
acl |
Una lista de control de acceso (ACL) de Amazon S3. Si se especifica una lista de control de acceso no válida, se genera un error. Para obtener más información acerca de las ACL, consulte Listas de control de acceso (ACL). Tipo: String Valor predeterminado: privado Valores válidos: |
No |
Cache-Control, Content-Type, Content-Disposition,
Content-Encoding, Expires |
Encabezados específicos de REST. Para obtener más información, consulte PUT Object. |
No |
key |
El nombre de la clave cargada. Para utilizar el nombre de archivo provisto por el usuario, utilice la variable ${filename}. Por ejemplo si la usuaria Betty carga el archivo lolcatz.jpg y usted especifica /user/betty/${filename}, el archivo se guarda como /user/betty/lolcatz.jpg. Para obtener más información, consulte Trabajar con metadatos de objeto. |
Sí |
policy |
Política de seguridad que describe qué está permitido en la solicitud. Las solicitudes sin una política de seguridad se consideran anónimas y solo se aceptarán en buckets que se pueden escribir públicamente. |
No |
success_action_redirect, redirect |
URL al que el cliente es redirigido después de la carga exitosa. Amazon S3 adjunta al URL el bucket, la clave y los valores de la etag como parámetros de cadena de consulta. Si no se especifica el campo success_action_redirect, Amazon S3 devuelve el tipo de documento vacío especificado en el campo success_action_status. Si Amazon S3 no puede interpretar la URL, ignora el campo . Si la carga falla, Amazon S3 muestra un error y no redirige al usuario a una URL. Para obtener más información, consulte Redireccionamiento. notaEl nombre de campo de redirección es obsoleto y el soporte para el nombre de campo de redirección se eliminará en el futuro. |
No |
success_action_status |
El código de estado que recibe el cliente después de la carga exitosa si no se especifica el campo success_action_redirect. Los valores válidos son 200, 201 o 204 (predeterminado). Si el valor se establece en 200 o 204, Amazon S3 devuelve un documento vacío con un código de estado 200 o 204. Si el valor se establece en 201, Amazon S3 devuelve un documento XML con un código de estado 201. Para obtener información acerca del contenido del documento XML, consulte POST Object. Si el valor no se establece o si se establece en un valor no válido, Amazon S3 devuelve un documento vacío con un código de estado 204. notaAlgunas versiones de Adobe Flash Player no controlan debidamente las respuestas HTTP con un cuerpo vacío. Para admitir cargas con Adobe Flash, recomendamos establecer |
No |
signature |
La firma HMAC que se crea con la clave de acceso secreta que corresponde al AWSAccessKeyId provisto. Este campo es obligatorio si se incluye un documento de política en la solicitud. Para obtener más información, consulte Identity and Access Management en Amazon S3. |
Condicional |
x-amz-security-token |
Un token de seguridad utilizado por las credenciales de sesión Si la solicitud utiliza Amazon DevPay, se requieren dos campos de formulario Si la solicitud utiliza credenciales de sesión, se requiere un formulario |
No |
| Otros nombres de archivo con prefijos x-amz-meta- |
Metadatos especificados por el usuario. Amazon S3 no valida ni utiliza estos datos. Para obtener más información, consulte PUT Object. |
No |
| file |
Contenido de texto o archivo. El archivo o el contenido debe ser el último campo en el formulario. Cualquier campo debajo de estos se ignora. No puede cargar más de un archivo a la vez. |
Sí |
Construcción de la política
La política es un documento JSON con codificación UTF-8 y Base64 que especifica las condiciones que debe cumplir la solicitud, y se utiliza para autenticar el contenido. Según cómo diseñe sus documentos de política, puede utilizarlos por carga, por usuario, para todas las cargas o de acuerdo con otros diseños que se ajusten a sus necesidades.
nota
Si bien el documento de política es opcional, lo recomendamos ampliamente en lugar de hacer un bucket que se pueda escribir públicamente.
A continuación se muestra el ejemplo de un documento de política:
{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ {"acl": "public-read" }, {"bucket": "awsexamplebucket1" }, ["starts-with", "$key", "user/eric/"], ] }
El documento de política incluye los vencimientos y las condiciones.
Expiration
El elemento de vencimiento especifica la fecha de vencimiento de la política en el formato de fecha según la norma ISO 8601 en Universal Time Coordinated (UTC, Hora universal coordinada). Por ejemplo, “2007-12-01T12:00:00.000Z” especifica que la política no es válida después de la medianoche, UTC, del 01/12/2007. El vencimiento es obligatorio en una política.
Condiciones
Las condiciones en el documento de política validan los contenidos del objeto cargado. Cada campo de formulario que especifica en el formulario (salvo AWSAccessKeyId, firma, archivo, política y nombres de archivos que tienen un prefijo x-ignore-) se debe incluir en la lista de condiciones.
nota
Si tiene varios campos con el mismo nombre, los valores deben estar separados por comas. Por ejemplo, si tiene dos campos denominados “x-amz-meta-tag” y el primero tiene el valor “Ninja” y el segundo tiene el valor “Stallman”, configurará el documento de política como Ninja,Stallman.
Todas las variables en el formulario se expanden antes de que la política se valide. Por lo tanto, se deben realizar todas las coincidencias de condiciones con respecto a los campos expandidos. Por ejemplo, si configuró el campo de clave en user/betty/${filename}, su política puede ser [
"starts-with", "$key", "user/betty/" ]. No escriba [
"starts-with", "$key", "user/betty/${filename}" ]. Para obtener más información, consulte Coincidencia de condiciones.
En la siguiente tabla se describen las condiciones de los documentos de política.
| Nombre del elemento | Descripción |
|---|---|
| acl |
Especifica las condiciones que debe cumplir la ACL. Admite las coincidencias exactas y |
| content-length-range |
Especifica el tamaño mínimo y máximo permitido para el contenido cargado. Admite la coincidencia de rango. |
| Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires |
Encabezados específicos de REST. Admite las coincidencias exactas y |
| clave |
El nombre de la clave cargada. Admite las coincidencias exactas y |
| success_action_redirect, redirect |
URL al que el cliente es redirigido después de la carga exitosa. Admite las coincidencias exactas y |
| success_action_status |
El código de estado que recibe el cliente después de la carga exitosa si no se especifica el campo success_action_redirect. Admite las coincidencias exactas. |
| x-amz-security-token |
Token de seguridad de Amazon DevPay. Cada solicitud que utiliza Amazon DevPay requiere dos campos de formulario |
| Otros nombres de archivo con prefijos x-amz-meta- |
Metadatos especificados por el usuario. Admite las coincidencias exactas y |
nota
Si su conjunto de herramientas añade campos adicionales (p. ej., Flash añade el nombre de archivo), debe añadirlos al documento de política. Si puede controlar esta funcionalidad, añada el prefijo x-ignore- al campo para que Amazon S3 omita la característica y no afecte futuras versiones de esta característica.
Coincidencia de condiciones
En la siguiente tabla se describen los tipos de coincidencias de condiciones. Si bien debe especificar una condición para cada campo de formulario que especifica en el formulario, puede crear criterios de coincidencia más complejos especificando varias condiciones para un campo de formulario.
| Condición | Descripción |
|---|---|
|
Coincidencias exactas |
Las coincidencias exactas verifican que los campos coincidan con valores específicos. En este ejemplo se indica que la ACL se debe establecer en public-read:
Este ejemplo es una alternativa para indicar que la ACL se debe establecer en public-read:
|
|
Empieza por |
Si el valor debe empezar con un valor determinado, utilice starts-with. En este ejemplo se indica que la clave debe empezar con user/betty:
|
|
Coincidencia con cualquier contenido |
Para configurar la política para permitir cualquier contenido dentro de un campo, utilice starts-with con un valor vacío. Este ejemplo permite cualquier campo success_action_redirect:
|
|
Especificación de rangos |
Para campos que aceptan rangos, separe los rangos superiores e inferiores con una coma. Este ejemplo permite un tamaño de archivo de 1 a 10 megabytes:
|
Secuencia de escape de caracteres
En la siguiente tabla se describen los caracteres a los que se debe aplicar una secuencia de escape en un documento de política.
| Secuencia de escape | Descripción |
|---|---|
|
\\ |
Barra inversa |
|
\$ |
Signo de dólar |
|
\b |
Retroceso |
|
\f |
Salto de página |
|
\n |
Nueva línea |
|
\r |
Salto de línea |
|
\t |
Tabulador horizontal |
|
\v |
Tabulador vertical |
|
\u |
Todos los caracteres Unicode |
Crear una firma
| Paso | Descripción |
|---|---|
| 1 |
Codifique la política con UTF-8. |
| 2 |
Codifique los bytes de UTF-8 con Base64. |
| 3 |
Firme la política con su clave de acceso secreta mediante el uso del algoritmo HMAC SHA-1. |
| 4 |
Codifique la firma de SHA-1 con Base64. |
Para obtener más información acerca de la autenticación, consulte Identity and Access Management en Amazon S3.
Redireccionamiento
En esta sección se describe cómo administrar los direccionamientos.
Redireccionamiento general
Al finalizar la solicitud POST, el usuario es redirigido a la ubicación que especificó en el campo success_action_redirect. Si Amazon S3 no puede interpretar la URL, ignora el campo success_action_redirect.
Si no se especifica el campo success_action_redirect, Amazon S3 devuelve el tipo de documento vacío especificado en el campo success_action_status.
Si la solicitud POST falla, Amazon S3 muestra un error y no proporciona un redireccionamiento.
Redireccionamiento de carga previa
Si su bucket se creó con <CreateBucketConfiguration>, sus usuarios finales pueden necesitar una redirección. Si esto sucede, algunos navegadores pueden administrar la redirección de manera incorrecta. Esto es relativamente poco frecuente, pero es muy probable que suceda inmediatamente después de que se crea un bucket.
