POST Object

Description

This API is used to upload a file (object) to a specified bucket using forms. To make this request, you need to have the permission to write to the bucket. All the API parameters carried by HTTP headers are requested using 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 will return 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 objects in the bucket.

Notes

1. You need to have the permission to write to the bucket.
2. If there is an object in the bucket with the same name as the object to be uploaded, the old object will be overwritten by the new one and the request will return success upon a successful upload.

Request

Sample Request

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

Request Headers

Common Headers

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

Special Headers

The following request headers are required for the implementation of this operation:

Form Fields

Signature Protection

If signature protection is needed for a POST request to upload an object using forms, the forms must contain the content of the following form-data:

Signature Calculation

The signature q-signature is calculated in three steps:

1. Use the key content to encrypt q-key-time to get SignKey.
2. Create a POST request policy and encrypt its content with sha1 to get StringToSign.
3. Encrypt StringToSign with 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
Sets the expiration time of 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 left empty, the verification can be skipped.

Response

Response Headers

Common Response Headers

This response uses common response headers. For more information on common response headers, see Common Response Headers.

Special Response Headers

This request may return the following response headers:

Response Parameters

Response Body

This response body returns application/xml data. The following contains all the node data:

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

Below are the details:

Content of the Container node PostResponse:

Error Codes

The following describes some frequent special errors that may occur when you make this request. For more COS error codes, see Error Codes.

Example

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