All Products
Search

This Product

    :put-object

    Document Center

    :put-object

    Last Updated:Sep 25, 2024

    Uploads an object to a bucket.

    Usage notes

    • By default, an Alibaba Cloud account has the permissions to upload an object to a bucket. To upload an object to a bucket by using a RAM user or Security Token Service (STS), you must have the oss:PutObject permission. For more information, see Attach a custom policy to a RAM user.

    • You cannot run this command to upload an object that is larger than 5 GB in size.

    • By default, if an object that has the same name already exists in the bucket and you have the permissions to access the existing object, the object that you want to upload overwrites the existing object.

    Command syntax

    ossutil api put-object --bucket value --key value [flags]

    Parameter

    Type

    Description

    --body

    string

    The request body.

    --bucket

    string

    The name of the bucket.

    --cache-control

    string

    The web page caching behavior of the object.

    --content-disposition

    string

    The name of the object.

    --content-encoding

    string

    The method that is used to encode the object.

    --expires

    string

    The time when the request expires.

    --forbid-overwrite

    boolean

    Specifies whether the object that is uploaded by running the put-object command overwrites an existing object that has the same name.

    --key

    string

    The full path of the object.

    --metadata

    stringArray

    The metadata of the object. To specify custom metadata, you must specify parameters prefixed with x-oss-meta-*.

    --object-acl

    string

    The access control list (ACL) of the object.

    --server-side-data-encryption

    string

    The server-side encryption method of the bucket.

    --server-side-encryption

    string

    The method that is used to encrypt the object that you want to upload.

    --server-side-encryption-key-id

    string

    The ID of the customer master key (CMK) that is managed by Key Management Service (KMS).

    --storage-class

    string

    The storage class of the object.

    --tagging

    string

    The tag you want to specify for the object by using a key-value pair. You can specify multiple tags for an object. Example: TagA=A&TagB=B.

    Note

    • The put-object command corresponds to the PutObject operation. For more information about the parameters in the PutObject operation, see PutObject.

    • For more information about supported global command-line options, see Global command-line options.

    Examples

    • Upload an object by uploading a string. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss"

    • Upload an object by uploading a local file. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body file://uploadFile

    • Upload an object by uploading a string and specify the metadata of the object. 

      ossutil api put-object --bucket examplebucket --key exampleobject  --metadata user=aliyun --metadata email=ali***@aliyuncs.com --body "hi oss"

    • Upload an object by uploading a string and specify tags for the object. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --tagging "TagA=A&TagB=B"

    • Upload an object by uploading a string and specify the ACL and storage class of the object. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --object-acl private --storage-class IA

    • Upload an object by uploading a string and specify the method that is used to encrypt the object. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --server-side-encryption KMS --server-side-data-encryption SM4 --server-side-encryption-key-id 9468da86-3509-4f8d-a61e-6eab1eac****

    • Upload an object by uploading a string and prevent the object that you want to upload from overwriting existing objects that have the same name. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --forbid-overwrite true

    • Upload an object by uploading a string and specify the caching behavior of the web page when the object is downloaded. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --cache-control no-cache

    • Upload an object by uploading a string and specify the name of the object when the object is downloaded. 

      ossutil api put-object --bucket examplebucket --key exampleobject --body "hi oss" --content-disposition "attachment;filename=oss_download.jpg"