Uploads objects.

Usage notes

  • The object that you want to upload cannot be larger than 5 GB in size.
  • By default, if an object that has the same name as the object that you want to upload exists in the bucket and you have access permissions on the existing object, the uploaded object overwrites the existing object and 200 OK is returned.
  • 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 versioned 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.

HeaderTypeRequiredExampleDescription
AuthorizationStringNoOSS lkojgn8y1exic6e:6****+BuuEqzI1tAMW0wgIyl****Specifies that the request is authorized. For more information about how to calculate the value of the Authorization header, see Include signatures 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 Add signatures to URLs.

This parameter is empty by default.

Cache-ControlStringNono-cacheThe caching behavior of the web page when the object is downloaded. Valid values:
  • no-cache: Each time you access a cached object, the server checks whether the object is updated. If the object is updated, the cache expires. The object must be downloaded from the server again. If the object is not updated, the cache does not expire, and you can directly use the cached object.
  • 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 value is available only in HTTP/1.1.

This parameter is empty by default.

Content-DispositionStringNoattachmentThe method that is used to access the object. Valid values:
  • Content-Disposition:inline: You can preview the object content.
  • Content-Disposition:attachment: The object is downloaded to the specified path of the browser with the original object name.
  • Content-Disposition:attachment; filename="yourFileName": The object is downloaded to the specified path of the browser with the custom object name.

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

Before the object is downloaded to the specified 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 object may be escaped. For example, if you download example*.jpg" to your local computer, example*.jpg" may be escaped as example_.jpg".
  • To ensure that the name of the file that is saved to the specified path does not contain garbled characters after an object whose name contains Chinese characters is downloaded, you must URL-encode the Chinese characters in the object name. If garbled characters appear when you download the test.txt object to your local computer, you must specify Content-Disposition to save the local file as test.txt in the following format: "attachment;filename="+URLEncoder.encode("test","UTF-8")+".txt;filename*=UTF-8''"+URLEncoder.encode("test","UTF-8")+".txt"). The local file name is URL-encoded as attachment;filename=%E6%B5%8B%E8%AF%95.txt;filename*=%E6%B5%8B%E8%AF%95.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 download 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-EncodingStringNoidentityThe 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 parameter empty. Valid values:
  • identity: 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.

This parameter is empty by default.

Content-MD5StringNoeB5eJF1ptWaXm4bijSPyxw==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 data 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.

This parameter is empty by default.

Content-LengthStringNo344606The 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 specified by Content-Length.

ETagStringNoD41D8CD98F00B204E9800998ECF8****The ETag that is generated when the object is created. ETags are used to identify the content of objects.
  • For an object that is created by calling the PutObject operation, the ETag value of the object is the MD5 hash of the object content.
  • For an object that is created by using another method, the ETag value is not the MD5 hash of the object content but a unique value calculated based on a specific rule.
Note You can use the ETag value of an object to check whether the object content is modified. We recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity.

This parameter is empty by default.

ExpiresStringNo2022-10-12T00:00:00.000ZThe expiration time of the cache in Greenwich Mean Time (GMT).

This parameter is empty by default.

x-oss-forbid-overwriteStringNofalseSpecifies whether the object that is uploaded by calling the PutObject operation overwrites an 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, the object that is uploaded cannot overwrite the existing object that has the same name.

If you specify the x-oss-forbid-overwrite header, the queries per second (QPS) performance of OSS may be degraded. If you want to specify the x-oss-forbid-overwrite header in a large number of requests (QPS greater than 1,000), contact technical support.

Default value: false

x-oss-server-side-encryptionStringNoAES256The method that is used to encrypt the 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 and is set to the algorithm that is used to encrypt the object.

x-oss-server-side-encryption-key-idStringNo9468da86-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 when the x-oss-server-side-encryption header is set to KMS.

x-oss-object-aclStringNodefaultThe access control list (ACL) of the object. Default value: default.
Valid values:
  • default: The ACL of the object is the same as that of the bucket in which the object is stored.
  • private: The ACL of the object is private. Only the owner of the object and authorized users have 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 read and write permissions on the object. Other users have only read permissions on the object. Exercise caution when you set the object ACL to this value.
  • public-read-write: The ACL of the object is public read/write. All users have read and write permissions on the object. Exercise caution when you set the object ACL to this value.

For more information about object ACLs, see Object ACL.

x-oss-storage-classStringNoStandardThe 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 IA bucket, the object is stored as a Standard object.

Valid values:
  • Standard
  • IA
  • Archive
  • ColdArchive

For more information about storage classes, see Overview.

x-oss-meta-*StringNox-oss-meta-locationIn a PutObject request, headers whose names contain the x-oss-meta-* prefix specify the metadata of the object that you want to upload. Example: x-oss-meta-location. You can specify multiple similar 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-taggingStringNoTagA=A&TagB=BThe tags of the object that are specified by using key-value pairs. You can configure multiple tags for the object. Example: TagA=A&TagB=B.
Note The tag key and value must be URL-encoded. The key is required and the value is optional. For example, you can set the tags to TagA&TagB=B.

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

Response headers

This request contains only common response headers. For more information, see Common response headers.

Examples

  • 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 qn6qrrqxo2oawuk53otf****:kZoYNv66bsmc10+dcGKw5x2P****
    Transfer-Encoding: chunked
    Sample 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: 0
    Content-MD5: 1B2M2Y8AsgTpgAmY7PhCfg==
    x-oss-server-time: 7
  • Upload an Archive object
    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 qn6qrrqxo2oawuk53otf****:kZoYNv66bsmc10+dcGKw5x2P**** 
    [344606 bytes of object data]
    Sample 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
    x-oss-bucket-version: 1418321259
    ETag: "A797938C31D59EDD08D86188F6D5B872"
  • Upload objects to a versioned 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 lkojgn8y1exic6e:6****+BuuEqzI1tAMW0wgIyl****
    Sample 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 codeHTTP status codeDescription
MissingContentLength411 The error message returned because the request header is not encoded by means of chunked encoding or the Content-Length header is not specified.
InvalidEncryptionAlgorithmError400 The error message returned because the specified value of the x-oss-server-side-encryption header is invalid.

Valid values: AES256 and KMS.

AccessDenied403 The error message returned because you do not have the permissions to access the specified bucket to which you want to upload the object.
NoSuchBucket404The error message returned because the specified bucket to which you want to upload the object does not exist.
InvalidObjectName400 The error message returned because the length of the specified object key exceeds 1,023 bytes.
InvalidArgument400 The error message returned because of the following possible causes:
  • The object that you want to upload is larger than 5 GB in size.
  • The values of parameters such as x-oss-storage-class are invalid.
RequestTimeout400 The error message returned because 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 Request400The error message returned because 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.
KmsServiceNotEnabled403 The error message returned because the x-oss-server-side-encryption header is set to KMS, but KMS is not activated in advance.
FileAlreadyExists409 The error message returned because of the following possible causes:
  • The request contains the x-oss-forbid-overwrite=true header, but an object that has the same name as the object that you want to upload exists.
  • 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.
FileImmutable409The error message returned because 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 in the OSS console, and by using ossbrowser, OSS SDKs for various programming languages, ossutil, and REST APIs. For example, you can change the value of the Content-Type parameter from application/octet-stream to image/jpeg. For more information, see Manage object metadata.