POST Object

Last updated:2021-04-07 21:40:26

Description

You can call this operation to add an object to a specified space by using an HTML form. This operation is an alternative of the PUT operation, allowing you to upload objects to user spaces by using a browser. Parameters are encoded and encapsulated into the message body as form fields and passed through POST. To call this operation, you must have the write permissions on the bucket.

Kingsoft Cloud Standard Storage Service (KS3) adds only complete objects. If you receive a success response, KS3 has added the entire object to the bucket.

KS3 is a distributed system. When KS3 receives multiple write requests for the same object, it writes the object in an overwrite way and keeps only the latest object. KS3 does not provide object locking when you write an object to the bucket. You can build this function into your application layer as required.

Request

Request syntax

POST / HTTP/1.1
Host: {BucketName}.{endpoint}
User-Agent: {browser_data}
Accept: {file_types}
Accept-Language: {Regions}
Accept-Charset: {character_set}
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: {length}

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

{ObjectKey}
--9431149156168
Content-Disposition: form-data; name="KSSAccessKeyId"

{AccessKey}
--9431149156168
Content-Disposition: form-data; name="Policy"

{Policy}
--9431149156168
Content-Disposition: form-data; name="Signature"

{Signature}
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to KS3
--9431149156168--

Request parameters

No request parameter is used.

Request headers

This operation involves only common request headers. For more information, see Common request headers.

Form fields

Name Description Required
acl The access control list (ACL). If the ACL is invalid, an error will be returned.
Type: String
Default value: private
Valid values: private and public-read
No
Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires REST special headers. For more information, see PUT Object.
Type: String
Default value: None
No
file The file or file content. You can upload only one file at a time. The file content must be placed after the key field; otherwise, an 400 error will be returned.
Type: File or file content
Default value: None
Yes
key The object key. You can use the ${filename} variable to specify the file name as the key. For example, to upload the local.jpg file, you need to specify specify /user/betty/${filename}, and the key is /user/betty/local.jpg.
Type: String
Default value: None
Yes
KSSAccessKeyId The KSS access key.
Type: String
Default value: None
Constraint: This field is required when the bucket field is not public-read-write or when the policy field is specified.
Required in specific conditions
policy The security policy for defining allowed actions. A request without this field is treated as an anonymous request and has access only to common writable spaces.
Type: String
Default value: None
Constraint: This field is required when the value of the bucket field is not public-read-write. For more information, see [Post Policy]
Required in specific conditions
signature The signature calculated based on the access key and policy. KS3 verifies this field to determine whether the request is valid.
Type: String
Default value: None
Constraint: This field is required when the value of the bucket field is not public-read-write or when the policy field is specified. For more information, see [Post Policy]
Required in specific conditions
success_action_redirect, redirect The URL to which the client will be redirected after the uploading succeeds. If success_action_redirect is not specified, KS3 will return an empty file. If KS3 cannot parse the URL, it will ignore this field. If the uploading fails, KS3 will not redirect the client.
Type: String
Default value: None
No
success_action_status The response status code. If this field is not specified, the response status code depends on the uploading status.
Default value: 204
Valid values: 200, 201, and 204. If the value is 200 or 204, KS3 will return an empty file with the HTTP status code 200 or 204. If the value is 201, KS3 will return an XML file with the HTTP status code 201. If the value is invalid or no value is specified, KS3 will return an empty file with the HTTP status code 204.
Type: String
Default value: None
No
x-kss-meta- The prefix of user-defined metadata. A header starting with x-kss-meta- is user-defined metadata.
Type: String
Default value: None
Constraint: None
No
x-kss-storage-class The file storage type.
Type: String
Default value: None
Valid values: STANDARD, STANDARD_IA, and ARCHIVE
Note: When x-kss-storage-class is not specified, archival storage will be used for the object if the storage type of the bucket is ARCHIVE, and standard storage will be used for the object if the storage type of the bucket is not ARCHIVE. When x-kss-storageClass is specified, the specified type of storage will be used for the object.
Constraint: None
No
x-kss-newfilename-in-body Specifies whether to show the file name in the response. The file name is configured in the console. For more information, see Setting a file name. A value of true indicates that the file name is displayed in the response header and response body. A value of false indicates that the file name is displayed only in the response header.
Type: Boolean
Default value: None
Valid values: false
true
Constraint: None
tagging The tag to be added to the object.
Default value: None
No
The following entries are required in a KS3 encryption request.

The following entries are required for enabling default encryption.

Name Description Required
x-kss-server-side-encryption The encryption that specifies the used encryption algorithm. This entry is required if KS3 has encrypted the object. Currently, only AES256 is supported.
Type: String
Yes

The following headers are required for specifying a user-defined key for encryption.

Header Description Required
x-kss-server-side-encryption-customer-key The base64-encoded encryption key for KS3.
Type: String
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-algorithm and x-kss-server-side-encryption-customer-key-MD5.
Yes
x-kss-server-side-encryption-customer-algorithm The user-defined encryption algorithms. If the server-side encryption uses a user-defined encryption key, the response will include this header to check the decryption algorithms to use when decrypting the object.
Type: String
Valid value: AES256
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-key and x-kss-server-side-encryption-customer-key-MD5.
Yes
x-kss-server-side-encryption-customer-key-MD5 The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key.
Type: String
Constraint: This header must be used together with valid x-kss-server-side-encryption-customer-key and x-kss-server-side-encryption-customer-algorithm.
Yes

Response

Response headers

This operation supports all common response headers. For more information, see Common response headers.

Header Description
success_action_redirect, redirect The URL to which the client will be redirected after the uploading succeeds.
Type: String
Parent node: PostResponse
x-kss-server-side-encryption-customer-algorithm The user-defined encryption algorithms. If the server-side encryption uses a user-defined encryption key, the response will include this header to check the decryption algorithms to use when decrypting the object.
Type: String
Valid value: AES256
x-kss-server-side-encryption-customer-key-MD5 The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key.
Type: String
newfilename The new file name configured in the console. For more information, see Setting a file name.
Type: String

Operation-specific errors

This operation does not return operation-specific errors.

Usage notes

  • You must have the write permissions on the bucket.
  • The KSSAccessKeyId, policy, and signature fields are required unless an anonymous user has the write permissions on the bucket. For more information, see Post Policy
  • When you call this operation, make sure that Content-Type is multipart/form-data.
  • The policy specifies rules for uploading a form. The form must meet all the rules. The policy must contain all form entries other than KSSAccessKeyId, policy, signature, and file.
  • You must have the ks3:PutObjectTagging permission to tag the object during the uploading. If you have the ks3:PutObject permission but not the ks3:PutObjectTagging permission, you can call this operation to upload an object without tags.
  • You can add entries starting with x-kss-meta to add user-defined metadata. These entries must be defined in the policy.
  • If KS3 returns a 403 error, check whether the form meets the policy.

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

  • Insufficient
  • Outdated
  • Unclear or awkward
  • Redundant or clumsy
  • Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈