You can call this operation to upload objects.

Note
  • You cannot upload objects larger than 5 GB.
  • By default, if you upload an object with the same name as that of an accessible existing object, the existing object is overwritten by the uploaded object and 200 OK is returned.
  • OSS does not use folders. All elements are stored as objects. You can create a simulated folder by creating an object whose name ends with a forward slash (/) and that is 0 KB in size.
  • To ensure data integrity, OSS uses MD5 hashes of the data in a couple different manners. To enforce Content-MD5, add the header to the request. When the Content-MD5 header is specified in a request, OSS calculates the MD5 hash of the sent data and checks it with the Content-MD5 specified in the request. If the two hashes do not match, the operation fails and an 400 (Bad Request) error is returned.

Versioning

If you initiate a PutObject request to a versioning-enabled bucket, OSS automatically generates a unique version ID for the uploaded object and includes the version ID in the x-oss-version-id response header. If you initiate a PutObject request to a versioning-suspended bucket, OSS automatically generates a null version ID for the uploaded object. An object can only have one null version ID.

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

Note OSS supports five request headers specified in HTTP: Cache-Control, Expires, Content-Encoding, Content-Disposition, and Content-Type. If these headers are set when you upload an object, the corresponding header values are automatically set to the uploaded values next time this object is downloaded.
Header Type Required Description
Authorization String No Indicates that the request is authorized. For more information, visit RFC 2616.

The Authorization header is required in most cases. This header is optional if the request URL contains a signature. For more information, see Add a signature to a URL.

This parameter is empty by default.

Cache-Control String No Specifies the web page caching behavior when the object is downloaded. For more information, visit RFC 2616.

This parameter is empty by default.

Content-Disposition String No Specifies the name of the object when the object is downloaded. For more information, visit RFC 2616.

This parameter is empty by default.

Content-Encoding String No Specifies the content encoding format when the object is downloaded. For more information, visit RFC 2616.

This parameter is empty by default.

Content-MD5 String No Checks whether the message content is consistent with the sent content. The value of Content-MD5 is calculated based on the MD5 algorithm. After the Content-MD5 request header is uploaded, OSS calculates the value of Content-MD5 and checks the consistency. For more information about how to calculate the value of Content-MD5, see Calculate the Content-MD5 value.

This parameter is empty by default.

Content-Length String No Specifies the data size in the HTTP request body.

If the value of Content-Length in the request header is smaller than that of the data length in the actual request body, OSS can still create an object. However, the object size is the value of Content-Length, and the remaining data is dropped.

ETag String No Specifies the entity tag (ETag) that is generated when an object is created. Etags are used to indicate the content of the objects.
  • For an object that is created with a PutObject request, the ETag value is the MD5 value of the object content.
  • For an object that is created by using other methods, the ETag value is the UUID of the object content.
Note The ETag value of the object can be used to check whether the object content is modified. However, we recommend that you do not use the ETag of an object as the MD5 value of the object to verify data integrity.

This parameter is empty by default.

Expires String No Specifies the expiration time. For more information, visit RFC 2616.

This parameter is empty by default.

x-oss-forbid-overwrite String No Specifies whether the PutObject operation overwrites the object with the same name.
  • By default, if x-oss-forbid-overwrite is not specified, the object with the same name is overwritten.
  • If x-oss-forbid-overwrite is set to true, the object with the same name cannot be overwritten. If x-oss-forbid-overwrite is set to false, the object with the same name can be overwritten.
Note
  • The x-oss-forbid-overwrite request header is invalid when the versioning state of the target bucket is Enabled or Suspended. In this case, the PutObject operation overwrites the object with the same name.
  • Specifying the x-oss-forbid-overwrite request header may degrade the query per second (QPS) performance of OSS. If you want to use the x-oss-forbid-overwrite request header for a large number of operations (QPS > 1000), submit a ticket.
x-oss-server-side-encryption String No Specifies the server-side encryption algorithm that is used when OSS creates the object.

Valid values: AES256 and KMS. You must activate KMS to use the KMS-based encryption algorithm. Otherwise, a KmsServiceNotEnabled error code is returned.

If you specify this parameter, it is returned in the response header and the uploaded object is encrypted. When you download the encrypted object, the x-oss-server-side-encryption field is included in the response header and its value is set to the algorithm used to encrypt the object.

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

This parameter takes effect only when x-oss-server-side-encryption is set to KMS.

x-oss-object-acl String No Specifies the ACL configured when OSS creates the object.

Valid values: public-read, private, and public-read-write

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

If the storage class is specified when you upload the object, the specified storage class applies regardless of the storage class of the bucket that contains the object. If you set x-oss-storage-class to Standard when you upload an object to an IA bucket, the object is stored as a Standard object.

Valid values: Standard, IA, Archiveand ColdArchive

Supported operations: PutObject, InitiateMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

x-oss-meta-* String No If the PutObject request contains a parameter prefixed with x-oss-meta-, the parameter is considered as the user metadata. Example: x-oss-meta-location. An object may have multiple similar parameters, but the total size of the user metadata cannot exceed 8 KB.

Metadata supports hyphens (-), digits, and letters. Uppercase letters are converted to lowercase letters, and other characters such as underscores (_) are not supported.

x-oss-tagging String No Specifies the tag for the object. You can set multiple tags for the object. Example: TagA=A&TagB=B.
Note The tag key and value must be URL-encoded. If a key-value pair does not contain an equal sign (=), the tag value is considered as an empty string.

Examples

  • Sample request for simple upload
    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 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
  • Sample request for uploading objects to Archive buckets
    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 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
    x-oss-bucket-version: 1418321259
    ETag: "A797938C31D59EDD08D86188F6D5B872"
  • Sample request for uploading objects to versioning-enabled buckets
    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 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

Error codes

Error code HTTP status code Description
MissingContentLength 411 Th error message returned because the request header is not encoded by using chunked encoding, and the Content-Length parameter is not specified.
InvalidEncryptionAlgorithmError 400 The error message returned because the specified value of x-oss-server-side-encryption is invalid.

Valid values: AES256 and KMS.

AccessDenied 403 The error message returned because you are not authorized to access the bucket to which you want to add objects.
NoSuchBucket 404 The error message returned because the bucket to which the object is to be added does not exist.
InvalidObjectName 400 The error message returned because the length of the input object key has exceeded 1,023 bytes.
InvalidArgument 400
  • The error message returned because the size of the object to be added has exceeded 5 GB.
  • The error message returned because the values of parameters such as x-oss-storage-class are invalid.
RequestTimeout 400 The error message returned because Content-Length was specified, but the message body was not sent, or the sent message body was smaller than the specified size. In this case, the server waits until it times out.
KmsServiceNotEnabled 403 The error message returned because x-oss-server-side-encryption is set to KMS. However, you did not activate KMS in advance.
FileAlreadyExists 409 The error message returned because an object with the same name already exists when the request contains an x-oss-forbid-overwrite header and the value of this header is set to true.