Uploading Objects Through Forms

Description

The POST Object API is used to upload files (objects) to a specified bucket by using a form. This operation requires the requester to have the write permission on the bucket. All API parameters carried by HTTP headers are requested using form fields.

Notes

1. Write permissions for the bucket are required.
2. If the Object being added already exists with the same name, the newly uploaded file will overwrite the original file, and a successful response will return 200 OK.

Request

Request Example

POST / HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Content-Length: length
Headers
Form

Request Header

Common Headers

The implementation of this request operation uses common request headers. For details on common request headers, please refer to the Common Request Headers document.

Non-common Headers

The following table describes required request headers for this request operation.

Form Field

Signature Protection

When an HTTP POST request for form upload is initiated and signature protection is required, the form should include form-data in the following content structure:

Signature Calculation

The calculation of the signature q-signature is classified into three steps:

1. Use the key content to encrypt the value of q-key-time to obtain SignKey.
2. Create a POST request policy and encrypt the content using SHA1 to obtain StringToSign.
3. Use SignKey to encrypt StringToSign to generate the signature.

Policy

The following example is 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": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
    {"q-sign-time": "1480932292;1481012298" }
  ]
}

Expiration
Sets the timeout time of POST Policy, in ISO8601 GMT time, for example, 2017-12-01T12:00:00.000Z.

Conditions rules

Conditions parameters
All parameters are optional. If a parameter is not specified, it does not need to be verified.

Response

Response Headers

Common Response Headers

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

Response Parameters

Response Body

The response body is returned as application/xml data, and the content containing the complete node data is shown below.

<PostResponse>
        <Location>http://examplebucket-1250000000.<Endpoint>/photo.jpg</Location>
        <Bucket>examplebucket-1250000000</Bucket>
        <Key>photo.jpg</Key>
        <ETag>d41d8cd98f00b204e9800998ecf8427e</ETag>
</PostResponse>

The data are described as follows:

Content of the PostResponse node of the container type:

Error Code

The following table describes some special and common errors that may occur with this request. For details on error codes related to COS, see Error Codes.

Practical Case

Request

POST / HTTP/1.1
Connection: keep-alive
Accept-Encoding: gzip, deflate
Accept: */*
User-Agent: python-requests/2.12.4
Host: <BucketName-APPID>.<Endpoint>
Content-Length: 1352
Content-Type: multipart/form-data; boundary=e07f2a7876ae4755ae18d300807ad879

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

a/${filename}
--e07f2a7876ae4755ae18d300807ad879
Content-Disposition: form-data; name="Acl"

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

q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&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-[Region].myqcloud.com/photo.jpg
x-cos-request-id: NWEyZTRkMDZfMjQ4OGY3MGFfNTE4Yl81