View a markdown version of this page

Criação de um formulário HTML (usando o AWS Signature Version 4) - Amazon Simple Storage Service
Declaração de formulário HTMLCampos do formulário HTML

Criação de um formulário HTML (usando o AWS Signature Version 4)

Para permitir que os usuários façam upload de conteúdo no Amazon S3 usando os navegadores (solicitações HTTP POST), 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 do formulário contêm informações detalhadas da solicitação.

Esta seção descreve como criar formulários HTML. Para obter um exemplo prático de upload baseado no navegador usando HTTP POST e cálculos de assinatura relacionados para autenticação de solicitações, consulte Exemplo: upload baseado no navegador usando HTTP POST (usando o AWS Signature Version 4).

O formulário e a política devem ser codificados em UTF-8. Aplique a codificação UTF-8 no formulário especificando charset=UTF-8 no atributo content. Confira 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>

Confira a seguir um exemplo de codificação UTF-8 em um cabeçalho de solicitação.

Content-Type: text/html; charset=UTF-8
nota

Os dados e os limites do formulário (excluindo o conteúdo do arquivo) não podem exceder 20 KB.

Declaração de formulário HTML

A declaração do formulário HTML tem os três atributos a seguir:

  • action: 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 examplebucket, o URL será http://examplebucket.s3.amazonaws.com/.

    nota

    O nome chave é especificado em um campo do formulário.

  • method: o método deve ser POST.

  • enctype: o tipo de compartimento (enctype) deve ser definido como multipart/form-data para uploads de arquivos e de áreas de texto. Para obter mais informações sobre enctype, consulte RFC 1867.

Essa é uma declaração de formulário para o bucket examplebucket.

<form action="http://examplebucket.s3.amazonaws.com/" method="post"

enctype="multipart/form-data">

Campos do formulário HTML

A tabela a seguir descreve uma lista de campos que podem ser usados em um formulário. Entre outros campos, há um campo de assinatura que você pode usar para autenticar solicitações. Há campos para você especificar o algoritmo de cálculo da assinatura (x-amz-algorithm), o escopo da credencial (x-amz-credential) que você usou para gerar a chave de assinatura e a data (x-amz-date) usada para calcular a assinatura. O Amazon S3 usa essas informações para recriar a assinatura. Se as assinaturas corresponderem, o Amazon S3 processará a solicitação.

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 fornecer 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.

Se você não fornecer os elementos necessários para solicitações autenticadas, como o elemento policy, a solicitação será considerada anônima e só será bem-sucedida se você tiver configurado o bucket para leitura e gravação públicas.

Nome do elemento Descrição Obrigatório
acl

Uma lista de controle de acesso (ACL) do Amazon S3. Se uma ACL inválida for especificada, o Amazon S3 negará a solicitação. Consulte mais informações sobre ACLs em Uso de ACLs do Amazon S3.

Tipo: string

Padrão: privado

Valores válidos: private | public-read | public-read-write | aws-exec-read | authenticated-read | bucket-owner-read | bucket-owner-full-control

Não
Cache-Control

Content-Type

Content-Disposition

Content-Encoding

Expires

Cabeçalhos específicos para REST. Para obter mais informações, consulte PutObject.

Não
key

O nome da chave do objeto carregado.

Para usar o nome de arquivo fornecido pelo usuário, use a variável ${filename}. Por exemplo, se você fizer upload de um arquivo photo1.jpg e especificar /user/user1/${filename} como nome da chave, o arquivo será armazenado como /user/user1/photo1.jpg.

Para obter mais informações, consulte Chave e metadados de objeto no Guia do usuário do Amazon Simple Storage Service.

Sim
policy

Política de segurança com codificação base64 que descreve o que é permitido na solicitação. Para solicitações autenticadas, é necessária uma política.

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.

Obrigatório para solicitações autenticadas
success_action_redirect

O URL para o qual o cliente é redirecionado após um upload bem-sucedido.

Se success_action_redirect não for especificado ou o Amazon S3 não conseguir interpretar o URL, o Amazon S3 retornará o tipo de documento vazio especificado no campo success_action_status.

Se houver falha no upload, o Amazon S3 retornará um erro e não redirecionará o usuário para outro URL.

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 o código de status especificado.

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 inválido, o Amazon S3 retornará um documento vazio com um código de status 204.

nota

Algumas 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 success_action_status como 201.

Não
x-amz-algorithm

O algoritmo de assinatura usado para autenticar a solicitação. Para AWS Signature Version 4, o valor é AWS4-HMAC-SHA256.

Este campo é necessário se um documento de política estiver incluso na solicitação.

Obrigatório para solicitações autenticadas
x-amz-credential

Além do ID da chave de acesso, esse campo também fornece informações de escopo que identificam a região e o serviço para os quais a assinatura é válida. Deve ser o mesmo escopo usado no cálculo da chave de assinatura para o cálculo da assinatura.

É uma string da seguinte forma:

<your-access-key-id>/<date>/<aws-region>/<aws-service>/aws4_request

Por exemplo:

AKIAIOSFODNN7EXAMPLE/20130728/us-east-1/s3/aws4_request

Para o Amazon S3, a string aws-service é s3. Para conferir a lista de strings aws-region do Amazon S3, consulte Regiões e endpoints na Referência geral da AWS. Será obrigatório se um documento de política estiver incluso na solicitação.

Obrigatório para solicitações autenticadas
x-amz-date

É o valor de data no formato ISO8601. Por exemplo, 20130728T000000Z.

É a mesma data que você usou para criar a chave de assinatura (por exemplo, 20130728). Também deve ser o mesmo valor fornecido na política (x-amz-date) que você assinou.

Será obrigatório se um documento de política estiver incluso na solicitação.

Obrigatório para solicitações autenticadas
x-amz-security-token

Um token de segurança usado pelo Amazon DevPay e por credenciais de sessão

Se a solicitação estiver usando o Amazon DevPay, serão necessários dois campos do formulário x-amz-security-token: um para o token de produto e outro para o token de usuário. Para obter mais informações, consulte Uso do DevPay no Guia do usuário do Amazon Simple Storage Service.

Se a solicitação estiver usando credenciais de sessão, será necessário um formulário x-amz-security-token. Para obter mais informações, consulte Solicitação de credenciais de segurança temporárias no Manual do usuário do IAM.

Não
x-amz-signature

(AWS Signature Version 4) O hash HMAC-SHA256 da política de segurança.

Este campo é necessário se um documento de política estiver incluso na solicitação.

Obrigatório para solicitações autenticadas
x-amz-meta-*

Os nomes de campo que começam com esse prefixo são metadados definidos pelo usuário. Cada um é armazenado e retornado como um conjunto de pares de chave-valor. O Amazon S3 não valida nem interpreta metadados definidos pelo usuário. Para obter mais informações, consulte PutObject.

Não
x-amz-*

Consulte Objeto POST (Objeto POST para outros cabeçalhos x-amz-*).

Não
file

Conteúdo de arquivo ou texto.

O arquivo ou conteúdo deve ser o último campo no formulário.

Não carregue mais de um arquivo por vez.

Sim

Itens condicionais são necessários para solicitações autenticadas e são opcionais para solicitações anônimas.

Agora que você já sabe como criar formulários, vai aprender a criar uma política de segurança que possa ser assinada. Para obter mais informações, consulte Política de POST.