Formulários HTML (AWS Signature Version 2)
Tópicos
Ao se comunicar com o Amazon S3, você normalmente usa as APIs REST ou SOAP para executar as operações “put”, “get”, “delete”, entre outras. Com POST, os usuários fazem upload dos dados diretamente para o Amazon S3 por meios dos navegadores, que não são capazes de processar a API SOAP ou criar uma solicitação PUT de REST.
nota
O suporte a SOAP via HTTP está obsoleto, mas o SOAP continua disponível via HTTPS. Os novos recursos do Amazon S3 não são compatíveis com SOAP. Em vez de SOAP, recomendamos usar a API REST ou os AWS SDKs.
Para permitir que os usuários façam upload de conteúdo para o Amazon S3 usando os navegadores, use formulários HTML. Os formulários HTML são formados por uma declaração de formulário e campos de formulário. A declaração de formulário contém informações de alto nível sobre a solicitação. Os campos de formulário contêm informações detalhadas sobre a solicitação, bem como a política usada para autenticá-la e garantir que ela satisfaça as condições especificadas.
nota
Os dados e os limites do formulário (excluindo o conteúdo do arquivo) não podem exceder 20 KB.
Esta seção explica como usar formulários HTML.
Codificação do formulário HTML
O formulário e a política devem ser codificados em UTF-8. Aplique a codificação UTF-8 no formulário especificando isso no cabeçalho HTML ou como um cabeçalho de solicitação.
nota
A declaração de formulário HTML não aceita parâmetros de autenticação por query string.
A seguir um exemplo de codificação UTF-8 no cabeçalho HTML:
<html> <head> ... <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> ... </head> <body>
A seguir um exemplo de codificação UTF-8 em um cabeçalho de solicitação:
Content-Type: text/html; charset=UTF-8
Declaração do formulário HTML
A declaração de formulário tem três componentes: a ação, o método e o tipo de compartimento. Se qualquer um desses valores for definido de maneira incorreta, a solicitação falhará.
A ação especifica o URL que processa a solicitação, que deve ser definido como o URL do bucket. Por exemplo, se o nome do seu bucket for awsexamplebucket1 e a região for Oeste dos EUA (Norte da Califórnia), o URL será https://awsexamplebucket1.s3.us-west-1.amazonaws.com/.
nota
O nome chave é especificado em um campo do formulário.
O método deve ser POST.
O tipo de compartimento (enctype) deve ser especificado e definido como multipart/form-data para uploads de arquivos e de áreas de texto. Para obter mais informações, acesse RFC 1867
exemplo
O exemplo a seguir é uma declaração de formulário para o bucket "awsexamplebucket1".
<form action="https://awsexamplebucket1.s3.us-west-1.amazonaws.com/" method="post" enctype="multipart/form-data">
Campos do formulário HTML
A tabela a seguir descreve os campos que podem ser usados em um formulário HTML.
nota
A variável ${filename} é substituída automaticamente pelo nome do arquivo fornecido pelo usuário e é reconhecida por todos os campos do formulário. Se o navegador ou o cliente fornece um caminho completo ou parcial para o arquivo, apenas o texto que vem depois da última barra (/) ou barra invertida (\) será usado. Por exemplo, "C:\Program Files\directory1\file.txt" será interpretado como "file.txt". Se nenhum arquivo ou nome de arquivo for fornecido, a variável será substituída por uma string vazia.
| Nome do campo | Descrição | Obrigatório |
|---|---|---|
AWSAccessKeyId |
O ID da chave de acesso da AWS do proprietário do bucket que concede acesso a um usuário anônimo para uma solicitação que satisfaz o conjunto de restrições na política. Este campo é necessário se a solicitação inclui um documento de política. |
Condicional |
acl |
Uma lista de controle de acesso (ACL) do Amazon S3. Se uma lista de controle de acesso inválida for especificada, um erro será gerado. Para obter mais informações sobre as ACLs, consulte Listas de controle de acesso (ACLs). Type: string Padrão: privado Valores válidos: |
Não |
Cache-Control, Content-Type, Content-Disposition,
Content-Encoding, Expires |
Cabeçalhos específicos para REST. Para obter mais informações, consulte Objeto PUT. |
Não |
key |
O nome da chave carregada. Para usar o nome de arquivo fornecido pelo usuário, use a variável ${filename}. Por exemplo, se o usuário Betty carrega o arquivo lolcatz.jpg e você especifica /user/betty/${filename}, o arquivo é armazenado como /user/betty/lolcatz.jpg. Para obter mais informações, consulte Trabalhar com metadados de objeto. |
Sim |
policy |
Política de segurança que descreve o que é permitido na solicitação. As solicitações sem uma política de segurança são consideradas anônimas e terão sucesso apenas em buckets com gravação pública. |
Não |
success_action_redirect, redirect |
O URL para o qual o cliente é redirecionado após um upload bem-sucedido. O Amazon S3 anexa os valores de bucket, chave e etag como parâmetros de query string ao URL. Se success_action_redirect não for especificado, o Amazon S3 retornará o tipo de documento vazio especificado no campo success_action_status. Se o Amazon S3 não for capaz de interpretar o URL, o campo será ignorado. Se houver falha no upload, o Amazon S3 exibirá um erro e não redirecionará o usuário para um URL. Para obter mais informações, consulte Redirecionamento. notaO nome do campo de redirecionamento está obsoleto e o suporte para ele será removido no futuro. |
Não |
success_action_status |
O código de status retornado ao cliente após o upload bem-sucedido se success_action_redirect não for especificado. Os valores válidos são 200, 201 ou 204 (padrão). Se o valor estiver definido como 200 ou 204, o Amazon S3 retornará um documento vazio com um código de status 200 ou 204. Se o valor estiver definido como 201, o Amazon S3 retornará um documento XML com um código de status 201. Para obter informações sobre o conteúdo do documento XML, consulte Objeto POST. Se o valor não estiver definido ou for um valor inválido, o Amazon S3 retornará um documento vazio com um código de status 204. notaAlgumas versões do Adobe Flash Player não lidam muito bem com respostas HTTP com um corpo vazio. Para oferecer suporte a uploads por meio do Adobe Flash, recomendamos definir |
Não |
signature |
A assinatura HMAC criada com a chave de acesso secreta correspondente ao AWSAccessKeyId fornecido. Este campo é necessário se um documento de política estiver incluso na solicitação. Para obter mais informações, consulte Identity and Access Management no Amazon S3. |
Condicional |
x-amz-security-token |
Um token de segurança usado por credenciais de sessão Se a solicitação estiver usando o Amazon DevPay, serão necessários dois campos do formulário Se a solicitação estiver usando credenciais de sessão, será necessário um formulário |
Não |
| Outros nomes de campos com o prefixo x-amz-meta- |
Metadados especificados pelo usuário. O Amazon S3 não valida ou usa esses dados. Para obter mais informações, consulte Objeto PUT. |
Não |
| file |
Conteúdo de arquivo ou texto. O arquivo ou conteúdo deve ser o último campo no formulário. Todos os campos abaixo deles serão ignorados. Não carregue mais de um arquivo por vez. |
Sim |
Criação de política
A política é um documento JSON codificado em Base64 e UTF-8 que especifica as condições que a solicitação deve satisfazer, sendo usado para autenticar o conteúdo. Dependendo de como os documentos de política forem elaborados, eles podem ser usados por upload, por usuário, para todos os uploads ou de acordo com outros formatos que atendam as suas necessidades.
nota
Embora o documento de política seja opcional, o recomendamos fortemente em vez de tornar um bucket aberto ao público para gravação.
Veja a seguir um exemplo de um documento de política:
{ "expiration": "2007-12-01T12:00:00.000Z", "conditions": [ {"acl": "public-read" }, {"bucket": "awsexamplebucket1" }, ["starts-with", "$key", "user/eric/"], ] }
O documento de política contém a expiração e as condições.
Expiração
O elemento expiração especifica a data de expiração da política no formato de data UTC ISO 8601. Por exemplo, "2007-12-01T12:00:00.000Z" especifica que a política não tem mais validade depois da meia-noite UTC do dia 1° de dezembro de 2007. A expiração é necessária em uma política.
Condições
As condições no documento de política validam o conteúdo do objeto carregado. Cada campo especificado no formulário (exceto AWSAccessKeyId, assinatura, arquivo, política e nomes de campos com o prefixo x-ignore-) deve estar incluso na lista de condições.
nota
Caso existam vários campos com o mesmo nome, os valores devem ser separados por vírgulas. Por exemplo, se existem dois campos chamados "x-amz-meta-tag", o primeiro tem o valor "Ninja" e o segundo tem o valor "Stallman", o documento de política seria definido como Ninja,Stallman.
Todas as variáveis dentro do formulário são expandidas antes da validação da política. Portanto, qualquer correspondência de condição deve ser realizada nos campos expandidos. Por exemplo, se o campo chave for definido como user/betty/${filename}, a política deve ser [
"starts-with", "$key", "user/betty/" ]. Não insira [
"starts-with", "$key", "user/betty/${filename}" ]. Para obter mais informações, consulte Correspondência de condição.
A tabela a seguir descreve as condições do documento de política.
| Nome do elemento | Descrição |
|---|---|
| acl |
Especifica as condições que a ACL deve satisfazer. Oferece suporte à correspondência exata e a |
| content-length-range |
Especifica os tamanhos mínimo e máximo permitidos para o conteúdo carregado. Oferece suporte à correspondência por intervalo. |
| Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires |
Cabeçalhos específicos para REST. Oferece suporte à correspondência exata e a |
| chave |
O nome da chave carregada. Oferece suporte à correspondência exata e a |
| success_action_redirect, redirect |
O URL para o qual o cliente é redirecionado após um upload bem-sucedido. Oferece suporte à correspondência exata e a |
| success_action_status |
O código de status retornado ao cliente após o upload bem-sucedido se success_action_redirect não for especificado. Oferece suporte à correspondência exata. |
| x-amz-security-token |
Token de segurança do Amazon DevPay. Cada solicitação que usa o Amazon DevPay requer dois campos do formulário |
| Outros nomes de campos com o prefixo x-amz-meta- |
Metadados especificados pelo usuário. Oferece suporte à correspondência exata e a |
nota
Se o seu toolkit traz campos adicionais (por exemplo, o Flash adiciona nome do arquivo), é necessário adicioná-los ao documento de política. Se essa funcionalidade puder ser controlada, adicione o prefixo x-ignore- ao campo para que o Amazon S3 ignore o recurso e para que futuras versões não sejam afetadas.
Correspondência de condição
A tabela a seguir descreve os tipos de correspondência de condição. Embora seja necessário especificar uma condição para cada campo especificado no formulário, é possível criar critérios de correspondência mais complexos especificando várias condições para um campo.
| Condição | Descrição |
|---|---|
|
Correspondências exatas |
Correspondências exatas verificam se os campos correspondem a valores específicos. Este exemplo indica que a ACL deve ser definida como pública para leitura:
Este exemplo é uma forma alternativa para indicar que a ACL deve ser definida como pública para leitura:
|
|
Inicia com |
Se o valor deve iniciar com um certo valor, use starts-with. Este exemplo indica que a chave deve iniciar com user/betty:
|
|
Corresponder qualquer conteúdo |
Para configurar a política para permitir qualquer conteúdo em um campo, use starts-with com um valor vazio. Este exemplo permite qualquer success_action_redirect:
|
|
Especificar intervalos |
Para os campos que aceitam intervalos, separe os limites superior e inferior do intervalo com uma vírgula. Este exemplo permite um tamanho de arquivo entre 1 e 10 megabytes:
|
Caracteres de escape
A tabela a seguir descreve os caracteres de escape dentro de um documento de política.
| Sequência de escape | Descrição |
|---|---|
|
\\ |
Barra invertida |
|
\$ |
Sinal de dólar |
|
\b |
Apagar |
|
\f |
Feed do formulário |
|
\n |
Nova linha |
|
\r |
Carriage return |
|
\t |
Guia horizontal |
|
\v |
Guia vertical |
|
\u |
Todos os caracteres do Unicode |
Criar uma assinatura
| Etapa | Descrição |
|---|---|
| 1 |
Codifique a política usando UTF-8. |
| 2 |
Codifique os bytes UTF-8 usando Base64. |
| 3 |
Assine a política com a chave de acesso secreta usando HMAC SHA-1. |
| 4 |
Codifique a assinatura SHA-1 usando Base64. |
Para obter informações gerais sobre a autenticação, consulte Identity and Access Management no Amazon S3.
Redirecionamento
Esta seção descreve como manipular redirecionamentos.
Redirecionamento geral
Após a conclusão da solicitação POST, o usuário é redirecionado para o local especificado no campo success_action_redirect. Se o Amazon S3 não for capaz de interpretar o URL, o campo success_action_redirect será ignorado.
Se success_action_redirect não for especificado, o Amazon S3 retornará o tipo de documento vazio especificado no campo success_action_status.
Se houver falha na solicitação POST, o Amazon S3 exibirá um erro e não fará o redirecionamento.
Redirecionamento pré-upload
Se o bucket foi criado usando <CreateBucketConfiguration>, os usuários finais poderão exigir um redirecionamento. Se isso ocorrer, alguns navegadores podem manipular o redirecionamento de maneira incorreta. Isso é relativamente raro, mas é mais provável que ocorra logo após a criação do bucket.
