Uploads objects.

Usage notes

  • The object that you want to upload cannot be larger than 5 GB in size.
  • By default, if you upload an object whose name is the same as that of an existing object on which you have permissions, the existing object is overwritten by the uploaded object and 200 OK is returned.

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 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 version 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 five HTTP request headers: Cache-Control, Expires, Content-Encoding, Content-Disposition, and Content-Type. If these headers are configured when you upload an object, the headers are automatically set to the configured values when you download the object.

Header Type Required Description
Authorization String No Specifies that the request is authorized. For more information, see RFC 2616. For more information about how to calculate the value of this header, see Include signatures in the Authorization header.

The Authorization header is required in most cases. However, if you use a signed URL in a PutObject request, this header is not required. For more information, see Add signatures to a URL.

Default value: null
Cache-Control String No The caching behavior of the web page when the object is downloaded. For more information, see RFC 2616.

Default value: null
Content-Disposition String No The name of the object when the object is downloaded. For more information, see RFC 2616.

Default value: null
Content-Encoding String No The content encoding format of the object when the object is downloaded. For more information, see RFC 2616.

Default value: null
Content-MD5 String No 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 uploaded data. To verify the MD5 hash of an uploaded object based on the Content-MD5 header, add the Content-MD5 header to the request.

Default value: null
Content-Length String No The size of the data in the HTTP message body.

If the value of the Content-Length header in the request is less than the size of the data in the message 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 The entity tag (ETag) that is generated when an object is created. ETags are used to identify the content of objects.
  • If an object is created by using a PutObject request, the ETag value of the object is the MD5 hash of the object content.
  • If an object is created by using other methods, the ETag value of the object is not the MD5 hash of the object content but a unique value calculated based on a specific rule.
Note The ETag value of an object can be used to check whether the object content is modified. However, we recommend that you use the MD5 hash of an object rather than the ETag value of the object to verify data integrity.

Default value: null
Expires String No The expiration time. For more information, see RFC 2616.

Default value: null
x-oss-forbid-overwrite String No 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 the x-oss-forbid-overwrite header is not specified or the value of the x-oss-forbid-overwrite header is set to false, the object that is uploaded by calling the PutObject operation overwrites the existing object that has the same name.
  • If the value of the x-oss-forbid-overwrite header is set to true, the object that is uploaded by calling the PutObject operation does not 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 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 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 header in a PutObject request, the 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 the header value is set to the algorithm that is used to encrypt the object.

x-oss-server-side-encryption-key-id String No The ID of the customer master key (CMK) hosted in Key Management Service (KMS).

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

x-oss-object-acl String No The 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 can read and write this object.
  • public-read: The ACL of the object is public-read. Only the owner of the object and authorized users can read and write this object. Other users can only read 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 can read and write this object. Exercise caution when you set the object ACL to this value.

For more information about ACLs, see ACL.

x-oss-storage-class String No The storage class of the object.

If you specify the header when you upload an object, the storage class of the uploaded object is the specified header 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-* String No In a PutObject request, headers whose names contain the x-oss-meta-* prefix specify the user 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 user metadata of an object cannot exceed 8 KB in size.

The names of user 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 The tag of the object. You can configure multiple tags for the object. Example: TagA=A&TagB=B.
Note The key and value of a tag must be URL-encoded. If a tag does not contain an equal sign (=), the value of the tag is considered an empty string.

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

Response headers

The response to a PutObject request contains only common response headers. For more information, see Common response 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 qn6qrrqxo2oawuk53otfjbyc: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 qn6qrrqxo2oawuk53otfjbyc: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 an object 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:6yYhX+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****"

SDKs

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 error message returned because the request header is not encoded by using chunked encoding or the Content-Length header is not specified.
InvalidEncryptionAlgorithmError 400 The error message returned because the specified value of the x-oss-server-side-encryption header is invalid.

Valid values: AES256 and KMS

AccessDenied 403 The error message returned because you do not have permissions to access the specified bucket to which you want to upload the object.
NoSuchBucket 404 The error message returned because the specified bucket to which you want to upload the object does not exist.
InvalidObjectName 400 The error message returned because 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 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 Request 400 The 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.
KmsServiceNotEnabled 403 The error message returned because 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, but an existing object has the same name as the object that you want to upload.
  • 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 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.