POST Object

Last updated: 2021-01-21 10:05:41

    Feature Description

    This API is used to upload a local object of less than 5 GB in size to a specified bucket through an HTML form. To make this request, you need to have the permission to write to the bucket.

    Note:

    • This API has special requirements for signatures instead of using standard COS request signatures. For more information, please see Signature protection and description of related fields.
    • If versioning is not enabled and you try to upload an object whose name already exists, the newly uploaded object will overwrite the prior one and a response will be returned in the specified way upon success.

    Versioning

    • If versioning is enabled for the bucket, COS will automatically generate a unique version ID for the object to be uploaded. It returns this ID in the response by using the x-cos-version-id response header.
    • If versioning is suspended for the bucket, COS will always use null as the version ID of the object in the bucket and will not return the x-cos-version-id response header.

    Request

    Sample request

    POST / HTTP/1.1
    Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
    Date: GMT Date
    Content-Type: multipart/form-data; boundary=Multipart Boundary
    Content-Length: Content Length
    
    [Multipart Form Data]

    Request form

    The request body of this API is encoded with multipart/form-data. When sending requests in HTML with the <form> element, you need to configure the enctype attribute of the <form> element as multipart/form-data, and then use HTML form elements (such as <input> and <select>) to add required form fields.

    Form fields

    Name Description Type Required
    key Object key. If you specify the ${filename} wildcard in the object key, the wildcard in the object key will be replaced with the actual filename. For more information, please see Sample 7 string Yes
    Cache-Control Cache directives as defined in RFC 2616, which will be stored in the object metadata string No
    Content-Disposition Filename as defined in RFC 2616, which will be stored in the object metadata string No
    Content-Encoding Encoding format as defined in RFC 2616, which will be stored in the object metadata string No
    Content-Type HTTP content type (MIME) as defined in RFC 2616, which will be stored in the object metadata
    Note: when files are uploaded through forms, the browser will automatically carry the MIME type of the specified file in the request. However, COS will not use the MIME type carried by the browser, so you need to explicitly specify the Content-Type field as the object content type
    string No
    Expires The cache expiration time as defined in RFC 2616, which will be saved in the object metadata string No
    success_action_redirect Destination address for URL redirect upon a successful upload. If this field is not set, HTTP status code 303 (Redirect) and the Location response header will be returned. The Location response header will include the URL address specified by this field together with the bucket, key, and etag parameters. For more information, please see Sample 8 string No
    success_action_status HTTP status code returned upon a successful upload. Valid values: 200, 201, 204; default value: 204. If success_action_redirect is specified, this field will be ignored. For more information, please see Sample 9 number No
    x-cos-meta-* Contains user-defined metadata and header suffixes, which will be stored in the object metadata. Maximum size: 2 KB.
    Note: user-defined metadata can contain underscores (_), while the header suffixes of user-defined metadata can only contain minus signs (-) but not underscores
    string No
    x-cos-storage-class Object storage class, such as INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE. Default value: STANDARD. For enumerated values, please see Storage Class Enum No
    x-cos-traffic-limit Specifies the traffic limit in bit/s on this upload. Value range: 819200-838860800, that is, 100 KB/s-100 MB/s. if this range is exceeded, a 400 error will be returned integer No
    Content-MD5 MD5 hash value of the Base64-encoded file content used for integrity check, i.e., checking whether the file content has changed during the upload string No
    file Information and content of the file. When the file is uploaded through the web form, the browser will automatically set the value of this field to the correct format.
    Note: the file field must be placed at the end of the entire form.
    file Yes

    ACL-related form fields

    You can configure access permissions for the object by specifying the following form fields during upload:

    Name Description Type Required
    x-cos-acl Defines the access control list (ACL) attribute of the object. For enumerated values such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default
    Note: If you don't need access control for the object, set the field to default or simply leave it empty, and the object will inherit the permissions of the bucket
    Enum No
    x-cos-grant-read Grants a user read permission for an object in the format of id="[OwnerUin]", such as id="100000000001". You can use commas (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-read-acp Grants a user read permission for the ACL of an object in the format of id="[OwnerUin]", such as id="100000000001". You can use commas (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-write-acp Grants a user write permission for the ACL of an object in the format of id="[OwnerUin]", such as id="100000000001". You can use commas (,) to separate multiple users, such as id="100000000001",id="100000000002" string No
    x-cos-grant-full-control Grants a user full permission to operate on an object in the format of id="[OwnerUin]", such as id="100000000001". You can use commas (,) to separate multiple users, such as id="100000000001",id="100000000002" string No

    Form fields related to server-side encryption

    You can use server-side encryption by specifying the following form fields when uploading the object:

    Name Description Type Required
    x-cos-server-side-encryption Server-side encrypt algorithm. Valid values: AES256, cos/kms string Yes if SSE-COS or SSE-KMS is used
    x-cos-server-side-encryption-customer-algorithm Server-side encryption algorithm. AES256 is supported string Yes if SSE-C is used
    x-cos-server-side-encryption-cos-kms-key-id When the value of x-cos-server-side-encryption is cos/kms, this field is used to specify the CMK of KMS. If it is not specified, the CMK created by COS will be used by default. For more information, please see SSE-KMS Encryption string No
    x-cos-server-side-encryption-context When the value of x-cos-server-side-encryption is cos/kms, this field is used to specify the encryption context, and its value is a Base64-encoded string of the key-value pair for the encryption context in JSON format,
    such as eyJhIjoiYXNkZmEiLCJiIjoiMTIzMzIxIn0=
    string No
    x-cos-server-side-encryption-customer-key Base64-encoded server-side encryption key,
    such as MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
    string Yes if SSE-C is used
    x-cos-server-side-encryption-customer-key-MD5 Base64-encoded MD5 hash value of the server-side encryption key,
    such as U5L61r7jcwdNvT7frmUG8g==
    string Yes if SSE-C is used

    Signature protection

    The POST Object API requires signature-related fields to be carried in the request. After receiving the message, the COS server will perform authentication. If the authentication is successful, the request will be accepted and executed; otherwise, an error message will be returned, and the request will be discarded.

    The signature is generated as follows:

    1. Prepare

    Log in to the CAM Console and get your project's SecretId and SecretKey on the API Key Management page.

    2. Generate KeyTime

    a. Get the Unix timestamp StartTimestamp corresponding to the current time, which is the total seconds from January 1, 1970, 00:00:00 UTC (January 1, 1970, 08:00:00 Beijing time) to now.
    b. Calculate the Unix timestamp EndTimestamp for the moment the signature will expire based on the timestamp above and the expected valid duration of the signature.
    c. Get the signature validity period (i.e., KeyTime) by splicing the two timestamps above in the format of StartTimestamp;EndTimestamp.

    3. Create a policy

    A policy is a piece of JSON text. A typical policy is as follows:

    {
        "expiration": "2019-08-30T09:38:12.414Z",
        "conditions": [
            { "acl": "default" },
            { "bucket": "examplebucket-1250000000" },
            [ "starts-with", "$key", "folder/subfolder/" ],
            [ "starts-with", "$Content-Type", "image/" ],
            [ "starts-with", "$success_action_redirect", "https://my.website/" ],
            [ "eq", "$x-cos-server-side-encryption", "AES256" ],
            { "q-sign-algorithm": "sha1" },
            { "q-ak": "AKIDQjz3ltompVjBni5LitkWHFlFpwkn9U5q" },
            { "q-sign-time": "1567150692;1567157892" }
        ]
    }

    Here:

    • expiration: expiration time of the policy, which is a string in ISO8601 format
    • conditions: an array of specific conditions for the policy. The specific rules for the conditions are listed below.