POST Object

Description

This API (POST Object) is used to upload a file (object) to the specified bucket through the use of 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 to 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 a success will be returned as if the upload succeeded.

Request

Sample Request

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

Request Header

Common Headers

The implementation of this request operation uses a common request header. For more information on common request headers, see Common Request Headers.

Non-common Headers

The following request headers are required for the implementation of 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 a sample 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 Header

Common Response Headers

This response uses a common response header. For more information on 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

Some frequent special errors that may occur with the request are listed below. For more common error codes in COS, see Error Codes.

Samples

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