Object Storage Service PutObject API - Object Storage Service: Central de Documentação do Alibaba Cloud

Sintaxe da solicitação

PUT /ObjectName HTTP/1.1
Content-Length: ContentLength
Content-Type: ContentType
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Notas de uso

O limite máximo para envio de arquivo em uma única operação é de 5 GB. Para arquivos maiores que esse tamanho, use o recurso de upload multipart.
Ao enviar um arquivo com o mesmo nome de outro já existente, o sistema substitui o arquivo original por padrão e retorna o código de status 200 OK. Defina um parâmetro para impedir substituições e evitar a perda acidental de arquivos importantes.
O OSS adota uma estrutura de armazenamento plana, sem diretórios como em sistemas de arquivos tradicionais. Para simular uma estrutura de pastas, crie um objeto vazio cujo nome termine com uma barra (/).

Permissions

Uma conta Alibaba Cloud possui permissões completas por padrão. No entanto, um usuário do Resource Access Management (RAM) ou uma função RAM vinculada à conta não tem permissões até que a conta Alibaba Cloud ou um administrador as conceda por meio de uma RAM Policy ou de uma Bucket Policy.

API	Action	Description
PutObject	`oss:PutObject`	Envia um objeto.
	`oss:PutObjectTagging`	Necessário se você especificar tags de objeto usando o cabeçalho `x-oss-tagging` durante o upload.
	`kms:GenerateDataKey`	Obrigatório quando o cabeçalho `X-Oss-Server-Side-Encryption: KMS` estiver definido como `KMS` no upload do objeto.
	`kms:Decrypt`

Versioning

Em buckets com versionamento ativado, o OSS gera automaticamente um ID de versão exclusivo para cada novo objeto. Esse ID é retornado no cabeçalho de resposta x-oss-version-id.

Quando o versionamento está suspenso, o ID de versão de um novo objeto é null. O OSS garante que exista apenas uma versão null por objeto.

Parâmetros da solicitação

O OSS suporta cabeçalhos de solicitação HTTP padrão, como Cache-Control, Expires, Content-Encoding, Content-Disposition e Content-Type. Ao definir esses cabeçalhos, os valores são aplicados automaticamente durante o download do arquivo.

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
Authorization	String	Não	OSS qn6q:77Dv**	Indica que a solicitação foi autenticada e autorizada. Para mais detalhes sobre o cálculo do valor de Authorization, consulte Include a signature in the header. Geralmente, o cabeçalho Authorization é obrigatório. Contudo, ele pode ser omitido caso a assinatura esteja incluída na URL. Veja mais em Include a signature in the URL. Valor padrão: nenhum
Cache-Control	String	Não	no-cache	Define o comportamento de cache durante o download do objeto. Valores válidos: no-cache: O cache deve revalidar o conteúdo com o servidor de origem antes de servi-lo. no-store: Proíbe o armazenamento do objeto em cache. public: Permite que qualquer sistema de cache armazene o objeto. private: Restringe o cache apenas ao cliente. max-age=<seconds>: Define a validade do cache em segundos. Disponível somente no HTTP 1.1. Valor padrão: nenhum
Content-Disposition	String	Não	attachment	Determina como o objeto será exibido. Valores válidos: Content-Disposition:inline: Exibe o objeto diretamente no navegador. Content-Disposition:attachment: Força o download do objeto mantendo seu nome original. Content-Disposition:attachment; filename="yourFileName": Baixe o objeto com um nome de arquivo personalizado. yourFileName representa o nome personalizado, como example.jpg. Ao baixar objetos como anexos, observe os seguintes pontos: Nota Se o nome do objeto contiver caracteres especiais, como asteriscos () ou barras (/), o nome do arquivo baixado poderá sofrer escape. Por exemplo, ao baixar `example`.jpg para o computador local, `example*.jpg` pode ser convertido para `example_.jpg`. Para evitar nomes de arquivo ilegíveis devido a caracteres não ASCII, aplique codificação URL neles. Por exemplo, para baixar o objeto `Test.txt` com o nome original `Test.txt`, defina o cabeçalho Content-Disposition como `attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename=UTF-8''%E6%B5%8B%E8%AF%95.txt`, derivado de `"attachment;filename="+URLEncoder.encode("Test","UTF-8")+".txt;filename=UTF-8''"+URLEncoder.encode("Test","UTF-8")+".txt"`. A pré-visualização ou o download do objeto como anexo depende da data de criação do bucket, da ativação do OSS e do tipo de nome de domínio. Consulte What do I do if an image object is downloaded as an attachment but cannot be previewed when I access the image object by using its URL? para mais informações. Valor padrão: nenhum
Content-Encoding	String	Não	identity	Declara o codec do objeto. Especifique o codec real do objeto para evitar falhas de análise ou download no cliente. Deixe este cabeçalho vazio se o objeto não estiver codificado. Valores válidos: identity (padrão): Sem compressão ou codificação. gzip: Codificado com o algoritmo LZ77 e CRC de 32 bits. compress: Codificado com o algoritmo LZW. deflate: Codificado com zlib e o algoritmo deflate. br: Codificado com o algoritmo Brotli. Valor padrão: nenhum
Content-MD5	String	Não	eB5eJF1ptWaXm4bijSPyxw==	Serve para verificar a integridade do conteúdo da mensagem. O Content-MD5 é gerado pelo algoritmo MD5. Se este cabeçalho for definido, o OSS calcula o hash Content-MD5 do corpo da mensagem e valida a consistência. Veja mais em How to calculate Content-MD5. Para garantir a integridade dos dados, o OSS oferece vários métodos de verificação de hash MD5. Para validar via Content-MD5, adicione o cabeçalho Content-MD5 à solicitação. Valor padrão: nenhum
Content-Length	String	Não	344606	Tamanho do corpo da mensagem HTTP a ser transferido, em bytes. Caso o valor do cabeçalho Content-Length seja menor que o tamanho real dos dados transferidos no corpo da solicitação, o OSS ainda cria o objeto. Entretanto, o tamanho final corresponderá ao valor definido em Content-Length, e o excesso de dados será descartado.
Expires	String	Não	Wed, 08 Jul 2015 16:57:01 GMT	Define a data de expiração do objeto. Consulte a RFC2616 para mais detalhes. Valor padrão: nenhum
x-oss-forbid-overwrite	String	Não	false	Controla a substituição de objetos com o mesmo nome durante a operação PutObject. Se o bucket de destino tiver versionamento ativado ou suspenso, o cabeçalho x-oss-forbid-overwrite perde o efeito, permitindo a sobrescrita. A substituição ocorre normalmente se x-oss-forbid-overwrite não for especificado ou estiver definido como false. Definir x-oss-forbid-overwrite como true impede a substituição de objetos homônimos. O uso do cabeçalho x-oss-forbid-overwrite impacta o desempenho de QPS. Caso suas operações exijam esse cabeçalho em alta frequência (QPS>1000), entre em contato com o suporte técnico para evitar impactos nos seus processos de negócio. Valor padrão: false
x-oss-server-side-encryption	String	Não	AES256	Especifica o método de criptografia no lado do servidor durante a criação do objeto. Valores válidos: AES256, KMS, Se especificado, este cabeçalho é retornado na resposta. O OSS criptografa e armazena o objeto enviado. Durante o download, o cabeçalho de resposta incluirá x-oss-server-side-encryption com o algoritmo de criptografia utilizado.
x-oss-server-side-encryption-key-id	String	Não	9468da86-3509-4f8d-a61e-6eab1eac****	ID da chave mestra do cliente (CMK) gerenciada pelo KMS. Este cabeçalho só é válido quando x-oss-server-side-encryption estiver definido como KMS.
x-oss-object-acl	String	Não	default	Define as permissões de acesso do objeto no momento da criação no OSS. Valores válidos: default: O objeto herda as permissões de acesso do bucket. private: Recurso privado. Apenas o proprietário e usuários autorizados têm permissão de leitura e escrita. Outros usuários não podem acessá-lo. public-read: Recurso de leitura pública. O proprietário e usuários autorizados têm leitura e escrita; demais usuários possuem apenas permissão de leitura. Utilize com cautela. public-read-write: Recurso público de leitura e escrita. Todos os usuários têm permissão total. Use esta opção com extrema cautela. Para mais informações sobre permissões de acesso, consulte Object ACL.
x-oss-storage-class	String	Não	Standard	Determina a classe de armazenamento do objeto. Independentemente da classe do bucket, especificar este parâmetro no upload armazena o objeto na classe indicada. Por exemplo, definir x-oss-storage-class como Standard ao enviar um arquivo para um bucket Infrequent Access (IA) resultará em um objeto Standard. Valores válidos: Standard: Standard IA: Infrequent Access Archive: Archive Storage ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Importante Para uploads massivos, definir diretamente a classe Deep Cold Archive gera altas taxas de requisição PUT. Recomendamos enviar os objetos inicialmente como Standard e depois utilizar lifecycle rules para convertê-los para Deep Cold Archive, reduzindo custos. Para mais detalhes, veja Storage classes.
x-oss-meta-*	String	Não	x-oss-meta-location	Na API PutObject, parâmetros com o prefixo x-oss-meta- são tratados como metadados definidos pelo usuário, como `x-oss-meta-location`. Um objeto pode ter múltiplos parâmetros desse tipo, mas o tamanho total dos metadados não pode exceder 8 KB. Metadados aceitam hifens (-), números e letras minúsculas (a-z). Letras maiúsculas são convertidas automaticamente para minúsculas. Outros caracteres, incluindo underscores (_), não são permitidos.
x-oss-tagging	String	Não	TagA=A&TagB=B	Atribui tags ao objeto no formato chave-valor. Várias tags podem ser definidas simultaneamente, por exemplo: `TagA=A&TagB=B`. Nota Chaves e valores devem estar codificados em URL. A chave é obrigatória, enquanto o valor é opcional. Por exemplo, é válido definir as tags como `TagA&TagB=B`.

Para mais informações, consulte Common Response Headers.

Parâmetros de resposta

Parâmetro	Tipo	Exemplo	Descrição
Content-MD5	String	1B2M2Y8AsgTpgAmY7PhC****	Hash MD5 do arquivo enviado. Importante Este hash refere-se ao arquivo processado após a conclusão do upload pelo cliente, e não ao corpo da resposta.
x-oss-hash-crc64ecma	String	316181249502703****	Valor CRC-64 do arquivo enviado.
x-oss-version-id	String	CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****	ID de versão do arquivo. Este cabeçalho de resposta é retornado apenas quando o upload é feito em um bucket com versionamento ativado.

Para mais informações, consulte Common Response Headers.

Exemplos

Upload simples

Exemplo de solicitação

PUT /test.txt HTTP/1.1
Host: test.oss-cn-zhangjiakou.aliyuncs.com
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: */*
Connection: keep-alive
Content-Type: text/plain
Date: Tue, 04 Dec 2018 15:56:37 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Transfer-Encoding: chunked

Exemplo de resposta

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 04 Dec 2018 15:56:38 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5C06A3B67B8B5A3DA422299D
ETag: "D41D8CD98F00B204E9800998ECF8****"
x-oss-hash-crc64ecma: 316181249502703****
Content-MD5: 1B2M2Y8AsgTpgAmY7PhC****
x-oss-server-time: 7

Definir a classe de armazenamento

Exemplo de solicitação

PUT /oss.jpg HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Cache-control: no-cache 
Expires: Fri, 28 Feb 2012 05:38:42 GMT 
Content-Disposition: attachment;filename=oss_download.jpg 
Date: Fri, 24 Feb 2012 06:03:28 GMT 
Content-Type: image/jpg 
Content-Length: 344606 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-disposition;content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e 
[344606 bytes of object data]

Exemplo de resposta

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Sat, 21 Nov 2015 18:52:34 GMT
Content-Type: image/jpg
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5650BD72207FB30443962F9A
ETag: "A797938C31D59EDD08D86188F6D5B872"

Ativar versionamento

Exemplo de solicitação

PUT /test HTTP/1.1
Content-Length: 362149
Content-Type: text/html
Host: versioning-put.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:53:24 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemplo de resposta

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 09 Apr 2019 02:53:24 GMT
Content-Length: 0
Connection: keep-alive
x-oss-request-id: 5CAC0A3DB7AEADE01700****
x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****
ETag: "4F345B1F066DB1444775AA97D5D2****"

Códigos de erro

Error code	HTTP status code	Description
MissingContentLength	411	O cabeçalho da solicitação não utiliza codificação chunked ou o parâmetro Content-Length não foi definido.
InvalidEncryptionAlgorithmError	400	O valor especificado para x-oss-server-side-encryption é inválido. Valores válidos: AES256, KMS, .
AccessDenied	403	O usuário não possui as permissões de acesso necessárias no bucket especificado para adicionar o objeto.
NoSuchBucket	404	O bucket especificado não existe no momento da adição do objeto.
InvalidObjectName	400	Nome do objeto inválido. Isso ocorre quando o nome não é especificado, excede o limite de caracteres ou contém padrões não permitidos.
InvalidArgument	400	Este erro pode ser retornado pelos seguintes motivos: O tamanho do objeto a ser adicionado ultrapassa 5 GB. Um parâmetro, como x-oss-storage-class, possui um valor inválido.
RequestTimeout	400	O parâmetro Content-Length foi especificado, mas nenhum corpo de mensagem foi enviado, ou o corpo enviado é menor que o tamanho indicado. Nesses casos, o servidor aguarda até que a solicitação atinja o tempo limite.
Bad Request	400	Se Content-MD5 for especificado na solicitação, o OSS calcula o hash MD5 dos dados enviados e o compara com o valor fornecido. A discrepância entre os valores resulta neste erro.
KmsServiceNotEnabled	403	Você especificou KMS para x-oss-server-side-encryption, mas não adquiriu o pacote KMS previamente.
FileAlreadyExists	409	Possíveis causas: O cabeçalho inclui `x-oss-forbid-overwrite=true` para impedir substituições, mas já existe um arquivo com o mesmo nome no bucket. O recurso de namespace hierárquico está ativado no bucket e já existe um diretório com o mesmo nome no nível atual.
FileImmutable	409	Erro retornado ao tentar excluir ou modificar dados em um bucket que se encontra em estado protegido.

Métodos de integração

SDK

Os SDKs para a API PutObject estão disponíveis nas seguintes linguagens:

Java	Python V2	Go V2	C++	PHP V2
C	.NET	Android	iOS	Node.js
Browser.js	Ruby	Harmony

Interface de linha de comando ossutil

Para o comando ossutil correspondente à API PutObject, consulte put-object.

FAQ

Como modifico os metadados de um arquivo enviado?

É possível alterar metadados de arquivos através do console do OSS, ossbrowser, SDKs em diversas linguagens, interface de linha de comando ossutil ou API REST. Por exemplo, você pode mudar o Content-Type de application/octet-stream para image/jpeg. Para mais detalhes, veja Manage object metadata.

Por que o cabeçalho Expires que defini não funciona?

Prioridade dos cabeçalhos de cache

Se ambos Expires e Cache-Control forem definidos, Cache-Control terá prioridade. Caso Cache-Control contenha uma diretiva de cache, como max-age=3600, o cabeçalho Expires poderá ser ignorado.

Configuração incorreta do Expires

O valor do cabeçalho Expires deve ser uma data futura no formato GMT. O código abaixo exemplifica como configurar esse cabeçalho usando o SDK para Node.js:

const OSS = require('ali-oss');

// Create an OSS client instance.
const client = new OSS({
  // Replace yourregion with the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the Region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this example, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Specify the bucket name.
  bucket: 'examplebucket',
});

async function setExpires(objectName, expiresDate) {
  try {
    const result = await client.copy(objectName, objectName, {
      meta: {
        'Expires': expiresDate.toGMTString()
      }
    });
    console.log('Expires header set successfully.');
  } catch (error) {
    console.error('Error setting Expires header:', error);
  }
}

// Set the absolute expiration time for the cached content.
const expiresDate = new Date('2024-10-12T00:00:00.000Z');
setExpires('your-object-name', expiresDate);