All Products
Search
Document Center

Object Storage Service:PutObject

Last Updated:Sep 23, 2024

Uploads objects.

Usage notes

  • You cannot call this operation to upload an object that is larger than 5 GB in size.

  • By default, if an existing object in the bucket has the same name as the object that you want to upload and you have access permissions on the existing object, the upload operation overwrites the existing object and returns 200 OK.

  • Object Storage Service (OSS) uses a flat structure for all resources instead of a hierarchical structure to store these resources as objects. However, you can create a simulated directory by creating an empty object whose name ends with a forward slash (/).

Versioning

If you call the PutObject operation to upload an object to a versioning-enabled bucket, OSS generates a unique version ID for the uploaded object and returns the version ID as the value of the x-oss-version-id header in the response.

If you call the PutObject operation to upload an object to a versioning-suspended bucket, OSS generates a version ID of null for the uploaded object. An object can have only one version whose ID is null.

Request syntax

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

Request headers

OSS supports the following HTTP request headers: Cache-Control, Expires, Content-Encoding, Content-Disposition, and Content-Type. If you specify these headers when you upload an object, the headers are automatically set to the specified values when you download the object.

Header

Type

Required

Example

Description

Authorization

String

No

OSS qn6q**************:77Dv****************

Specifies that the request is authorized. For more information about how to calculate the Authorization header, see Include a V1 signature in the Authorization header.

In most cases, you must specify the Authorization header. However, if you use a signed URL in a PutObject request, you do not need to specify the Authorization header. For more information, see Include a V1 signature in a URL.

By default, this header is left empty.

Cache-Control

String

No

no-cache

The caching behavior of the web page when the object is downloaded. Valid values:

  • no-cache: The cached content cannot be used directly. Cached content must be validated with the server to check whether object content is updated. If the object content is updated, the cached content expires and the object is downloaded from the server again. If the object content is not updated, the cache does not expire, and the object is directly available from the cache.

  • no-store: All content of the object is not cached.

  • public: All content of the object is cached.

  • private: All content of the object is cached only on the client.

  • max-age=<seconds>: the validity period of the cached content. Unit: seconds. This option is available only in HTTP 1.1.

By default, this header is left empty.

Content-Disposition

String

No

attachment

The method that is used to display the object. Valid values:

  • Content-Disposition:inline: The object is displayed in the browser for a content preview.

  • Content-Disposition:attachment: The object is downloaded to the specified download path of the browser with the original object name.

  • Content-Disposition:attachment; filename="yourFileName": The object is downloaded to the specified download path of the browser with a custom object name.

    yourFileName specifies the custom name of the downloaded object, such as example.jpg.

If you want to download the object to the specified download path of the browser, take note of the following items:

Note
  • If the name of the object contains special characters such as asterisks (*) or forward slashes (/), the name of the downloaded object may be escaped. For example, if you download example*.jpg to your local computer, example*.jpg may be escaped as example_.jpg.

  • To prevent a download of an object with Chinese characters included in the object name from creating a local file with garbled characters in the file name, you must URL-encode the Chinese characters in the object name. For example, to ensure that the 测试.txt object in OSS is downloaded as a local file that has the original object name 测试.txt, you must set the Content-Disposition header to attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename*=UTF-8''%E6%B5%8B%E8%AF%95.txt, which derives from "attachment;filename="+URLEncoder.encode("测试","UTF-8")+".txt;filename*=UTF-8''"+URLEncoder.encode("测试","UTF-8")+".txt".

Whether an object is previewed or downloaded as an attachment when the object is accessed by using the object URL is determined by the creation time of the bucket in which the object is stored, the activation time of OSS, and the domain name type. For more information, see 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?

By default, this header is left empty.

Content-Encoding

String

No

identity

The method that is used to encode the object. You must specify this header based on the encoding type of the object. Otherwise, the browser that serves as the client may fail to parse the encoding type of the object, or the object may fail to be downloaded. If the object is not encoded, leave this header empty. Valid values:

  • identity (default): OSS does not compress or encode the object.

  • gzip: OSS uses the LZ77 compression algorithm created by Lempel and Ziv in 1977 and 32-bit cyclic redundancy check (CRC) to encode the object.

  • compress: OSS uses the Lempel–Ziv–Welch (LZW) compression algorithm to encode the object.

  • deflate: OSS uses the zlib library and the deflate algorithm to encode the object.

  • br: OSS uses the Brotli algorithm to encode the object.

By default, this header is left empty.

Content-MD5

String

No

eB5eJF1ptWaXm4bijSPyxw==

The MD5 hash of the object that you want to upload. The Content-MD5 value is calculated by using the MD5 algorithm. If you specify the Content-MD5 header in a PutObject request, OSS calculates the Content-MD5 value based on the message body and checks whether the calculated Content-MD5 value is the same as the Content-MD5 value that is specified in the request header. For more information, see Calculation of Content-MD5.

To ensure data integrity, OSS provides multiple methods to check the MD5 hash of the object that you want to upload. To verify the MD5 hash of the object that you want to upload based on the Content-MD5 header, add the Content-MD5 header to the request.

By default, this header is left empty.

Content-Length

String

No

344606

The size of the data in the HTTP message body. Unit: bytes.

If the value of the Content-Length header in the request is smaller than the size of the data in the request body, the object can still be created. However, the data is truncated to the object size that is specified by the Content-Length header.

ETag

String

No

D41D8CD98F00B204E9800998ECF8****

The ETag that is generated when the object is created. ETags are used to identify the content of objects.

  • If an object is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.

  • If an object is created by using another method, the ETag value is not the MD5 hash of the object content but a unique value that is calculated based on a specific rule.

Note

The ETag value of an object can be used to check whether the object content is modified. We recommend that you use the MD5 hash of an object instead of the ETag value of the object to verify data integrity.

By default, this header is left empty.

Expires

String

No

2022-10-12T00:00:00.000Z

The absolute expiration time of the cache in Greenwich Mean Time (GMT).

By default, this header is left empty.

x-oss-forbid-overwrite

String

No

false

Specifies whether the object that is uploaded by calling the PutObject operation overwrites the existing object that has the same name. When versioning is enabled or suspended for the bucket to which you want to upload the object, the x-oss-forbid-overwrite header does not take effect. In this case, the object that is uploaded by calling the PutObject operation overwrites the existing object that has the same name.

  • If you do not specify the x-oss-forbid-overwrite header or you set the x-oss-forbid-overwrite header to false, the object that is uploaded by calling the PutObject operation overwrites the existing object that has the same name.

  • If you set the x-oss-forbid-overwrite header to true, an existing object that has the same name cannot be overwritten.

If you specify the x-oss-forbid-overwrite header, the queries per second (QPS) performance of OSS is degraded. If you want to configure the x-oss-forbid-overwrite header in a large number of requests (QPS > 1,000), submit a ticket.

Default value: false.

x-oss-server-side-encryption

String

No

AES256

The method that is used to encrypt the uploaded object on the OSS server when the object is created.

Valid values: AES256 and KMS.

If you specify the x-oss-server-side-encryption header, the x-oss-server-side-encryption header is returned in the response. OSS uses the method that is specified by this header to encrypt the uploaded object. When you download the object, the x-oss-server-side-encryption header is included in the response. The value of the header in the response is the algorithm that is used to encrypt the object.

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

String

No

9468da86-3509-4f8d-a61e-6eab1eac****

The ID of the customer master key (CMK) that is managed by Key Management Service (KMS).

This header is valid only if the x-oss-server-side-encryption header is set to KMS.

x-oss-object-acl

String

No

default

The access control list (ACL) of the object.

Valid values:

  • default: The ACL of the object is the same as that of the bucket in which the object is stored. This is the default value.

  • private: The ACL of the object is private. Only the owner of the object and authorized users have the read and write permissions on the object.

  • public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you set the ACL of the object to this value.

  • public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you set the ACL of the object to this value.

For more information, see Object ACLs.

x-oss-storage-class

String

No

Standard

The storage class of the object.

If you specify the x-oss-storage-class header when you upload an object, the storage class of the uploaded object is the specified value regardless of the storage class of the bucket to which the object is uploaded. For example, if you set the x-oss-storage-class header to Standard when you upload an object to an Infrequent Access (IA) bucket, the object is stored as a Standard object.

Valid values:

  • Standard

    Note

    If you use OSS on CloudBox, only the Standard storage class is supported.

  • IA

  • Archive

  • ColdArchive

  • DeepColdArchive

    Important

    If you want to upload a large number of objects and set the storage classes of the objects to Deep Cold Archive, you are charged high PUT request fees. We recommend that you set the storage classes of the objects to Standard when you upload the objects, and configure lifecycle rules to convert the storage classes of the Standard objects to Deep Cold Archive. This reduces PUT request fees.

For more information about the storage classes, see Overview.

x-oss-meta-*

String

No

x-oss-meta-location

Specifies the metadata of the object. If you configure a parameter that contains the x-oss-meta- parameter, the parameter specifies metadata. Example: x-oss-meta-location. You can specify multiple metadata headers for an object. However, the metadata of an object cannot exceed 8 KB in size.

The names of metadata headers can contain letters, digits, and hyphens (-). Uppercase letters are converted to lowercase letters. Other characters, such as underscores (_), are not supported.

x-oss-tagging

String

No

TagA=A&TagB=B

The tag you want to specify for the object by using a key-value pair. You can specify multiple tags for an object. Example: TagA=A&TagB=B.

Note

The tag key and tag value must be URL-encoded. When you specify a tag for an object, only the tag key is required and the tag value is optional. Example: TagA&TagB=B.

For more information about the common request headers in a PutObject request, such as Host and Date, see Common request headers.

Response headers

Header

Type

Example

Description

Content-MD5

String

1B2M2Y8AsgTpgAmY7PhC****

The MD5 hash of the object.

Important

The MD5 hash of the object is obtained after the client uploads the object. The MD5 hash of the object is not the MD5 hash in the response body.

x-oss-hash-crc64ecma

String

316181249502703****

The CRC-64 value of the object.

x-oss-version-id

String

CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****

The version ID of the object. This header is returned only if you upload the object to a versioning-enabled bucket.

For more information about the common response headers, such as Date and x-oss-request-id, in the response to a PutObject request, see Common HTTP headers.

Examples

  • Upload an object by using simple upload

    Sample requests

    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: OSS qn6q**************:77Dv****************
    Transfer-Encoding: chunked

    Sample success responses

    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
  • Upload an object and set the storage class of the object to Archive

    Sample requests

    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-Encoding: utf-8
    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: OSS qn6q**************:77Dv**************** 
    [344606 bytes of object data]

    Sample success responses

    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"
  • Upload an object to a versioning-enabled bucket

    Sample requests

    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: OSS qn6q**************:77Dv****************

    Sample success responses

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

SDK

You can use OSS SDKs for the following programming languages to call the PutObject operation:

Error codes

Error code

HTTP status code

Description

MissingContentLength

411

The request headers are not encoded by using chunked encoding or the Content-Length header is not specified.

InvalidEncryptionAlgorithmError

400

The specified value of the x-oss-server-side-encryption header is invalid.

Valid values: AES256 and KMS.

AccessDenied

403

You do not have the permissions to access the specified bucket to which you want to upload the object.

NoSuchBucket

404

The specified bucket to which you want to upload the object does not exist.

InvalidObjectName

400

The length of the specified object key exceeds 1,023 bytes.

InvalidArgument

400

Possible causes:

  • The object that you want to upload is larger than 5 GB in size.

  • The values of headers, such as x-oss-storage-class, are invalid.

RequestTimeout

400

The Content-Length header is specified in the request but the message body is not sent, or the size of the data in the message body is less than the specified value. In this case, the server waits until the request times out.

Bad Request

400

The Content-MD5 value that is specified in the request header is different from the MD5 hash that is calculated by OSS. OSS calculates the MD5 hash based on the message body and compares the calculated MD5 hash with the Content-MD5 value that is specified in the request header.

KmsServiceNotEnabled

403

The x-oss-server-side-encryption header is set to KMS, but KMS is not activated in advance.

FileAlreadyExists

409

Possible causes:

  • The request contains the x-oss-forbid-overwrite=true header, and the bucket contains an object that has the same name as the object specified in the request.

  • The hierarchical namespace feature is enabled for the bucket, and a directory that has the same name as the object that you want to upload exists in the current directory level.

FileImmutable

409

The data that you want to delete or modify is being protected. During the protection period, data in the bucket cannot be deleted or modified.

FAQ

Can I modify the metadata of an uploaded object?

Yes, you can modify the metadata of an uploaded object by using the OSS console, ossbrowser, OSS SDKs for various programming languages, ossutil, or OSS API. For example, you can change the value of the Content-Type header from application/octet-stream to image/jpeg. For more information, see Manage object metadata.

Why is the specified value of the Expires header invalid?

  • Priority of headers

    When you specify both the Expires and Cache-Control headers, the value of the Cache-Control header takes precedence over that of the Expires header. The browser checks whether the Cache-Control header is configured and the specified value of the Expires header only takes effect if no valid value is specified for the Cache-Control header. If the Cache-Control header contains a cache management instruction, such as Cache-Control:max-age=3600, the Expires header may be ignored.

  • Invalid value of the Expires header

    The Expires header specifies the absolute expiration time of the cache in GMT and its value must be a valid point in time in the future. If the specified value of the Expires header has expired or is in an invalid format, the header is considered invalid. The following sample code provides an example on how to specify the Expires header by using OSS SDK for Node.js:

    const OSS = require('ali-oss');
    
    // Create an OSS client instance.
    const client = new OSS({
      // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
      region: 'yourregion',
      // Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
      accessKeyId: process.env.OSS_ACCESS_KEY_ID,
      accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
      // Specify the name of the bucket. 
      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);
      }
    }
    
    // Specify the absolute expiration time of the cache. 
    const expiresDate = new Date('2024-10-12T00:00:00.000Z');
    setExpires('your-object-name', expiresDate);