金山云-文档中心-POST Object

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

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.

On this page

Previous:PUT Object

Next:GET Object ACL

Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen