POST Object¶
You can use this operation to upload an object to an existing bucket.
Uploading an object indicates that an object is added to a bucket. This operation requires the write permission.
Note
The objects that are uploaded by users are stored in buckets. Only the users who have the write permission can upload objects to buckets. The names of objects in the same bucket must be unique.
If objects whose object keys are the same exist in a specified bucket, the new objects that are uploaded by a user will overwrite the original objects. To prevent data from being damaged during the transfer process, users can add Content-MD5 to request headers. After OBS receives the objects that are uploaded, it executes MD5 verification and will return an error if inconsistency is detected.
Users can specify the x-amz-acl parameter and set a permission control policy when uploading objects.
After creating a bucket in OBS, you can send a PUT Object request to upload an object to the bucket.
This operation makes server-side encryption available.
Versioning¶
If a bucket has versioning enabled, the system automatically generates a unique version ID for the requested object in this bucket and returns the version ID in response header x-amz-version-id. If a bucket has versioning suspended, the version ID of the requested object in this bucket is null. For details about bucket versioning, see section PUT Bucket versioning.
WORM¶
If a bucket has WORM enabled, you can configure retention policies for objects in the bucket. You can specify the x-amz-object-lock-mode and x-amz-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, see section Configuring WORM Retention for an Object.
Note
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 will 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¶
POST / HTTP/1.1
Host: bucketname.obs.example.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-amz-meta-uuid"
uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"
metadata
--9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"
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 involves no parameters.
Request Headers¶
This request uses common headers. For details about common request headers, see section Common Request Headers. If you want to obtain CORS configuration information, you must use the headers in Table 1.
Header | Description | Remarks |
|---|---|---|
Origin | Indicates an origin specified by a pre-request. Generally, it is a domain name. Type: String | Mandatory |
Access-Control-Request-Headers | Indicates the HTTP headers of a request. The request can use multiple HTTP headers. Type: String | Optional |
x-amz-security-token | Header field used to identify the request of a federated user. When the federal authentication function is enabled, users sending such requests are identified as federated users. Type: string | Optional. This parameter must be carried in the request sent by federated users. |
Request Elements¶
This request uses form fields. Table 2 describes the form fields.
Form Field | Description | Remarks |
|---|---|---|
file | Indicates the content of the object to be uploaded. Type: Binary or text content Constraints: This field must be the last one in a form. Each request can contain only one file field. All excessive file fields are discarded. | Mandatory |
key | Indicates the name of the object to be uploaded. Type: String | Mandatory |
AWSAccessKeyId | Indicates the AK of the requester. Type: String Constraints: Required if the policy field is included in the request. | Optional |
policy | Indicates the security policy of the request. Type: String | Optional |
expires | Indicates the date and time at which an object is no longer cacheable. The time is expressed in milliseconds in RFC 2616 format. If this field is specified, it will be returned in response headers after you send a GET Object or HEAD Object request. Type: String Example: Policy: {" expires ": "1000" } HTML: <input type="text" name=" expires " value="1000" /> | Optional |
x-amz-acl | Indicates the ACL applied to the object to be uploaded. Possible values are private, public-read, public-read-write, authenticated-read, bucket-owner-read, and bucket-owner-full-control. For details, see Table 4. Type: String Example: Policy: {"acl": "public-read" } HTML:<input type="text" name="acl" value="public-read" /> | Optional |
x-amz-storage-class | When creating an object, you can add this header in the request to set the storage class of the object. If you do not add this header, the object will use the default storage class of the bucket. Type: String Note: The storage class can be STANDARD (OBS Standard), STANDARD_IA (OBS Warm), or GLACIER (OBS Cold). Note that the three storage class values are case-sensitive. Example: x-amz-storage-class: STANDARD | Optional |
Cache-Control, Content-Type, Content-Disposition, Content-Encoding | Indicate standard HTTP headers. If these fields are specified, they are returned in response headers after you send a GET Object or HEAD Object request. Type: String Example: Policy: ["starts-with", "$Content-Type", "text/"] HTML: <input type="text" name="content-type" value="text/plain" /> | Optional |
success_action_redirect | Indicates the URL to which the client is redirected after the request is successfully responded to.
Type: String Example: Policy: {"success_action_redirect": "http://123458.com"} HTML: <input type="text" name="success_action_redirect" value="http://123458.com" /> | Optional |
x-amz-meta-* | This prefix is used to construct a field in a POST request for returning self-defined metadata. If this prefix is specified, user-defined metadata is returned in one or more response headers prefixed with x-amz-meta-. Note: The format of the user-defined metadata header is x-amz-meta-key:value. The total size of the key and value of all user-defined metadata in the request cannot exceed 2 KB. Type: String Example: Policy: {" x-amz-meta-test ": " test metadata " } HTML: <input type="text" name=" x-amz-meta-test " value=" test metadata " /> | Optional |
success_action_status | Indicates the status code returned after a POST Object request is successfully received. Possible values are 200, 201, and 204.
Type: String Example: Policy: ["starts-with", "$success_action_status", ""] HTML: <input type="text" name="success_action_status" value="200" /> | Optional |
x-amz-website-redirect-location | If a bucket is configured as a website, redirects 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: None Constraint: The value must be prefixed by a slash (/), http://, or https://. The length of the value cannot exceed 2 K. | Optional |
x-amz-server-side-encryption | Indicates that SSE-KMS is used. Type: string Example: x-amz-server-side-encryption:aws:kms | No. This header is mandatory when KMS-managed keys are used. |
x-amz-server-side-encryption-aws-kms-key-id | Indicates the master key ID. This header is used in SSE-KMS mode. If the customer does not provide the master key, the default master key will be used. Type: string Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 | No |
x-amz-server-side-encryption-customer-algorithm | Indicates an encryption algorithm. The header is used in SSE-C mode. Type: string Example: x-amz-server-side-encryption-customer-algorithm:AES256 Constraints: This header must be used together with x-amz-server-side-encryption-customer-key and x-amz-server-side-encryption-customer-key-MD5. | No. This header is mandatory when customer-provided keys are used. |
x-amz-server-side-encryption-customer-key | Indicates a key used to encrypt objects. The header is used in SSE-C mode. Type: string Example: x-amz-server-side-encryption-customer-key:K7QkYpBkM5+hcs27fsNkUnNVaobncnLht/rCB2o/9Cw= Constraints: This header is a base64-encoded 256-bit or 512-bit key and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5. | No. This header is mandatory when customer-provided keys are used. |
x-amz-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-amz-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ== Constraints: This header is a base64-encoded 128-bit MD5 value and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key. | No. This header is mandatory when customer-provided keys are used. |
x-amz-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-amz-object-lock-retain-until-date. Type: string Example: x-amz-object-lock-mode:COMPLIANCE | No, but required when x-amz-object-lock-retain-until-date is present. |
x-amz-object-lock-retain-until-date | Indicates the expiration time of the Object Lock retention. 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-amz-object-lock-mode. Type: string Example: x-amz-object-lock-retain-until-date:2015-07-01T04:11:15Z | No, but required when x-amz-object-lock-mode is present. |
Response Syntax¶
HTTP/1.1 status_code
Server: Server Name
x-amz-request-id: request id
x-amz-id-2: id
x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
Content-Type: type
Location: location
Date: date
ETag: etag
Response Headers¶
This response uses common headers. For details about common response headers, see section Common Response Headers. This response also uses one optional header, as described in Table 3.
Header | Description |
|---|---|
x-amz-version-id | Indicates the version ID of an object. The version ID of an object will be returned if the bucket housing the object has versioning enabled. A string "null" will be returned if the bucket housing the object has versioning suspended. Type: String |
Access-Control-Allow-Origin | CORS is configured for buckets. If Origin in the request meets the CORS configuration requirements, Origin is included in the response. Type: String |
Access-Control-Allow-Headers | CORS is configured for buckets. If headers in the request meet the CORS configuration requirements, headers are included in the response. Type: String |
Access-Control-Max-Age | Indicates MaxAgeSeconds in the CORS configuration of a server when CORS is configured for buckets. Type: Integer |
Access-Control-Allow-Methods | CORS is configured for buckets. If Access-Control-Request-Method in the request meets the CORS configuration requirements, methods in the rule are included in the response. Type: String Valid values: GET, PUT, HEAD, POST, and DELETE |
Access-Control-Expose-Headers | Indicates ExposeHeader in the CORS configuration of a server when CORS is configured for buckets. Type: String |
x-amz-server-side-encryption | This header is included in a response if SSE-KMS is used. Type: string Example: x-amz-server-side-encryption:aws:kms |
x-amz-server-side-encryption-aws-kms-key-id | Indicates the master key ID. This header is included in a response if SSE-KMS is used. Example: x-amz-server-side-encryption-aws-kms-key-id:arn:aws:kms:sichuan:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0 |
x-amz-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-amz-server-side-encryption-customer-algorithm:AES256 |
x-amz-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-amz-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 1.
Sample Request¶
POST / HTTP/1.1
Date: Fri, 18 Nov 2011 01:19:49 GMT
Host: bucketname.obs.example.com
Content-Type: multipart/form-data; boundary=---------------------------7db143f50da2
Content-Length: 2424
-----------------------------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"
1000
-----------------------------7db143f50da2
Content-Disposition: form-data; name="AWSAccessKeyId"
14RZT432N80TGDF2Y2G2
-----------------------------7db143f50da2
Content-Disposition: form-data; name="policy"
ewogICJleHBpcmF0aW9uIjogIjIwMTItMDEtMDFUMTI6MDA6MDAuMDAwWiIsCiAgImNvbmRpdGlvbnMiOiBbCiAgICB7ImJ1Y2tldCI6ICJ0Yy5wb3N0LmV4cGlyZXMuMDAxIiB9LAogICAgeyJhY2wiOiAicHVibGljLXJlYWQiIH0sCiAgICB7IkV4cGlyZXMiOiAiMTAwMCIgfSwKICAgIFsiZXEiLCAiJGtleSIsICJvYmplY3QwMSJdLAogICAgWyJzdGFydHMtd2l0aCIsICIkQ29udGVudC1UeXBlIiwgInRleHQvIl0sCiAgXQp9Cg==
-----------------------------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 for Uploading Objects to a Bucket with No Versioning Configured¶
HTTP/1.1 204 No Content
Server: OBS
x-amz-request-id: 90E2BA00C26C00000133B442A90063FD
x-amz-id-2: OTBFMkJBMDBDMjZDMDAwMDAxMzNCNDQyQTkwMDYzRkRBQUFBQUFBQWJiYmJiYmJi
x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
Content-Type: text/xml
Location: http://obs.example.com/tc.post.expires.001/object01
Date: Fri, 18 Nov 2011 01:20:27 GMT
ETag: "ab7abb0da4bca5323ab6119bb5dcd296"
Sample Response for Uploading Objects to a Bucket with Versioning Enabled¶
HTTP/1.1 204 No Content
Server: OBS
x-amz-request-id: DCD2FC9CAB780000014394C8D18D7A7F
x-amz-id-2: ebDwZjh64WVojaUVqPaWaXPqqfqLcp15DNr1KkAkP9EXyWrLsrqQoUs1Xn49VC9h
x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
Content-Type: text/xml
Location: http://192.168.69.11/example/testfile.txt
ETag: "098f6bcd4621d373cade4e832627b4f6"
x-amz-version-id: AAABQ5TI0anc0vycq3gAAAAyVURTRkha
Date: Wed, 15 Jan 2014 07:23:45 GMT
Sample Response for Uploading Objects to a Bucket with Versioning Suspended¶
HTTP/1.1 204 No Content
Server: OBS
x-amz-request-id: DCD2FC9CAB780000014394F041CA8F94
x-amz-id-2: 8EUVTpv5QBvTslQVlaDrzEauRpDP9fusd4IiJrgjExdPlyz+xleFMCNZD/zK0aZg
x-reserved: amazon, aws and amazon web services are trademarks or registered trademarks of Amazon Technologies, Inc
Content-Type: text/xml
Location: http://192.168.69.11/example/testfile.txt
ETag: "cc03e747a6afbbcbf8be7668acfebee5"
x-amz-version-id: null
Date: Wed, 15 Jan 2014 08:06:50 GMT
Sample Request for Configuring a WORM Retention Policy When Uploading an Object¶
POST /srcbucket HTTP/1.1
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Postman-Token: 4c2f4c7e-2e0b-46c0-b1a7-4a5da560b6a1
Host: obs.example.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Type: multipart/form-data; boundary=--------------------------940435396775653808840608
Content-Length: 1409
----------------------------940435396775653808840608
Content-Disposition: form-data; name="key"
obj
----------------------------940435396775653808840608
Content-Disposition: form-data; name="AwsAccessKeyId"
XXXXXXXXXXXXXXX000003
----------------------------940435396775653808840608
Content-Disposition: form-data; name="signature"
X/7QiyMYUvxUWk0R5fToeTcgMMU=
----------------------------940435396775653808840608
Content-Disposition: form-data; name="policy"
eyJleHBpcmF0aW9uIjoiMjAyMy0wNi0xNVQxNDoyMjo1MVoiLCAiY29uZGl0aW9ucyI6W3sieC1vYnMtb2JqZWN0LWxvY2stcmV0YWluLXVudGlsLWRhdGUiOiJUaHUsIDIwIEp1biAyMDIzIDEzOjEyOjUxIEdNVCJ9LHsieC1vYnMtb2JqZWN0LWxvY2stbW9kZSI6IkNPTVBMSUFOQ0UifSx7ImJ1Y2tldCI6InNyY2J1Y2tldDIifSx7ImNvbnRlbnQtdHlwZSI6InRleHQvcGxhaW4ifSx7ImtleSI6IjMzMyJ9LF19
----------------------------940435396775653808840608
Content-Disposition: form-data; name="x-amz-object-lock-mode"
COMPLIANCE
----------------------------940435396775653808840608
Content-Disposition: form-data; name="x-amz-object-lock-retain-until-date"
Thu, 20 Jun 2023 13:12:51 GMT
----------------------------940435396775653808840608
Content-Disposition: form-data; name="file"; filename="test.txt"
Content-Type: text/plain
----------------------------940435396775653808840608
Content-Disposition: form-data; name="submit"
Upload to OBS
----------------------------940435396775653808840608--
Sample Response for Configuring a WORM Retention Policy When Uploading an Object¶
HTTP/1.1 204 No Content
Server: OBS
Date: Thu, 15 Jun 2023 13:24:03 GMT
Connection: keep-alive
Location: http://obs.example.com/srcbucket/obj
ETag: "d41d8cd98f00b204e9800998ecf8427e"
x-amz-request-id: 00000188BF3A36EE5306427D000FEE0A
x-amz-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCS/5pj0p0hAQcDVI3B6E5y167zy4eAQv
x-forward-status: 0x40020000000001
x-dae-api-type: REST.POST.OBJECT