Todos os produtos
Search

Este produto

    Object Storage Service:PostObject

    Central de documentação

    Object Storage Service:PostObject

    Última atualização: Jul 03, 2026

    Use a operação PostObject para fazer upload de um objeto em um bucket por meio de um formulário HTML.

    Observações de uso

    • O upload via formulário HTML exige a permissão oss:PutObject. Anexar uma política personalizada a um usuário do RAM.

    • Objetos enviados via PostObject não podem exceder 5 GB.

    • Uma requisição PostObject requer permissões de escrita no bucket. Se a ACL do bucket for public-read-write, as informações de assinatura são dispensáveis. Caso contrário, o OSS valida a assinatura na requisição.

    • Diferentemente do PutObject, o PostObject usa um AccessKey secret para assinar a política. A string de assinatura resultante corresponde ao valor do campo de formulário Signature, validado pelo OSS.

    • A URL do formulário corresponde ao nome de domínio do bucket sem o nome do objeto. A linha de requisição é POST / HTTP/1.1, e não POST /ObjectName HTTP/1.1.

    • Se uma requisição POST contiver informações de assinatura no cabeçalho ou na URL, o OSS ignorará essas informações.

    Versionamento

    Se o versionamento estiver ativado no bucket, o OSS gera um ID de versão exclusivo para o objeto enviado e o retorna no cabeçalho de resposta x-oss-version-id.

    Se o versionamento estiver suspenso, o OSS gera um ID de versão nulo para o objeto enviado e o retorna no cabeçalho de resposta x-oss-version-id. Apenas um ID de versão nulo é permitido por objeto.

    Sintaxe da requisição

    POST / HTTP/1.1 
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
User-Agent: browser_data
Content-Length: ContentLength
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
key
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"
success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
attachment;filename=oss_download.jpg
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
myuuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
mytag
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
access-key-id
--9431149156168
Content-Disposition: form-data; name="policy"
encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"
signature
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg
file_content
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    Cabeçalhos da requisição

    Importante

    • O corpo da requisição PostObject utiliza codificação multipart/form-data. Ao contrário do PutObject, que passa parâmetros em cabeçalhos HTTP, o PostObject transmite os parâmetros como campos de formulário no corpo.

    • O PostObject não oferece suporte ao cabeçalho x-oss-tagging. Após a conclusão do PostObject, chame PutObjectTagging para aplicar tags ao objeto.

    Nome

    Tipo

    Obrigatório

    Descrição

    Content-Type

    String

    Não

    Tipo de arquivo e codificação da página web. Determina como os navegadores leem o arquivo.

    O formulário enviado em uma operação Post deve usar a codificação multipart/form-data. Portanto, o cabeçalho Content-Type segue o formato multipart/form-data;boundary=xxxxxx.

    O boundary é uma string aleatória gerada pelo formulário. Não é necessário especificá-lo, pois os SDKs geram esse valor automaticamente.

    Esta operação também utiliza Cabeçalhos comuns de requisição, como Host e Date.

    Elementos do formulário

    A tabela a seguir descreve os elementos de formulário comuns às assinaturas V1 e V4. Para obter informações sobre elementos exclusivos das assinaturas V4, consulte Formulário de assinatura V4. Para detalhes sobre elementos exclusivos das assinaturas V1, veja Formulário de assinatura V1.

    Importante

    • O campo file deve ser o último campo do formulário. Os demais campos podem aparecer em qualquer ordem.

    • A chave de um campo de formulário não pode exceder 8 KB, e o valor não pode ultrapassar 2 MB.

    Nome

    Tipo

    Obrigatório

    Descrição

    Cache-Control

    String

    Não

    Comportamento de cache durante o download do objeto, conforme definido na RFC 2616.

    Valor padrão: nenhum.

    Content-Disposition

    String

    Não

    Nome do arquivo para download do objeto, conforme definido na RFC 2616.

    Valor padrão: nenhum.

    Content-Encoding

    String

    Não

    Codificação de conteúdo do objeto durante o download, conforme definido na RFC 2616.

    Valor padrão: nenhum.

    Expires

    String

    Não

    Tempo de expiração do cache, conforme definido na RFC 2616.

    Valor padrão: nenhum.

    policy

    String

    Sim, condicional

    Define a validade dos campos do formulário de requisição. Uma requisição sem o campo policy é tratada como anônima e só pode acessar buckets public-read-write.

    Valor padrão: nenhum.

    Restrição: Obrigatório se o bucket não for public-read-write ou se OSSAccessKeyId ou Signature forem fornecidos.

    Importante

    O formulário e a política devem estar codificados em UTF-8. O campo de formulário policy também deve ser codificado em Base64.

    x-oss-server-side-encryption-key-id

    String

    Não

    Chave mestra do cliente (CMK) gerenciada pelo KMS. Válido apenas quando x-oss-server-side-encryption está definido como KMS.

    x-oss-content-type

    String

    Não

    Substitui o Content-Type adicionado automaticamente pelos navegadores ao campo de formulário file. Este elemento tem a maior prioridade para especificar o Content-Type.

    Ordem de prioridade: x-oss-content-type > Content-Type do campo de formulário file

    Valor padrão: nenhum.

    x-oss-forbid-overwrite

    String

    Não

    Determina se um objeto com o mesmo nome pode ser sobrescrito durante uma operação PostObject.

    Quando o versionamento está ativado ou suspenso, x-oss-forbid-overwrite é ignorado e objetos com o mesmo nome podem ser sobrescritos.

    • Se x-oss-forbid-overwrite não for especificado ou estiver definido como false, objetos com o mesmo nome poderão ser sobrescritos.

    • Se x-oss-forbid-overwrite estiver definido como true, objetos com o mesmo nome não poderão ser sobrescritos.

    O cabeçalho x-oss-forbid-overwrite reduz o QPS. Se o uso de x-oss-forbid-overwrite exceder 1.000 QPS, entre em contato com o suporte técnico.

    x-oss-object-acl

    String

    Não

    Permissões de acesso para o objeto enviado.

    Valores válidos:

    • default (padrão): Herda a ACL do bucket.

    • private: Apenas o proprietário e usuários autorizados podem ler e gravar o objeto.

    • public-read: Todos os usuários podem ler o objeto. Apenas o proprietário e usuários autorizados podem gravar. Use com cautela.

    • public-read-write: Todos os usuários podem ler e gravar o objeto. Use com cautela.

    As permissões de acesso estão descritas em ACL de objeto.

    x-oss-storage-class

    String

    Não

    Especifica a classe de armazenamento do objeto.

    Independentemente da classe de armazenamento do bucket, o objeto enviado utiliza a classe especificada. Por exemplo, definir x-oss-storage-class como Standard para um bucket IA armazena o objeto como Standard.

    Valores válidos:

    • Standard: Standard

    • IA: Infrequent Access

    • Archive: Archive Storage

    • ColdArchive: Cold Archive

    • DeepColdArchive: Deep Cold Archive

      Importante

    Classes de armazenamento.

    key

    String

    Sim

    Nome do objeto a ser enviado. Não codifique o nome. Se o nome incluir um caminho, como destfolder/example.jpg, o OSS cria automaticamente a pasta correspondente.

    Valor padrão: nenhum.

    success_action_redirect

    String

    Não

    URL para redirecionar o cliente após um upload bem-sucedido. Se não especificado, o comportamento da resposta é determinado por success_action_status. Em caso de falha, o OSS retorna um erro sem redirecionar.

    Valor padrão: nenhum.

    success_action_status

    String

    Não

    Código de status HTTP retornado após um upload bem-sucedido quando success_action_redirect não é especificado.

    Valores válidos: 200, 201 e 204 (padrão).

    • Se este campo for definido como 200 ou 204, o OSS retorna um documento vazio e o código de status correspondente.

    • Se este campo for definido como 201, o OSS retorna um arquivo XML e o código de status 201.

    • Se este campo não for definido ou receber um valor inválido, o OSS retorna um documento vazio e o código de status 204.

    x-oss-meta-*

    String

    Não

    Metadados definidos pelo usuário.

    Valor padrão: nenhum.

    Campos de formulário com o prefixo x-oss-meta- são armazenados como metadados do usuário. Exemplo: x-oss-meta-location.

    Nota

    Um objeto pode ter vários desses parâmetros, mas o tamanho total de todos os metadados do usuário não pode exceder 8 KB.

    x-oss-security-token

    String

    Não

    Token de segurança STS. Necessário apenas ao usar STS para construir uma URL assinada. Obtenha um token chamando a operação AssumeRole.

    Valor padrão: nenhum.

    file

    String

    Sim

    Conteúdo do arquivo ou texto. Não codifique o conteúdo. O navegador define o Content-Type com base no tipo de arquivo, sobrescrevendo suas configurações. Apenas um arquivo pode ser enviado por requisição.

    Valor padrão: nenhum.

    Importante

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

    Cabeçalhos da resposta

    Nome

    Tipo

    Exemplo

    Descrição

    x-oss-server-side-encryption

    String

    KMS

    Retornado se x-oss-server-side-encryption for especificado na requisição. Indica o algoritmo de criptografia utilizado.

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    Hash MD5 do arquivo.

    Importante

    Este é o hash MD5 do arquivo enviado, não o hash MD5 do corpo da resposta.

    x-oss-hash-crc64ecma

    String

    316181249502703****

    Valor CRC-64 do arquivo.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

    ID de versão do objeto enviado. Retornado apenas para buckets com versionamento ativado.

    Esta operação também retorna Cabeçalhos comuns de resposta, como Date e x-oss-request-id.

    Elementos da resposta

    Nome

    Tipo

    Descrição

    PostResponse

    Container

    Recipiente que armazena o resultado da requisição Post.

    Nós filhos: Bucket, ETag, Key e Location

    Bucket

    String

    Nome do bucket.

    Nó pai: PostResponse

    ETag

    String

    ETag do objeto enviado. Para uploads via PostObject, o ETag é um identificador exclusivo, mas não corresponde ao hash MD5 do conteúdo. Utilize-o para verificar se o conteúdo foi alterado.

    Nó pai: PostResponse

    Location

    String

    URL do objeto recém-criado.

    Nó pai: PostResponse

    Exemplos

    • Exemplo de requisição:

      POST / HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 344606
Content-Type: multipart/form-data; boundary=9431149156168
--9431149156168
Content-Disposition: form-data; name="key"
/user/a/objectName.txt
--9431149156168
Content-Disposition: form-data; name="success_action_status"
200
--9431149156168
Content-Disposition: form-data; name="Content-Disposition"
content_disposition
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-oss-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="OSSAccessKeyId"
44CF9590006BF252****
--9431149156168
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAxMy0xMi0wMVQxMjowMDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwNDg1NzYwXSx7ImJ1Y2tldCI6ImFoYWhhIn0sIHsiQSI6ICJhIn0seyJrZXkiOiAiQUJDIn1dfQ==
--9431149156168
Content-Disposition: form-data; name="Signature"
kZoYNv66bsmc10+dcGKw5x2P****
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.txt"
Content-Type: text/plain
abcdefg
--9431149156168
Content-Disposition: form-data; name="submit"
Upload to OSS
--9431149156168--

    • Exemplo de resposta:

      HTTP/1.1 200 OK
x-oss-request-id: 61d2042d-1b68-6708-5906-33d81921362e 
Date: Fri, 24 Feb 2014 06:03:28 GMT
ETag: "5B3C1A2E053D763E1B002CC607C5****"
Connection: keep-alive
Content-Length: 0
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
Server: AliyunOSS

    SDK

    SDKs suportados:

    Códigos de erro

    Código de erro

    Código de status HTTP

    Descrição

    FieldItemTooLong

    400

    O tamanho da chave do campo de formulário não pode exceder 8 KB, e o tamanho do valor do campo de formulário não pode exceder 2 MB.

    InvalidArgument

    400

    Independentemente da ACL do bucket, se OSSAccessKeyId, policy ou Signature forem fornecidos, todos os três são obrigatórios. A ausência de qualquer um deles retorna este erro.

    InvalidDigest

    400

    O Content-MD5 na requisição não corresponde ao hash MD5 calculado pelo OSS para o corpo da requisição.

    EntityTooLarge

    400

    O corpo da requisição excede o limite de tamanho de 5 GB.

    InvalidEncryptionAlgorithmError

    400

    O valor de x-oss-server-side-encryption não é AES256 ou KMS.

    IncorrectNumberOfFilesInPOSTRequest

    400

    Uma requisição PostObject pode conter apenas um campo de formulário file.

    FileAlreadyExists

    409

    Existe um objeto com o mesmo nome e x-oss-forbid-overwrite está definido como true.

    KmsServiceNotEnabled

    403

    x-oss-server-side-encryption está definido como KMS, mas você não adquiriu um pacote KMS antecipadamente.

    FileImmutable

    409

    O bucket está protegido e os dados não podem ser excluídos ou modificados.

    MethodNotAllowed

    405

    O método de requisição HTTP não é suportado. Verifique se o método de requisição, cabeçalhos, protocolo da URL, nome de domínio e caminho estão corretos.

    Política POST

    O campo de formulário policy é uma política de segurança formatada em JSON que especifica restrições para uploads via formulário HTML, incluindo nome do bucket, prefixo do objeto, período de validade, métodos HTTP permitidos, limites de tamanho de upload e tipos de conteúdo.

    Assinatura POST

    Cada requisição PostObject deve incluir uma assinatura para autenticação.

    Perguntas frequentes

    O que fazer se o erro "Your proposed upload exceeds the maximum allowed size" for retornado?

    • Causa: O tamanho do arquivo enviado está fora do intervalo especificado por content-length-range.

    • Solução: Use content-length-range para especificar os tamanhos mínimo e máximo permitidos para o arquivo enviado, em bytes. Por exemplo, para enviar um arquivo de 1 GB, defina content-length-range como ["content-length-range", 1, 1073741824].

    Referências