:PostObject

Introdução

O PostObject faz upload de arquivos para o OSS usando formulários. No PostObject, as entidades de mensagem são codificadas no formato multipart/form-data. Para mais informações, consulte RFC 2388. No PutObject, os parâmetros são passados por cabeçalhos HTTP, enquanto no PostObject os parâmetros são passados como campos de formulário no corpo da mensagem.

Uma mensagem do PostObject é composta pelo cabeçalho e pelo corpo. O cabeçalho e o corpo são separados por \r\n--{boundary}. O corpo consiste em 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 cabeçalhos comuns incluem Host, User-Agent, Content-Length, Content-Type e Content-MD5, enquanto os campos de formulário incluem key, OSSAccessKeyId, Signature, Content-Disposition, metadados do objeto (x-oss-meta-*), x-oss-security-token, outros cabeçalhos HTTP (Cache-Control/Content-Type/Cache-Control/Content-Type/Content-Disposition/Content-Encoding/Expires/Content-Encoding/Expires) e file. O campo file deve ser o último entre esses campos de formulário.

Para mais informações, consulte Post Object.

Erros comuns do PostObject

A tabela a seguir mostra os erros comuns do PostObject:

• Formato de campo de formulário do PostObject

  Para o formato das requisições do PostObject, observe os seguintes itens:

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

  • O cabeçalho e o corpo 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 o último campo do formulário.

  • Quando o valor do bucket é public-read-write, não é necessário especificar os campos de formulário OSSAccessKeyId, policy e Signature. Se qualquer um entre OSSAccessKeyId, policy e Signature for especificado, os outros dois campos também deverão ser especificados, independentemente de o bucket ser public-read-write ou não.

  A seguir, um exemplo de requisição do 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, ou seja, uma quebra de linha. Isso também se aplica às requisições de exemplo a seguir.

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

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

  • C#

  • Java

• Formato da policy do PostObject

  Em uma requisição do PostObject, o campo de formulário policy é usado para verificar a validade da requisição e declara as condições que a requisição do PostObject deve atender. Especificamente, essas condições são:

  • O texto JSON em UTF-8 deve ser codificado em base64 antes de ser passado para o campo de formulário policy.

  • A policy deve incluir expiration e conditions, onde conditions deve conter pelo menos um item.

  A seguir, um exemplo de policy antes da codificação em base64.

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

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

  O PostPolicy aceita as seguintes "conditions":

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

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

  Caractere de escape	Descrição
  /	Barra
  \	Barra invertida
  “	Aspas duplas
  $	Cifrão
  \b	Espaço em branco
  \f	Quebra de formulário
  \n	Quebra de linha
  \r	Enter
  \t	Tabulação horizontal
  \uxxxx	Caractere Unicode

  Para mais informações sobre o PostPolicy, consulte Post Policy.

• Assinatura do PostObject

  Para que uma requisição Post seja verificada, ela deve incluir os campos de formulário AccessKeyID, policy e Signature. O processo de cálculo da assinatura é o seguinte:

  1. Crie uma policy codificada em UTF-8.

  2. Codifique a policy em base64. O valor resultante é o valor a ser preenchido no campo de formulário policy, e esse valor é usado como a string a ser assinada.

  3. Assine a string com o AccessKeySecret. Especificamente, faça o hash da string com hmac-sha1 e, em seguida, codifique-a em base64. O método de assinatura é o mesmo usado para Header Signature.

  Ou seja:

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

  Especifique a assinatura calculada no campo de formulário Signature da seguinte forma:

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

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

  • C#

  • Java

Perguntas frequentes

• Como especificar uma key?

  A key é o nome do objeto, especificado no campo de formulário key. A seguir, um exemplo:

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

• Como especificar o conteúdo do objeto?

  Especifique o conteúdo do objeto no campo de formulário file. A seguir, um 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 o último campo do formulário, ou seja, deve ser posicionado após qualquer outro campo.

  • O filename é o nome do arquivo local enviado, e não o nome do objeto.

• Como especificar o content-type do objeto?

  Especifique o content-type do objeto no campo de formulário file, e não no content-type do cabeçalho. A seguir, um exemplo:

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

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

  Especifique o content-md5 no cabeçalho da requisição do PostObject. Observe que o valor MD5 refere-se a todo o corpo, ou seja, a todos os campos de formulário. A seguir, um exemplo de cabeçalho 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 especificar uma assinatura?

  Consulte a seção PostObject signature para ver o método de cálculo da assinatura. A assinatura é transportada pelo campo de formulário Signature.

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

  O uso do AccessKeyID e do AccessKeySecret de uma chave de usuário temporário é o mesmo de uma chave de usuário principal e de subusuário. O Token é transportado pelo campo de formulário x-oss-security-token. A seguir, um exemplo:

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

• Como especificar um callback?

  O callback é transportado pelo campo de formulário callback. A seguir, um exemplo:

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

  Os parâmetros personalizados do callback também são transportados por campos de formulário. A seguir, um exemplo:

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

• Como especificar o Content-Transfer-Encoding?

  Especifique o Content-Transfer-Encoding no campo de formulário file. A seguir, um exemplo do campo de formulário file:

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

• Como especificar as informações de metadados personalizados Object User Meta?

  Especifique as informações de metadados personalizados nos campos de formulário. A seguir, um 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 as informações de metadados do arquivo, consulte File Meta Information Object Meta.

• Como especificar condições como expiration, Key, Bucket, tamanho e cabeçalho?

  O PostObject para o OSS aceita diversas condições e pode atender a requisitos rigorosos de segurança. Especifique as condições no campo de formulário policy. A seguir, um exemplo de policy:

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

  Na policy anterior, as condições para as operações de PostObject do usuário são as seguintes:

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

  • O horário da requisição deve ser anterior a 2018-01-01T12:00:00.000Z.

• Como especificar cabeçalhos HTTP como Cache-Control, Content-Type, Content-Disposition, Content-Encoding e Expires?

  Especifique os cabeçalhos HTTP, incluindo Cache-Control, Content-Type, Content-Disposition, Content-Encoding e Expires, nos campos de formulário. Para saber o significado desses cabeçalhos HTTP, consulte a RFC2616. No entanto, o Content-MD5 precisa ser especificado no cabeçalho do Post.

Exemplos de PostObject

Link comumente usado