Todos os produtos
Search

Este produto

    Object Storage Service:PostObject

    Central de documentação

    Object Storage Service:PostObject

    Última atualização: Sep 22, 2026

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

    Notas de uso

    • O upload por formulário HTML requer a permissão oss:PutObject. Attach a custom policy to a RAM user.

    • Os objetos enviados por meio do PostObject não podem exceder 5 GB.

    • Uma requisição PostObject requer permissões de gravação no bucket. Se a ACL do bucket for public-read-write, as informações de assinatura não são necessárias. Caso contrário, o OSS autentica a assinatura na requisição.

    • Diferente do PutObject, o PostObject usa um AccessKey secret para assinar a política. A string de assinatura resultante é o valor do campo de formulário Signature, que o OSS autentica.

    • A url do formulário é o 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 não verificará essas informações.

    Versionamento

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

    Se o versionamento estiver suspenso, o OSS gerará um id de versão nulo para o objeto enviado e o retornará 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 usa a codificação multipart/form-data. Ao contrário do PutObject, que passa parâmetros em cabeçalhos http, o PostObject passa 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 o PutObjectTagging para aplicar tags ao objeto.

    Nome

    Tipo

    Obrigatório

    Descrição

    Content-Type

    String

    Não

    O tipo de arquivo e a codificação da página da web, que determinam como os navegadores leem o arquivo.

    O formulário que você envie em uma operação Post deve ser codificado no formato multipart/form-data. Isso significa que o cabeçalho Content-Type está no formato multipart/form-data;boundary=xxxxxx.

    O boundary é uma string aleatória gerada pelo formulário. Você não precisa especificá-lo. Os SDKs geram esse valor automaticamente.

    Esta operação também usa Common request headers, como Host e Date.

    Elementos do formulário

    A tabela a seguir descreve os elementos do formulário comuns às assinaturas V1 e V4. Para obter informações sobre os elementos do formulário exclusivos das assinaturas V4, consulte V4 signature form. Para obter informações sobre os elementos do formulário exclusivos das assinaturas V1, consulte V1 signature form.

    Importante

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

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

    Nome

    Tipo

    Obrigatório

    Descrição

    Cache-Control

    String

    Não

    O comportamento de cache quando você baixe o objeto, conforme definido na RFC 2616.

    Valor padrão: none.

    Content-Disposition

    String

    Não

    O nome do arquivo quando você baixe o objeto, conforme definido na RFC 2616.

    Valor padrão: none.

    Content-Encoding

    String

    Não

    A codificação de conteúdo do objeto quando você baixe, conforme definido na RFC 2616.

    Valor padrão: none.

    Expires

    String

    Não

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

    Valor padrão: none.

    policy

    String

    Sim, condicional

    Especifique 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: none.

    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 ser 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

    A 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 que os navegadores adicionam automaticamente ao campo de formulário file. Este elemento tem a maior prioridade para que você especifique o Content-Type.

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

    Valor padrão: none.

    x-oss-forbid-overwrite

    String

    Não

    Especifique se um objeto com o mesmo nome deve ser substituído durante uma operação PostObject.

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

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

    • Se x-oss-forbid-overwrite estiver definido como true, objetos com o mesmo nome não podem ser substituídos.

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

    x-oss-object-acl

    String

    Não

    As 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 são descritas em Object ACL.

    x-oss-storage-class

    String

    Não

    Especifique a classe de armazenamento do objeto.

    Independentemente da classe de armazenamento do bucket, o objeto enviado usa a classe que você especificar. Por exemplo, especifique diretamente a classe 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

      Se você deseja fazer upload de um grande número de objetos, especifique diretamente a classe de armazenamento Deep Cold Archive para os objetos a serem enviados resulta em altas taxas de requisição PUT. Recomendamos que você primeiro especifique a classe de armazenamento Standard para os objetos ao enviá-los e, em seguida, use lifecycle rules para convertê-los para a classe de armazenamento Deep Cold Archive, a fim de reduzir as taxas de requisição PUT.

    Storage classes.

    key

    String

    Sim

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

    Valor padrão: none.

    success_action_redirect

    String

    Não

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

    Valor padrão: none.

    success_action_status

    String

    Não

    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 estiver definido como 200 ou 204, o OSS retornará um documento vazio e o código de status correspondente.

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

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

    x-oss-meta-*

    String

    Não

    Metadados definidos pelo usuário.

    Valor padrão: none.

    Os 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 parâmetros desse tipo, mas o tamanho total de todos os metadados do usuário não pode exceder 8 KB.

    x-oss-security-token

    String

    Não

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

    Valor padrão: none.

    file

    String

    Sim

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

    Valor padrão: none.

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

    Content-MD5

    String

    1B2M2Y8AsgTpgAmY7PhC****

    O 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****

    O valor CRC-64 do arquivo.

    x-oss-version-id

    String

    CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

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

    Esta operação também retorna Common response headers, como Date e x-oss-request-id.

    Elementos da resposta

    Nome

    Tipo

    Descrição

    PostResponse

    Container

    O contêiner que armazena o resultado da requisição Post.

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

    Bucket

    String

    O nome do bucket.

    Nó pai: PostResponse

    ETag

    String

    O ETag do objeto enviado. Para uploads do PostObject, o ETag é um identificador exclusivo, mas não o hash MD5 do conteúdo. Use-o e verifique se o conteúdo foi alterado.

    Nó pai: PostResponse

    Location

    String

    A 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 qualquer um entre OSSAccessKeyId, policy ou Signature for fornecido, todos os três serã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

    O x-oss-server-side-encryption está definido como KMS, mas você não adquiriu um pacote do 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. Por favor, verifique se o método de requisição, os cabeçalhos, o protocolo da url (http ou HTTPS), o nome de domínio e o 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 de formulários HTML, incluindo o nome do bucket, o prefixo do objeto, o período de validade, os métodos http permitidos, os limites de tamanho de upload e os 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 que você especifique os tamanhos mínimo e máximo permitidos para o arquivo enviado em bytes. Por exemplo, para fazer upload de um arquivo de 1 GB, é recomendado que você defina content-length-range como ["content-length-range", 1, 1073741824].

    Referências