POST Object

Description

A POST Object API request allows the users to upload a file (object) to the specified bucket through a form. This operation requires that you have WRITE permission to the bucket. All API parameters carried by the HTTP header are requested through form fields.

Version

If versioning is enabled for the bucket, the POST operation will automatically generate a unique version ID for the object to be uploaded. COS returns this ID in the response using the x-cos-version-id response header.
If you suspend versioning for the bucket, COS will always use "null" as the version ID of the object stored in the bucket.

Detail Analysis

1. You need to have write permission of the bucket.
2. If a file with the same name as the file to be uploaded already exists in the bucket, it will be overwritten and 200 OK will be returned upon success.

Request

Request Example

POST / HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Content-Length: length
Headers
Form

Request Headers

Common Headers

We implement this request with a common request header. For more information about common request headers, see Common Request Headers.

Special Request Headers

The following required headers are needed for this request operation:

Form Fields

Signature Protection

If signature protection is needed for an HTTP POST request as a form, the form should contain the content of the following form-data:

Signature Calculation

The signature "q-signature" can be calculated in three steps:

1. Use the key content to encrypt the time value of q-key-time and calculate the value of SignKey.
2. Create a POST request policy and encrypt its content with sha1 to get the StringToSign.
3. Encrypt the StringToSign with the SignKey to generate the signature.

Policy

Below is an example of a complete policy:

{ "expiration": "2007-12-01T12:00:00.000Z",
  "conditions": [
    {"acl": "public-read" },
    {"bucket": "examplebucket-1250000000" },
    ["starts-with", "$key", "user/eric/"],
    {"q-sign-algorithm": "sha1" },
    {"q-ak": "AKIDQjz3ltompVjBni5LitkWHFlFpwkn9U5q" },
    {"q-sign-time": "1480932292;1481012298" }
  ]
}

Expiration
This sets the expiration time for the POST policy in ISO8601 GMT time, such as 2017-12-01T12:00:00.000Z

Conditions Rules

Conditions Parameters
All parameters are optional. If they are not entered, the verification can be skipped.

Response

Response Headers

Common Response Headers

This response uses a common response header. For more information about common response headers, see Common Response Headers.

Special Response Headers

The request may return the following response headers:

Response Parameters

Response Body

application/xml data is returned in the response body, which contains the complete node data as shown below:

<PostResponse>
        <Location>http://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/photo.jpg</Location>
        <Bucket>examplebucket-1250000000</Bucket>
        <Key>photo.jpg</Key>
        <ETag>d41d8cd98f00b204e9800998ecf8427e</ETag>
</PostResponse>

The detailed data are described as follows:

Content of the Container node PostResponse:

Error Codes

Errors that are frequently seen with the request are listed below. For more common error codes in COS, see Error Codes.

Examples

Request

POST / HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.12.4
Host: examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
Content-Length: 1352
Content-Type: multipart/form-data; boundary=e07f2a7876ae4755ae18d300807ad879

--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="key"

photo.jpg
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="success_action_status"

201
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="Acl"

public-read
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="x-cos-storage-class"

STANDARD
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="Signature"

q-sign-algorithm=sha1&q-ak=AKIDZfbOAo7cllgPvF9cXFrJD0a1ICvR98JM&q-sign-time=1512983814;1512984814&q-key-time=1512983814;1512984814&q-url-param-list=&q-header-list=host&q-signature=2ffd2ae714e7445a8da000ec5d51771ff5056500
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="policy"

eyJjb25kaXRpb25zIjogW3siYnVja2V0IjogImtpdG1hbnMzdGVzdDEifSwgWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsIDAsIDEwMDAwMDAwXSwgWyJzdGFydHMtd2l0aCIsICJ4LWNvcy1tZXRhLWJiIiwgIjEyIl1dLCAiZXhwaXJhdGlvbiI6ICIyMDQ3LTEyLTAxVDEyOjAwOjAwLjAwMFoifQ==
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="x-Cos-meta-bb"

124
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="key1"

1
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="file"; filename="empty:a"


--e07f2a7876ae4755ae18d300807ad879--

Response

HTTP/1.1 204
Content-Type: application/xml
Content-Length: 232
Connection: keep-alive
Date: Mon, 11 Dec 2017 09:16:56 GMT
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Location: http://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/photo.jpg
Server: tencent-cos
x-cos-request-id: NWEyZTRkMDZfMjQ4OGY3MGFfNTE4Yl81