Uploading Objects - POST
Functions
This operation uploads an object to a bucket. To use this operation, you must have the write permission on 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 parameter in the form field. After receiving the request, OBS will perform an MD5 consistency check. If the two MD5 values are inconsistent, the system returns an error message. You can also specify the value of the x-obs-acl parameter to configure an access control policy for the object.
You can also upload an object using the POST method.
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.
This operation supports server-side encryption.
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. The request lines of the two methods are as follows:
PUT /ObjectName HTTP/1.1
POST / HTTP/1.1
For details about PUT upload, see Uploading Objects - PUT.
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 a bucket, the version ID of the requested object in this bucket is null. For details about the versioning statuses of a bucket, see Configuring Versioning for a Bucket.
WORM
If a bucket has WORM enabled, you can configure retention policies for objects in the bucket. You can specify the x-obs-object-lock-mode and x-obs-object-lock-retain-until-date headers to configure a retention policy when you upload an object. If you do not specify these two headers but have configured a default bucket-level WORM policy, this default policy automatically applies to the object newly uploaded. You can also configure or update a WORM retention policy for an existing object.
When you enable WORM for a bucket, OBS automatically enables versioning for the bucket. WORM protects objects based on the object version IDs. Only object versions with any WORM retention policy configured can be protected. Assume that object test.txt 001 is protected by WORM. If another file with the same name is uploaded, a new object version test.txt 002 with no WORM policy configured will be generated. In such case, test.txt 002 is not protected and can be deleted. When you download an object without specifying a version ID, the current object version (test.txt 002) will be downloaded.
Request Syntax
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
POST / HTTP/1.1 Host: bucketname.obs.region.myhuaweicloud.com User-Agent: browser_data Accept: file_types Accept-Language: Regions Accept-Encoding: encoding Accept-Charset: character_set Keep-Alive: 300 Connection: keep-alive Content-Type: multipart/form-data; boundary=9431149156168 Content-Length: length --9431149156168 Content-Disposition: form-data; name="key" acl --9431149156168 Content-Disposition: form-data; name="success_action_redirect" success_redirect --9431149156168 Content-Disposition: form-data; name="content-Type" content_type --9431149156168 Content-Disposition: form-data; name="x-obs-meta-uuid" uuid --9431149156168 Content-Disposition: form-data; name="x-obs-meta-tag" metadata --9431149156168 Content-Disposition: form-data; name="AccessKeyId" access-key-id --9431149156168 Content-Disposition: form-data; name="policy" encoded_policy --9431149156168 Content-Disposition: form-data; name="signature" signature= --9431149156168 Content-Disposition: form-data; name="file"; filename="MyFilename" Content-Type: image/jpeg file_content --9431149156168 Content-Disposition: form-data; name="submit" Upload to OBS --9431149156168-- |
Request Parameters
This request contains no parameters.
Request Headers
This request uses common headers. For details, see Table 3.
If you want to get CORS configuration information, you must use the headers in Table 1.
Header |
Description |
Mandatory |
|---|---|---|
Origin |
Origin of the cross-domain request specified by the pre-request. Generally, it is a domain name. Type: string |
Yes |
Access-Control-Request-Headers |
Indicates the HTTP headers of a request. The request can use multiple HTTP headers. Type: string |
No |
If an error message is still displayed after CORS has been configured, rectify the fault by referring to Why Is an Error Reported Even If CORS Has Been Configured?
Request Elements
This request uses form elements. Table 2 describes the form elements.
Parameter |
Description |
Mandatory |
|---|---|---|
file |
Indicates the content of the object to be uploaded. Type: binary content or text Constraint: This parameter must be the last parameter in a form. Otherwise, parameters after this parameter will be all discarded. Additionally, each request contains only one file parameter. |
Yes |
key |
Indicates the name of the object to be created. Type: string |
Yes |
AccessKeyId |
Access key ID (AK) of the requester. Type: string Constraint: This parameter is mandatory if there is security policy parameter policy or signature in the request. |
Yes when the constraint is met. |
policy |
Indicates the security policy in the request. For details about the policy format, see the policy format in Authentication of Signature Carried in the Table Uploaded Through a Browser. Type: string Constraint: This parameter is mandatory if the bucket provides the AccessKeyId (or signature). |
Yes when the constraint is met. |
signature |
Indicates a signature string calculated based on StringToSign. Type: string Constraint: This parameter is mandatory if the bucket provides the AccessKeyId (or policy). |
Yes when the constraint is met. |
token |
Specifies the AK, signature, and security policy of the request initiator. The priority of a token is higher than that of a specified AK, the request signature, and the security policy of the request initiator. Type: string Example: In HTML: <input type= "text" name="token" value="ak:signature:policy" /> |
No |
x-obs-acl |
When creating a bucket, you can add this header to set the permission control policy for the bucket. The predefined common policies are as follows: private, public-read, public-read-write, public-read-delivered, and public-read-write-delivered (for details about the policies, see the ACL configuration using header fields in ACLs). Type: string An example is provided as follows: In POLICY: {"acl": "public-read" } In HTML: <input type="text" name="acl" value="public-read" /> |
No |
x-obs-grant-read |
When creating an object, you can use this header to authorize all users in an account the permission to read objects and obtain object metadata. Type: string An example is provided as follows: In POLICY: {'grant-read': 'id=domainId1' }, In HTML: <input type="text" name="grant-read" value="id=domainId1" /> |
No |
x-obs-grant-read-acp |
When creating an object, you can use this header to authorize all users in an account the permission to obtain the object ACL. Type: string An example is provided as follows: In POLICY: {"grant-read-acp": "id=domainId1" }, In HTML: <input type="text" name="grant-read-acp" value="id=domainId1" /> |
No |
x-obs-grant-write-acp |
When creating an object, you can use this header to authorize all users in an account the permission to write the object ACL. Type: string An example is provided as follows: In POLICY: {"grant-write-acp": "id=domainId1" }, In HTML: <input type="text" name="grant-write-acp" value="id=domainId1" /> |
No |
x-obs-grant-full-control |
When creating an object, you can use this header to authorize all users in an account the permission to read the object, obtain the object metadata, obtain the object ACL, and write the object ACL. Type: string An example is provided as follows: In POLICY: {"grant-full-control": "id=domainId1" }, In HTML: <input type="text" name="grant-full-control" value="id=domainId1" /> |
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 value options: STANDARD (Standard), WARM (Infrequent Access), COLD (Archive) These values are case sensitive. An example is provided as follows: In POLICY: {"storage-class": "STANDARD" }, In HTML: <input type="text" name="x-obs-storage-class" value="STANDARD" /> |
No |
Cache-Control, Content-Type, Content-Disposition, Content-Encoding Expires |
Standard HTTP headers. OBS records those headers. If you download the object or send the HEAD Object request, those parameter values are returned. Type: string An example is provided as follows: In POLICY: ["starts-with", "$Content-Type", "text/"], In HTML: <input type="text" name="content-type" value="text/plain" /> |
No |
success_action_redirect |
Indicates the address (URL) to which a successfully responded request is redirected.
Type: string An example is provided as follows: In POLICY: {"success_action_redirect": "http://123458.com"}, In HTML: <input type="text" name="success_action_redirect" value="http://123458.com" /> |
No |
x-obs-meta-* |
Indicates user-defined metadata. When creating an object, you can use this header or a header starting with x-obs-meta- to define object metadata in an HTTP request. Custom metadata will be returned in the response header when you retrieve or query the metadata of the object. For details, see User-Defined Object Metadata. Type: string An example is provided as follows: In POLICY: {" x-obs-meta-test ": " test metadata " }, In HTML: <input type="text" name=" x-obs-meta-test " value=" test metadata " /> |
No |
x-obs-persistent-headers |
When creating an object, you can add the x-obs-persistent-headers header in an HTTP request to specify one or more user-defined response headers. User-defined response headers will be returned in the response header when you retrieve the object or query the object metadata. Type: string Format: x-obs-persistent-headers: key1:base64_encode(value1),key2:base64_encode(value2)... Note: Items, such as key1 and key2, are user-defined headers. If they contain non-ASCII or unrecognizable characters, they can be encoded using URL or Base64. The server processes these headers as character strings, but does not decode them. Items, such as value1 and value2 are the values of the corresponding headers. base64_encode indicates that the value is encoded using Base64. A user-defined header and its Base64-encoded value are connected using a colon (:) to form a key-value pair. All key-value pairs are separated with a comma (,) and are placed in the x-obs-persistent-headers header. The server then decodes the uploaded value. Examples: In POLICY: {"x-obs-persistent-headers": "key1:dmFsdWUx,key2:dmFsdWUy" }, In HTML: <input type="text" name="x-obs-persistent-headers" value="key1:dmFsdWUx,key2:dmFsdWUy" /> The returned header for downloading the object or obtaining the object metadata is key1:value1 or key2:value2 respectively. Constraints: 1. Response headers customized in this way cannot be prefixed with x-obs-. For example, you should use key1, instead of x-obs-key1. 2. Standard HTTP headers, such as host, content-md5, origin, range, and Content-Disposition, cannot be specified as custom headers. 3. The total length of this header and the custom metadata cannot exceed 8 KB. 4. If the same keys are transferred, values are separated with commas (,) and then returned in one key. 5. If the decoded value contains non-US-ASCII or unrecognizable characters, the server processes the value as a string and encapsulates it using ?UTF-8?B?<(str)>?=, but does not decode the value. For instance, value key1:abbc will be returned as key1: =?UTF-8?B?abbc?=. |
No |
success_action_status |
Indicates the status code returned after the request is successfully received. Possible values are 200, 201, and 204.
Type: string An example is provided as follows: In POLICY: ["starts-with", "$success_action_status", ""], In HTML: <input type="text" name="success_action_status" value="200" /> |
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. 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 |
Master key ID. This header is used in SSE-KMS mode. If the customer does not provide the master key ID, the default master key ID will be used. Type: string The following two formats are supported: 1. regionID:domainID:key/key_id 2. key_id regionID is the ID of the region to which the key belongs. domainID is the account ID of the tenant to which the key belongs. key_id is the key ID created in DEW. Example: 1. x-obs-server-side-encryption-kms-key-id: region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 2. x-obs-server-side-encryption-kms-key-id:4f1cd4de-ab64-4807-920a-47fc42e7f0d0 |
No |
x-obs-server-side-encryption-customer-algorithm |
Encryption algorithm. The header is used in SSE-C mode. 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 |
A key used to encrypt objects. The header is used in SSE-C mode. This key is used to encrypt objects. 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 a key used to encrypt objects. The header is used in SSE-C mode. 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. |
x-obs-expires |
Indicates the expiration time of an object, in days. An object will be automatically deleted once it expires (calculated from the last modification time of the object). Type: integer Example: x-obs-expires:3 |
No |
x-obs-object-lock-mode |
WORM mode that will be applied to the object. Currently, only COMPLIANCE is supported. This header must be used together with x-obs-object-lock-retain-until-date. Type: string Example: x-obs-object-lock-mode:COMPLIANCE |
No |
x-obs-object-lock-retain-until-date |
When the Object Lock retention will expire. The value must be a UTC time that complies with ISO 8601, for example, 2015-07-01T04:11:15Z. This header must be used together with x-obs-object-lock-mode. Type: string Example: x-obs-object-lock-retain-until-date:2015-07-01T04:11:15Z |
No, but required when the x-obs-object-lock-mode header is carried. |
Response Syntax
1 2 3 4 5 |
HTTP/1.1 status_code Content-Type: application/xml Location: location Date: date ETag: etag |
Response Headers
The response to the request uses common headers. For details, see Table 1.
In addition to the common response headers, the following message headers may also be used. For details, see Table 3.
Header |
Description |
|---|---|
x-obs-version-id |
Object version ID. If versioning is enabled for the bucket, the object version ID will be returned. A string null will be returned if the bucket housing the object has versioning suspended. Type: string |
Access-Control-Allow-Origin |
Indicates that the origin is included in the response if the origin in the request meets the CORS configuration requirements when CORS is configured for buckets. Type: string |
Access-Control-Allow-Headers |
Indicates that the headers are included in the response if headers in the request meet the CORS configuration requirements when CORS is configured for buckets. Type: string |
Access-Control-Max-Age |
Indicates MaxAgeSeconds in the CORS configuration of the server when CORS is configured for buckets. Type: integer |
Access-Control-Allow-Methods |
Indicates that methods in the rule are included in the response if Access-Control-Request-Method in the request meets the CORS configuration requirements when CORS is configured for buckets. Type: string Possible values are GET, PUT, HEAD, POST, and DELETE. |
Access-Control-Expose-Headers |
Value of ExposeHeader in the CORS configuration of a server when CORS is configured for buckets. 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 if SSE-KMS is used. Type: string Format: regionID:domainID:key/key_id regionID is the ID of the region to which the key belongs. domainID is the account ID of the tenant to which the key belongs. key_id is 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 an encryption algorithm. This header is included in a response if 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 a key used to encrypt objects. This header is included in a response if SSE-C is used. Type: string Example: x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== |
Response Elements
This response involves no elements.
Error Responses
No special error responses are returned. For details about error responses, see Table 2.
Sample Request 1
Common POST upload
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
POST / HTTP/1.1 Date: WED, 01 Jul 2015 04:15:23 GMT Host: examplebucket.obs.region.myhuaweicloud.com Content-Type: multipart/form-data; boundary=7db143f50da2 Content-Length: 2424 Origin: www.example.com Access-Control-Request-Headers:acc_header_1 --7db143f50da2 Content-Disposition: form-data; name="key" object01 --7db143f50da2 Content-Disposition: form-data; name="acl" public-read --7db143f50da2 Content-Disposition: form-data; name="content-type" text/plain --7db143f50da2 Content-Disposition: form-data; name="expires" WED, 01 Jul 2015 04:16:15 GMT --7db143f50da2 Content-Disposition: form-data; name="AccessKeyId" 14RZT432N80TGDF2Y2G2 --7db143f50da2 Content-Disposition: form-data; name="policy" ew0KICAiZXhaaXJhdGlvbiI6ICIyMDE1LTA3LTAxVDEyOjAwOjAwLjAwMFoiLA0KICAiY29uZGl0aW9ucyI6IFsNCiAgICB7ImJ1Y2tldCI6ICJleG1hcGxlYnVja2V0IiB9LA0KICAgIHsiYWNsIjogInB1YmxpYy1yZWFkIiB9LA0KICAgIHsiRXhaaXJlcyI6ICIxMDAwIiB9LA0KICAgIFsiZXEiLCAiJGtleSIsICJvYmplY3QwMSJdLA0KICAgIFsic3RhcnRzLXdpdGgiLCAiJENvbnRlbnQtVHlwZSIsICJ0ZXh0LyJdLA0KICBdDQp9DQo= --7db143f50da2 Content-Disposition: form-data; name="signature" Vk6rwO0Nq09BLhvNSIYwSJTRQ+k= --7db143f50da2 Content-Disposition: form-data; name="file"; filename="C:\Testtools\UpLoadFiles\object\1024Bytes.txt" Content-Type: text/plain 01234567890 --7db143f50da2 Content-Disposition: form-data; name="submit" Upload --7db143f50da2-- |
Sample Response 1
After CORS is configured for a bucket, the response contains the Access-Control-* information.
1 2 3 4 5 6 7 8 9 10 11 12 |
HTTP/1.1 204 No Content x-obs-request-id: 90E2BA00C26C00000133B442A90063FD x-obs-id-2: OTBFMkJBMDBDMjZDMDAwMDAxMzNCNDQyQTkwMDYzRkRBQUFBQUFBQWJiYmJiYmJi Access-Control-Allow-Origin: www.example.com Access-Control-Allow-Methods: POST,GET,HEAD,PUT Access-Control-Allow-Headers: acc_header_01 Access-Control-Max-Age: 100 Access-Control-Expose-Headers: exp_header_01 Content-Type: text/xml Location: http://examplebucket.obs.region.myhuaweicloud.com/object01 Date: WED, 01 Jul 2015 04:15:23 GMT ETag: "ab7abb0da4bca5323ab6119bb5dcd296" |
Sample Request 2
Upload an object with the x-obs-acl, storage class, and redirection header fields carried in the request message.
Before encoding, the policy content is as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
{
"expiration":"2018-07-17T04:54:35Z",
"conditions":[
{
"content-type":"text/plain"
},
{
"x-obs-storage-class":"WARM"
},
{
"success_action_redirect":"http://www.example.com"
},
{
"x-obs-acl":"public-read"
},
[
"starts-with",
"$bucket",
""
],
[
"starts-with",
"$key",
""
]
]
}
|
Sample request:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
POST / HTTP/1.1 Host: examplebucket.obs.region.myhuaweicloud.com Accept-Encoding: identity Content-Length: 947 Content-Type: multipart/form-data; boundary=9431149156168 User-Agent: OBS/Test --9431149156168 Content-Disposition: form-data; name="x-obs-acl" public-read --9431149156168 Content-Disposition: form-data; name="AccessKeyId" H4IPJX0TQTHTHEBQQCEC --9431149156168 Content-Disposition: form-data; name="key" my-obs-object-key-demo --9431149156168 Content-Disposition: form-data; name="signature" WNwv8P1ZiWdqPQqjXeLmAfzPDAI= --9431149156168 Content-Disposition: form-data; name="policy" eyJleHBpcmF0aW9uIjoiMjAxOC0wNy0xN1QwODozNDoyM1oiLCAiY29uZGl0aW9ucyI6W3siY29udGVudC10eXBlIjoidGV4dC9wbGFpbiJ9LHsieC1vYnMtYWNsIjoicHVibGljLXJlYWQifSxbInN0YXJ0cy13aXRoIiwgIiRidWNrZXQiLCAiIl0sWyJzdGFydHMtd2l0aCIsICIka2V5IiwgIiJdXX0= --9431149156168 Content-Disposition: form-data; name="content-type" text/plain --9431149156168 Content-Disposition: form-data; name="file"; filename="myfile" Content-Type: text/plain c2c6cd0f-898e-11e8-aab6-e567c91fb541 52b8e8a0-8481-4696-96f3-910635215a78 --9431149156168-- |
Sample Response 2
1 2 3 4 5 6 7 |
HTTP/1.1 204 No Content Server: OBS Location: http://examplebucket.obs.region.myhuaweicloud.com/my-obs-object-key-demo ETag: "17a83fc8d431273405bd266114b7e034" x-obs-request-id: 5DEB00000164A728A7C7F4E032214CFA x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCSwj2PcBE0YcoLHUDO7GSj+rVByzjflA Date: Tue, 17 Jul 2018 07:33:36 GMT |
Sample Request 3
Use a token for authentication.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
POST / HTTP/1.1 Content-Type:multipart/form-data; boundary=9431149156168 Content-Length: 634 Host: examplebucket.obs.region.myhuaweicloud.com --9431149156168 Content-Disposition: form-data; name="key" obj01 --9431149156168 Content-Disposition: form-data; name="token" UDSIAMSTUBTEST002538:XsVcTzR2/A284oE4VH9qPndGcuE=:eyJjb25kaXRpb25zIjogW3siYnVja2V0IjogInRlc3QzMDAzMDU4NzE2NjI2ODkzNjcuMTIifSwgeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24veG1sIn0sIFsiZXEiLCAiJGtleSIsICJvYmoudHh0Il1dLCAiZXhwaXJhdGlvbiI6ICIyMDIyLTA5LTA5VDEyOjA5OjI3WiJ9 --9431149156168 Content-Disposition: form-data; name="file"; filename="myfile" Content-Type: text/plain 01234567890 --9431149156168-- Content-Disposition: form-data; name="submit" Upload to OBS |
Sample Response 3
The response to the authentication using a token
1 2 3 4 5 6 7 |
HTTP/1.1 204 No Content Server: OBS Location: http://examplebucket.obs.region.myhuaweicloud.com/my-obs-object-key-demo ETag: "7eda50a430fed940023acb9c4c6a2fff" x-obs-request-id: 000001832010443D80F30B649B969C47 x-obs-id-2: 32AAAUgAIAABAAAQAAEAABAAAQAAEAABCTj0yO9KJd5In+i9pzTgCDVG9vMnk7O/ Date: Fri,09Sep 2022 02: 24:40 GMT |
Feedback
Was this page helpful?
Provide feedbackFor any further questions, feel free to contact us through the chatbot.
Chatbot
