POST Object

Uploading an object is to add an object into 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 name of each object in the same bucket must be unique.

If an object with the same object key as an original object in a bucket is uploaded to the bucket, the new object overwrites the original one. To prevent data corruption during transmission, 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.

Besides sending a PUT Object request to upload an object to the bucket, you can also send a POST Object request.

This operation supports server-side encryption.

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 PUT Bucket Versioning.

Request Syntax

POST / HTTP/1.1
Host: bucketname.obs.cn-north-1.myhwclouds.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 contains no parameter.

Request Headers

This request uses common headers. For details, see Table 1. If you want to obtain CORS configuration information, you must use the headers in Table 1.

Table 1 Request headers of CORS configuration

Header

Description

Required or Optional

Origin

Indicates an origin specified by a pre-request. Generally, it is a domain name.

Type: string

Required

Access-Control-Request-Headers

Indicates the HTTP headers of a request. The request can use multiple HTTP headers.

Type: string

Optional

Request Elements

This request uses form fields. Table 2 describes the form fields.

Table 2 Form fields

Field

Description

Required or Optional

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.

Required

key

Indicates the name of the object to be uploaded.

Type: string

Required

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 privatepublic-readpublic-read-writeauthenticated-readbucket-owner-read, and bucket-owner-full-control. For details, see Table 3.

Type: string

Example:

Policy: {"acl": "public-read" }

HTML: <input type="text" name="acl" value="public-read" />

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.

  • 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 the value is invalid, OBS ignores this field and returns status code 204. Location contains the object address.

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-*

Indicates user-defined metadata. When creating an object, you can use this header or a header starting with x-amz-meta- to define object metadata in an HTTP request. Self-defined metadata will be returned in the response header when you retrieve or query the metadata of the object.

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 200201, and 204.

  • If the value is set to 200 or 204, OBS returns an empty response body.
  • If the value is set to 201, OBS returns a response containing an XML file recording request details.
  • If the value is not set or is invalid, OBS returns status code 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 KB.

Optional

x-amz-server-side-encryption

Indicates that SSE-KMS is used.

Type: string

Example: x-amz-server-side-encryption:aws:kms

Optional. This header is required when SSE-KMS is 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

Optional

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.

Optional. This header is required when SSE-C is 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 key and must be used together with x-amz-server-side-encryption-customer-algorithm and x-amz-server-side-encryption-customer-key-MD5.

Optional. This header is required when SSE-C is 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.

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

Response Syntax

HTTP/1.1 status_code
Content-Type: application/xml
Location: location
Date: date
ETag: etag

Response Headers

This response uses common headers. For details, see Common Response Headers.

This response also uses additional headers, as described in Table 3.

Table 3 Additional response headers

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: GETPUTHEADPOST, 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 contains no element.

Error Responses

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

Registration