Help Center/ Object Storage Service/ API Reference/ APIs/ Operations on Objects/ Uploading an Object - PUT
Updated on 2024-05-31 GMT+08:00
View PDF

Uploading an Object - PUT

Functions

After creating a bucket in OBS, you can use this operation to upload an object to the bucket. This operation uploads an object to a bucket. To use this operation, you must have the write permission for the bucket.

The name of each object in a bucket must be unique.

With versioning not enabled, if an object to be uploaded has the same name as an existing object in the bucket, the newly uploaded object will overwrite the existing one. To protect data from being corrupted during transmission, you can add the Content-MD5 header in the request. After receiving the uploaded object, OBS compares the provided MD5 value to the MD5 value it calculates. If the two values do not match, OBS reports an error.

You can also specify the value of the x-obs-acl parameter to configure an access control policy for the object. If the x-obs-acl parameter is not specified when an anonymous user uploads an object, the object can be accessed by all OBS users by default.

This operation supports server-side encryption.

For a single upload, the size of the object to be uploaded ranges [0, 5 GB]. To upload a file greater than 5 GB, see Operations on Multipart Upload.

OBS does not have real folders. To facilitate data management, OBS provides a method to simulate a folder by adding a slash (/) to the object name, for example, test/123.jpg. You can simulate test as a folder and 123.jpg as the name of a file under the test folder. However, the object key remains test/123.jpg. Objects named in this format appear as folders on the console. When you upload an object larger than 0 in size using this format, an empty folder will be displayed on the console, but the occupied storage capacity is the actual object size.

An object name containing special characters must be URL encoded. For example, #obj must be encoded as %23obj.

Differences Between PUT and POST Methods

Parameters are passed through the request header if the PUT method is used to upload objects; if the POST method is used to upload objects, parameters are passed through the form field in the message body.

With the PUT method, you need to specify the object name in the URL, but object name is not required with the POST method, which uses the bucket domain name as the URL. Request lines of these two methods are given as follows:

PUT /ObjectName HTTP/1.1
POST / HTTP/1.1

For details about POST upload, see Uploading an Object - POST.

Versioning

If versioning is enabled for a bucket, the system automatically generates a unique version ID for the requested object in this bucket and returns the version ID in response header x-obs-version-id. If versioning is suspended for the bucket, the object version ID is null. For details about the versioning statuses of a bucket, see Configuring Versioning for a Bucket.

Request Syntax

1
2
3
4
5
6
7
8
 
PUT /ObjectName HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.eu
Content-Type: application/xml 
Content-Length: length
Authorization: authorization
Date: date
<Optional Additional Header> 
<object Content>

Request Parameters

This request contains no parameters.

Request Headers

This request uses common headers. For details, see Table 3. The request can use additional headers, as listed in Table 1.

OBS supports the six HTTP request headers: Cache-Control, Expires, Content-Encoding, Content-Disposition, Content-Type, and Content-Language. If these headers are carried in an object upload request, their values are saved. You can also call the metadata modification API, provided by OBS, to change the values of the six headers. When the object is downloaded or queried, the saved values are set for corresponding HTTP headers and returned to the client.

Table 1 Request headers

Header

Description

Mandatory

Content-MD5

Base64-encoded 128-bit MD5 digest of the message according to RFC 1864.

Type: string

Example: n58IG6hfM7vqI4K0vnWpog==

No

x-obs-acl

When creating an object, you can add this header to set the permission control policy for the object. The predefined common policies are as follows: private, public-read, and public-read-write. For details about each policy, see the ACL configuration using header fields in ACLs.

Type: string

Note: This header is a predefined policy expressed in a character string.

Example: x-obs-acl: public-read

No

x-obs-grant-read

When creating an object, you can use this header to grant all users in an account the permissions to read the object and obtain the object metadata.

Type: string

Example: x-obs-grant-read: id=domainID. If multiple accounts are authorized, separate them with commas (,).

No

x-obs-grant-read-acp

When creating an object, you can use this header to grant all users in an account the permissions to obtain the object ACL.

Type: string

Example: x-obs-grant-read-acp: id=domainID. If multiple accounts are authorized, separate them with commas (,).

No

x-obs-grant-write-acp

When creating an object, you can use this header to grant all users in an account the permission to write the object ACL.

Type: string

Example: x-obs-grant-write-acp: id=domainID. If multiple accounts are authorized, separate them with commas (,).

No

x-obs-grant-full-control

When creating an object, you can use this header to grant all users in an account the permissions to read the object, obtain the object metadata and ACL, and write the object ACL.

Type: string

Example: x-obs-grant-full-control: id=domainID. If multiple accounts are authorized, separate them with commas (,).

No

x-obs-storage-class

When creating an object, you can use this header to specify the storage class for the object. If you do not use this header, the object storage class is the default storage class of the bucket.

Type: string

Storage class options: STANDARD (Standard), WARM (Infrequent Access), COLD (Archive). These values are case sensitive.

Example: x-obs-storage-class: STANDARD

No

x-obs-meta-*

When creating an object, you can use a header starting with x-obs-meta- to define object metadata in an HTTP request. The user-defined metadata will be returned in the response when you retrieve the object or query the object metadata. For details, see User-Defined Object Metadata.

Type: string

Example: x-obs-meta-test: test metadata

Constraint: Both user-defined metadata keys and their values must conform to US-ASCII standards.

No

x-obs-website-redirect-location

If a bucket is configured with the static website hosting function, it will redirect requests for this object to another object in the same bucket or to an external URL. OBS stores the value of this header in the object metadata.

In the following example, the request header sets the redirection to an object (anotherPage.html) in the same bucket:

x-obs-website-redirect-location:/anotherPage.html

In the following example, the request header sets the object redirection to an external URL:

x-obs-website-redirect-location:http://www.example.com/

Type: string

Default value: none

Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 KB.

No

x-obs-server-side-encryption

Indicates that SSE-KMS is used.

Type: string

Example: x-obs-server-side-encryption: kms

No. This header is required when SSE-KMS is used.

x-obs-server-side-encryption-kms-key-id

Explanation:

The key used to encrypt objects. This header can be specified using either of the following formats:

1. regionID:domainID:key/key_id: regionID indicates the ID of the region where the key belongs. domainID indicates the ID of the tenant where the key belongs. key_id indicates the ID of the key created in KMS on the DEW console. An example is given as follows: x-obs-server-side-encryption-kms-key-id: region:exampledomainid: key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0.

2. key_id: It indicates the ID of the key created in KMS on the DEW console. An example is given as follows: x-obs-server-side-encryption-kms-key-id: 4f1cd4de-ab64-4807-920a-47fc42e7f0d0.

Restrictions:

This header can be used only when you set the x-obs-server-side-encryption header to kms.

Default value:

If you choose the KMS encryption but do not specify this header, the default master key will be used. If there is no such a default master key, OBS will create one and use it by default.

No

x-obs-server-side-encryption-customer-algorithm

Indicates the encryption algorithm when SSE-C is used.

Type: string

Example: x-obs-server-side-encryption-customer-algorithm: AES256

Constraint: This header must be used together with x-obs-server-side-encryption-customer-key and x-obs-server-side-encryption-customer-key-MD5.

No. This header is required when SSE-C is used.

x-obs-server-side-encryption-customer-key

Indicates the key for encrypting objects when SSE-C is used.

Type: string

Example: x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

Constraint: This header is a Base64-encoded 256-bit key and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key-MD5.

No. This header is required when SSE-C is used.

x-obs-server-side-encryption-customer-key-MD5

Indicates the MD5 value of the encryption key when SSE-C is used. The MD5 value is used to check whether any error occurs during the transmission of the key.

Type: string

Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

Constraint: This header is a Base64-encoded 128-bit MD5 value and must be used together with x-obs-server-side-encryption-customer-algorithm and x-obs-server-side-encryption-customer-key.

No. This header is required when SSE-C is used.

success-action-redirect

Indicates the address (URL) to which a successfully responded request is redirected.

  • If the value is valid and the request is successful, OBS returns status code 303. Location contains success_action_redirect as well as the bucket name, object name, and object ETag.
  • If this parameter value is invalid, OBS ignores this parameter. In such case, the Location header is the object address, and OBS returns the response code based on whether the operation succeeds or fails.

Type: string

No

x-obs-expires

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted. (The validity calculates from the object's creation time.)

You can configure this field when uploading an object or modify this field by using the metadata modification API after the object is uploaded.

Type: integer

Example: x-obs-expires:3

No

Request Elements

This request contains no elements. Its body contains only the content of the requested object.

Response Syntax

1
2
3
 
HTTP/1.1 status_code
Content-Length: length
Content-Type: type

Response Headers

The response to the request uses common headers. For details, see Table 1.

In addition to the common response headers, the headers listed in Table 2 may be used.

Table 2 Additional response headers

Header

Description

x-obs-version-id

Object version ID. If versioning is enabled for the bucket, the object version ID will be returned.

Type: string

x-obs-server-side-encryption

This header is included in a response if SSE-KMS is used.

Type: string

Example: x-obs-server-side-encryption:kms

x-obs-server-side-encryption-kms-key-id

Indicates the master key ID. This header is included in a response when SSE-KMS is used.

Type: string

Format: regionID:domainID:key/key_id

regionID indicates the ID of the region where the key belongs. domainID indicates the ID of the tenant where the key belongs. key_id indicates the key ID used in this encryption.

Example: x-obs-server-side-encryption-kms-key-id:region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-obs-server-side-encryption-customer-algorithm

Indicates the encryption algorithm. This header is included in a response when SSE-C is used.

Type: string

Example: x-obs-server-side-encryption-customer-algorithm: AES256

x-obs-server-side-encryption-customer-key-MD5

Indicates the MD5 value of the key for encrypting objects. This header is included in a response when SSE-C is used.

Type: string

Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

x-obs-storage-class

Type: string

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request: Uploading an Object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
PUT /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Date: WED, 01 Jul 2015 04:11:15 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw=
Content-Length: 10240
Expect: 100-continue

[1024 Byte data content]

Sample Response: Uploading an Object

1
2
3
4
5
6
7
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF2600000164364C10805D385E1E3C67
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-obs-id-2: 32AAAWJAMAABAAAQAAEAABAAAQAAEAABCTzu4Jp2lquWuXsjnLyPPiT3cfGhqPoY
Date: WED, 01 Jul 2015 04:11:15 GMT
Content-Length: 0

Sample Request: Uploading an Object (with the ACL Configured)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
PUT /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Date: WED, 01 Jul 2015 04:13:55 GMT
x-obs-grant-read:id=52f24s3593as5730ea4f722483579ai7,id=a93fcas852f24s3596ea8366794f7224
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:gYqplLq30dEX7GMi2qFWyjdFsyw=
Content-Length: 10240
Expect: 100-continue

[1024 Byte data content]

Sample Response: Uploading an Object (with the ACL Configured)

1
2
3
4
5
6
7
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BB7800000164845759E4F3B39ABEE55E
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSReVRNuas0knI+Y96iXrZA7BLUgj06Z
Date: WED, 01 Jul 2015 04:13:55 GMT
Content-Length: 0

Sample Request: Uploading an Object to a Versioned Bucket

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
PUT /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Date: WED, 01 Jul 2015 04:17:12 GMT
x-obs-storage-class: WARM
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:uFVJhp/dJqj/CJIVLrSZ0gpw3ng=
Content-Length: 10240
Expect: 100-continue

[1024 Byte data content]

Sample Response: Uploading an Object to a Versioned Bucket

1
2
3
4
5
6
7
8
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: DCD2FC9CAB78000001439A51DB2B2577
ETag: "d41d8cd98f00b204e9800998ecf8427e"
X-OBS-ID-2: GcVgfeOJHx8JZHTHrRqkPsbKdB583fYbr3RBbHT6mMrBstReVILBZbMAdLiBYy1l
Date: WED, 01 Jul 2015 04:17:12 GMT
x-obs-version-id: AAABQ4q2M9_c0vycq3gAAAAAVURTRkha
Content-Length: 0

Sample Request: Uploading an Object (with Its MD5 Specified)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
PUT /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Date: WED, 01 Jul 2015 04:17:50 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:uFVJhp/dJqj/CJIVLrSZ0gpw3ng=
Content-Length: 10
Content-MD5: 6Afx/PgtEy+bsBjKZzihnw==
Expect: 100-continue

1234567890

Sample Response: Uploading an Object (with Its MD5 Specified)

1
2
3
4
5
6
7
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BB7800000164B165971F91D82217D105
X-OBS-ID-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCSEKhBpS4BB3dSMNqMtuNxQDD9XvOw5h
ETag: "1072e1b96b47d7ec859710068aa70d57"
Date: WED, 01 Jul 2015 04:17:50 GMT
Content-Length: 0

Sample Request: Uploading an Object (with Website Hosting Configured)

If static website hosting has been configured for a bucket, you can configure parameters as follows when you upload an object. Then, users will be redirected when they download the object.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
PUT /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Date: WED, 01 Jul 2015 04:17:12 GMT
x-obs-website-redirect-location: http://www.example.com/
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:uFVJhp/dJqj/CJIVLrSZ0gpw3ng=
Content-Length: 10240
Expect: 100-continue

[1024 Byte data content]

Sample Response: Uploading an Object (with Website Hosting Configured)

1
2
3
4
5
6
7
8
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: DCD2FC9CAB78000001439A51DB2B2577
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTmxB5ufMj/7/GzP8TFwTbp33u0xhn2Z
ETag: "1072e1b96b47d7ec859710068aa70d57"
Date: WED, 01 Jul 2015 04:17:12 GMT
x-obs-version-id: AAABQ4q2M9_c0vycq3gAAAAAVURTRkha
Content-Length: 0

Sample Request: Uploading an Object Using a Signed URL

PUT /object02?AccessKeyId=H4IPJX0TQTHTHEBQQCEC&Expires=1532688887&Signature=EQmDuOhaLUrzrzRNZxwS72CXeXM%3D HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Content-Length: 1024

[1024 Byte data content]

Sample Response: Uploading an Object Using a Signed URL

1
2
3
4
5
6
7
8
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: DCD2FC9CAB78000001439A51DB2B2577
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTmxB5ufMj/7/GzP8TFwTbp33u0xhn2Z
ETag: "1072e1b96b47d7ec859710068aa70d57"
Date: Fri, 27 Jul 2018 10:52:31 GMT
x-obs-version-id: AAABQ4q2M9_c0vycq3gAAAAAVURTRkha
Content-Length: 0

Sample Request: Uploading an Object (with a Storage Class Specified)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
PUT /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.eu
Accept: */*
Date: WED, 01 Jul 2015 04:15:07 GMT
x-obs-storage-class: WARM
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:uFVJhp/dJqj/CJIVLrSZ0gpw3ng=
Content-Length: 10240
Expect: 100-continue

[1024 Byte data content]

Sample Response: Uploading an Object (with a Storage Class Specified)

1
2
3
4
5
6
7
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BB7800000164846A2112F98BF970AA7E
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-obs-id-2: a39E0UgAIAABAAAQAAEAABAAAQAAEAABCTPOUJu5XlNyU32fvKjM/92MQZK2gtoB
Date: WED, 01 Jul 2015 04:15:07 GMT
Content-Length: 0
Parent topic: Operations on Objects