:PostObject

Introdução

O PostObject faz upload de arquivos para o OSS por meio de formulários. Nessa operação, a codificação das entidades de mensagem usa o formato multipart/form-data. Para mais informações, consulte RFC 2388. Diferentemente do Put Object, que transmite parâmetros via headers HTTP, o Post Object envia os parâmetros como campos de formulário no corpo da mensagem.

Uma mensagem PostObject contém header e body, separados por \r\n--{boundary}. O body inclui uma série de campos de formulário no seguinte formato: Content-Disposition: form-data; name="{key}"\r\n\r\n{value}\r\n--{boundary}.

Os headers mais comuns incluem Host, User-Agent, Content-Length, Content-Type e Content-MD5. Os campos de formulário abrangem key, OSSAccessKeyId, Signature, Content-Disposition, metadados do objeto (x-oss-meta-*), x-oss-security-token, outros headers HTTP (Cache-Control/Content-Type/Cache-Control/Content-Type/Content-Disposition/Content-Encoding/Expires/Content-Encoding/Expires) e file. O campo file deve ser obrigatoriamente o último entre os campos de formulário.

Para mais informações, consulte Post Object.

Erros comuns do PostObject

A tabela a seguir lista os erros mais frequentes no PostObject:

• Formato de campos de formulário do PostObject

  Observe os seguintes pontos sobre o formato das requisições PostObject:

  • O header deve incluir Content-Type: multipart/form-data; boundary={boundary}.

  • O header e o body são separados por \r\n--{boundary}.

  • Formato do campo de formulário:

    Content-Disposition: form-data;
            name="{key}"\r\n\r\n{value}\r\n--{boundary}

  • Os nomes dos campos de formulário diferenciam maiúsculas de minúsculas, como policy, key, file, OSSAccessKeyId, OSSAccessKeyId e Content-Disposition.

    Importante

    O campo de formulário file deve ser obrigatoriamente o último campo do formulário.

  • Quando o valor de bucket for public-read-write, não é necessário especifique os campos de formulário OSSAccessKeyId, policy e Signature. Caso você especifique qualquer um desses três campos, informe também os outros dois, independentemente de o bucket ser public-read-write ou não.

  Veja a seguir um exemplo de requisição PostObject:

  POST / HTTP/1.1
  User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
  Content-Type: multipart/form-data; boundary=9431149156168
  Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
  Accept: text/html, image/gif, image/jpeg, *; q=. 2, */*; q=. 2
  Connection: keep-alive
  Content-Length: 5052
  -- 9431149156168
  Content-Disposition: form-data; name="key"
  test-key
  --9431149156168
  Content-Disposition: form-data; name="Content-Disposition"
  attachment;filename=D:\img\1.png
  --9431149156168
  Content-Disposition: form-data; name="OSSAccessKeyId"
  2NeL********j2Eb

  Nota

  • Na requisição de exemplo anterior, \r\n indica uma nova linha (line feed). O mesmo se aplica aos exemplos subsequentes.

  • A requisição de exemplo acima está incompleta. Para visualizar a requisição completa, consulte Post Object.

  Em caso de dúvidas, consulte os códigos de exemplo:

  • C#

  • Java

• Formato de política do PostObject

  Em uma requisição PostObject, o campo de formulário policy valida a requisição e declara as condições obrigatórias. Essas condições são:

  • Codifique o texto json em UTF-8 para base64 antes de insira-lo no campo de formulário policy.

  • A policy deve conter expiration e conditions. O campo conditions precisa ter pelo menos um item.

  O exemplo abaixo mostra uma policy antes da codificação base64.

  
     {
      "expiration": "2018-01-01T12:00:00.000Z",
      "conditions": [
          ["content-length-range", 0, 104857600]
      ]
  }

  O item expiration define o tempo de expiração da requisição no formato ISO8601 GMT. Por exemplo, 2018-01-01T12:00:00.000Z determina que a requisição deve ocorrer antes das 12h00 de 1º de janeiro de 2018.

  O PostPolicy aceita as seguintes "conditions":

  Nome	Descrição	Exemplo
  bucket	Nome do bucket do arquivo enviado. Suporta correspondência exata.	{“bucket”: “johnsmith” } ou [“eq”, “$bucket”, “johnsmith”]
  key	Nome do arquivo enviado. Suporta correspondência exata e por prefixo.	[“starts-with”, “$key”, “user/etc/”]
  content-length-range	Tamanhos máximo e mínimo permitidos para o arquivo enviado.	[“content-length-range”, 0, 104857600]
  x-oss-meta-*	Metadados do objeto especificados. Suporta correspondência exata e por prefixo.	[“starts-with”, “$x-oss-meta-prop”, “prop-“]
  success_action_redirect	URL de redirecionamento após upload bem-sucedido. Suporta correspondência exata e por prefixo.	[“starts-with”, “$success_action_redirect”, “http://www.aliyun.com”]
  success_action_status	Código de status retornado após upload bem-sucedido, caso success_action_redirect não seja especificado. Suporta correspondência exata e por prefixo.	[“eq”, “$success_action_status”, “204”]
  Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires, entre outros	Headers HTTP transmitidos como campos de formulário. Suporta correspondência exata e por prefixo.	[“eq”, “$Content-Encoding”, “ZLIB”]

  O PostPolicy aceita os seguintes caracteres de escape e utiliza \ para o escape.

  Caractere de escape	Descrição
  /	Barra
  \	Barra invertida
  “	Aspas duplas
  $	Cifrão
  \b	Espaço em branco
  \f	Form feed
  \n	Line feed
  \r	Enter
  \t	Tabulação horizontal
  \uxxxx	Caractere Unicode

  Para mais detalhes sobre o PostPolicy, consulte Post Policy.

• Assinatura do PostObject

  Para validar uma requisição Post, inclua os campos de formulário AccessKeyID, policy e Signature. O processo de cálculo da assinatura é o seguinte:

  1. Crie uma política codificada em UTF-8.

  2. Codifique a política em base64. O resultado será o valor a ser preenchido no campo de formulário policy e servirá como string a ser assinada.

  3. Assine a string com o AccessKeySecret. Para isso, aplique o hash hmac-sha1 na string e codifique o resultado em base64. O método de assinatura é idêntico ao descrito em Header Signature.

  Ou seja:

  Signature = base64(hmac-sha1(AccessKeySecret, base64(policy)))

  Especifique a assinatura calculada no campo de formulário Signature conforme abaixo:

  Content-Disposition: form-data; name="Signature"
  {signature}
  -- 9431149156168

  Em caso de dúvidas, consulte os códigos de exemplo:

  • C#

  • Java

Perguntas frequentes

• Como especifique uma key?

  A key corresponde ao nome do objeto e é definida no campo de formulário key. Veja o exemplo:

  Content-Disposition: form-data; name="key"
  {key}
  --9431149156168

• Como especifique o conteúdo do objeto?

  Defina o conteúdo do objeto no campo de formulário file. Confira o exemplo:

  Content-Disposition: form-data; name="file"; filename="images.png"
  Content-Type: image/png
  {File-content}
  -- 9431149156168

  Nota

  • O campo de formulário file deve ser sempre o último, posicionado após todos os demais campos.

  • O parâmetro filename refere-se ao nome do arquivo local enviado, e não ao nome do objeto.

• Como especifique o content-type do objeto?

  Informe o content-type do objeto no campo de formulário file, e não no content-type do header. Exemplo:

  Content-Disposition: form-data; name="file"; filename="images.png"
  Content-Type: image/png
  {file-content}
  --9431149156168

• Como configurar a verificação content-md5 para o conteúdo do objeto?

  Especifique o content-md5 no header da requisição Post Object. Lembre-se de que o valor MD5 abrange todo o body, ou seja, todos os campos de formulário. Exemplo de header de requisição:

  POST / HTTP/1.1
  User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; zh-CN; rv:1.9.2.6)
  Content-Type: multipart/form-data; boundary = 9431149156168
  Content-MD5: tdqHe4hT/TuKb7Y4by+nJg==
  Host: mingdi-hz.oss-cn-hangzhou.aliyuncs.com
  Accept: text/html, image/gif, image/jpeg, *; q=. 2, */*; q=. 2
  Connection: keep-alive
  Content-Length: 5246
  --9431149156168

• Como definir uma assinatura?

  Consulte a seção Assinatura do PostObject para entender o método de cálculo. A assinatura é transmitida no campo de formulário Signature.

• Como implementar o Post Object com o STS Token de um usuário temporário?

  O uso do AccessKeyID e AccessKeySecret de um usuário temporário segue a mesma lógica das chaves de usuário principal e subusuário. Informe o Token no campo de formulário x-oss-security-token. Veja o exemplo:

  Content-Disposition: form-data; name="Signature"
  5L0+KaeugxYygfqWLJLoy0ehOmA=
  --9431149156168
  Content-Disposition: form-data; name="x-oss-security-token"
  {Token}
  --9431149156168

• Como configurar um callback?

  Transmita o callback pelo campo de formulário callback. Exemplo:

  Content-Disposition: form-data; name="callback"
  eyJjYWxsYmFja0JvZHlUeXBlIjogImFwcGxpY2F0aW9uL3gtd3d3LWZvcm0tdXJsZW5jb2RlZCIsICJjYWxsYmFja0JvZHkiOiAiZmlsZW5hbWU9JHtvYmplY3R9JnNpemU9JHtzaXplfSZtaW1lVHlwZT0ke21pbWVUeXBlfSIsICJjYWxsYmFja1VybCI6ICJodHRwOi8vb3NzLWRlbW8uYWxpeXVuY3MuY29tOjIzNDUwIn0=
  --9431149156168

  Envie também parâmetros personalizados do callback via campos de formulário. Exemplo:

  Content-Disposition: form-data; name="x:var1"
  {var1-value}
  --9431149156168

• Como especifique o Content-Transfer-Encoding?

  Defina o Content-Transfer-Encoding no campo de formulário file. Abaixo, um exemplo do campo file:

  Content-Disposition: form-data; name="file"; filename="images.png"
  Content-Type: image/png
  Content-Transfer-Encoding: base64
  {file-content}
  --9431149156168

• Como definir metainformações personalizadas Object User Meta?

  Informe as metainformações personalizadas nos campos de formulário. Exemplo:

  Content-Disposition: form-data; name="x-oss-meta-uuid"
  {uuid}
  --9431149156168
  Content-Disposition: form-data; name="x-oss-meta-tag"
  {tag}
  --9431149156168

  Nota

  Para mais informações sobre metainformações de arquivo, consulte Metainformações de arquivo Object Meta.

• Como especifique condições como expiration, Key, Bucket, tamanho e header?

  O PostObject para OSS aceita diversas condições e atende a rigorosos requisitos de segurança. Defina as condições no campo de formulário policy. Exemplo de política:

  {
      "expiration": "2018-01-01T12:00:00.000Z",
      "conditions": [
          ["eq", "$bucket", "md-hz"],
          ["starts-with", "$key", "md/conf/"],
          ["content-length-range", 0, 104857600]
      ]
  }

  Na política acima, as condições para operações Post Object do usuário são:

  • O bucket deve ser md-hz.

  • A key deve começar com md/conf/.

  • O tamanho do arquivo enviado deve ser inferior a 100 MB.

  • A requisição deve ocorrer antes de 2018-01-01T12:00:00.000Z.

• Como especifique headers HTTP como Cache-Control, Content-Type, Content-Disposition, Content-Encoding e Expires?

  Defina os headers HTTP, incluindo Cache-Control, Content-Type, Content-Disposition, Content-Encoding e Expires, diretamente nos campos de formulário. Para o significado desses headers HTTP, consulte RFC2616. No entanto, especifique o Content-MD5 no Header do Post.

Exemplos de Post Object

Link útil