API PutObject do Object Storage Service - 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, utilize o recurso de upload multipart.
Ao enviar um arquivo com nome idêntico ao de outro já existente, o sistema sobrescreve o original por padrão e retorna o código de status 200 OK. Defina um parâmetro para impedir essa substituição e evitar a perda acidental de dados 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 barra (/).

Permissões

Uma conta Alibaba Cloud possui permissões completas por padrão. No entanto, usuários ou funções do Resource Access Management (RAM) vinculados à conta não têm permissões até que a conta Alibaba Cloud ou um administrador as conceda por meio de uma Política do RAM ou de uma Política de Bucket.

API	Action	Descrição
PutObject	`oss:PutObject`	Envia um objeto.
	`oss:PutObjectTagging`	Necessário caso você especifique 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 momento do upload.
	`kms:Decrypt`

Versionamento

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, seus 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 Incluir uma assinatura no cabeçalho. Geralmente, o cabeçalho Authorization é obrigatório. Contudo, ele se torna desnecessário se a assinatura for incluída diretamente na URL. Veja mais em Incluir uma assinatura na 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 os dados com o servidor de origem antes de servi-los. 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 o seguinte: Nota Se o nome do objeto contiver caracteres especiais, como asteriscos () ou barras (/), o nome do arquivo baixado poderá ser escapado. 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 com caracteres não ASCII, aplique codificação URL neles. Por exemplo, para baixar o objeto `Test.txt` preservando 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 decisão entre pré-visualizar ou baixar o objeto como anexo depende da data de criação do bucket, da ativação do OSS e do tipo de domínio utilizado. Consulte O que fazer se um objeto de imagem for baixado como anexo e não puder ser visualizado ao acessar sua URL? para mais informações. Valor padrão: nenhum
Content-Encoding	String	Não	identity	Declara a codificação do objeto. Especifique a codificação real utilizada; caso contrário, podem ocorrer falhas de análise ou download no cliente. Deixe este cabeçalho vazio se não houver codificação. Valores válidos: identity (padrão): Sem compressão ou codificação. gzip: Codificado com algoritmo LZ77 e CRC de 32 bits. compress: Codificado com algoritmo LZW. deflate: Codificado com zlib e algoritmo deflate. br: Codificado com algoritmo Brotli. Valor padrão: nenhum
Content-MD5	String	Não	eB5eJF1ptWaXm4bijSPyxw==	Verifica a integridade do conteúdo da mensagem. O Content-MD5 é gerado pelo algoritmo MD5. Se definido, o OSS calcula o hash Content-MD5 do corpo da mensagem e valida a consistência. Saiba mais em Como calcular o Content-MD5. Para garantir a integridade dos dados, o OSS oferece diversos métodos de verificação de hash MD5. Para validar usando 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 enviados 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 sobrescrita 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 substituição. A ausência do parâmetro x-oss-forbid-overwrite ou sua definição como false permite sobrescrever objetos homônimos. Definir x-oss-forbid-overwrite como true impede a substituição de objetos existentes. O uso do cabeçalho x-oss-forbid-overwrite impacta o desempenho de QPS. Caso suas operações exijam frequentemente esse cabeçalho (QPS>1000), entre em contato com o suporte técnico para evitar prejuízos às suas atividades. 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, a resposta inclui o cabeçalho 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 possuem permissão de leitura e escrita. Outros usuários não têm acesso. 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 podem ler e gravar no objeto. Use esta permissão com extrema cautela. Para detalhes sobre permissões de acesso, consulte ACL de objeto.
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 força o armazenamento na classe indicada. Por exemplo, ao definir x-oss-storage-class como Standard em um bucket Infrequent Access (IA), o objeto será armazenado como Standard. Valores válidos: Standard: Padrão IA: Acesso Infrequente Archive: Armazenamento de Arquivo ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Importante Consulte Classes de armazenamento para mais informações.
x-oss-meta-*	String	Não	x-oss-meta-location	Na API PutObject, parâmetros com prefixo x-oss-meta- funcionam 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. Os 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 Tanto a chave quanto o valor devem passar por codificação URL. A chave é obrigatória, enquanto o valor é opcional. Por exemplo, é válido definir as tags como `TagA&TagB=B`.

Para mais detalhes, consulte Cabeçalhos de resposta comuns.

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 aparece apenas quando o upload ocorre em um bucket com versionamento habilitado.

Para mais detalhes, consulte Cabeçalhos de resposta comuns.

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

Código de erro	Código de status HTTP	Descrição
MissingContentLength	411	O cabeçalho da solicitação não utiliza codificação chunked ou falta o parâmetro Content-Length.
InvalidEncryptionAlgorithmError	400	O valor informado 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 formatação incorreta.
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 valor inválido.
RequestTimeout	400	O parâmetro Content-Length foi especificado, mas nenhum corpo de mensagem foi enviado, ou o tamanho enviado é inferior ao declarado. Nessas situações, 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 recebidos e compara com o valor fornecido. A discrepância entre os valores resulta neste erro.
KmsServiceNotEnabled	403	Você definiu KMS para x-oss-server-side-encryption, mas não adquiriu previamente o pacote KMS.
FileAlreadyExists	409	Possíveis causas: O cabeçalho inclui `x-oss-forbid-overwrite=true` para evitar substituições, porém 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.

Perguntas frequentes

Como modifico os metadados de um arquivo já enviado?

É possível alterar os 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, altere o Content-Type de application/octet-stream para image/jpeg. Veja mais em Gerenciar metadados de objetos.

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

Prioridade dos cabeçalhos de cache

Ao configurar simultaneamente Expires e Cache-Control, o Cache-Control prevalece. Se o Cache-Control incluir diretivas 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 representar uma data futura no formato GMT. O código abaixo demonstra como configurar esse cabeçalho utilizando o SDK 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);