Uploads objects.
Usage notes
You cannot use 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 lkojgn8y1exic6e:6****+BuuEqzI1tAMW0wgIyl**** | Specifies that the request is authorized. For more information about how to calculate 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 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:
By default, this header is left empty. |
Content-Disposition | String | No | attachment | The method that is used to access the object. Valid values:
Before the object is downloaded to the specified path of the browser, take note of the following items: Note
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:
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 Include signatures in the Authorization header. 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. 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.
Note The ETag of an object can be used to check whether the object content changes. We recommend that you use the MD5 hash of an object rather than 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 expiration time of the cache in UTC. 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 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 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 encryption method on the server side when an 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 when 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:
For more information about ACLs, see Object ACL. |
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 IA bucket, the object is stored as a Standard object. Valid values:
For more information about the storage classes, see Overview. |
x-oss-meta-* | String | No | x-oss-meta-location | The metadata of the object that you want to upload. Example: 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 tags that are specified for the object by using a key-value pair. You can specify multiple tags for an object. Example: Note The tag key and value must be URL-encoded. When you specify a tag for the object, only the key of the tag is required and the value is optional. For example, you can set the value of this header to |
For more information about the common request headers such as Host and Date, see Common HTTP headers.
Response headers
This request contains only common response headers. For more information, see Common HTTP headers.
Examples
Upload an object by using simple upload
Sample request
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 response
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 request
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 response
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 request
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 response
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 request header is 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:
|
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:
|
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, OSS API, ossbrowser, OSS SDKs for various programming languages, or ossutil. 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.