put-object - Object Storage Service - Alibaba Cloud Documentation Center

Upload a single object (up to 5 GB) to an Object Storage Service (OSS) bucket. This command gives you direct control over upload headers, metadata, tags, and encryption settings. For objects larger than 5 GB or recursive directory uploads, use <code data-tag="code" class="inline-code___exakR" id="code_c454ecd2">ossutil cp</code>.

Quick start

Upload a local file to a bucket:

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

Replace examplebucket with your bucket name, exampleobject with the destination key, and uploadFile with the path to your local file. Make sure ossutil is configured with credentials for the correct OSS region before running this command.

Prerequisites

Before you begin, make sure you have:

An OSS bucket
The oss:PutObject permission granted through a RAM policy or bucket policy
(Optional) The oss:PutObjectTagging permission, if setting object tags
(Optional) The kms:GenerateDataKey and kms:Decrypt permissions, if using Key Management Service (KMS) encryption

Synopsis

ossutil api put-object --bucket <value> --key <value> [--body <value>]
  [--cache-control <value>] [--content-disposition <value>]
  [--content-encoding <value>] [--content-type <value>]
  [--expires <value>] [--forbid-overwrite <value>]
  [--metadata <value>] [--object-acl <value>]
  [--server-side-encryption <value>] [--server-side-data-encryption <value>]
  [--server-side-encryption-key-id <value>]
  [--storage-class <value>] [--tagging <value>]

Usage notes

The maximum object size is 5 GB. For larger objects, use multipart upload or ossutil cp.
Uploading an object with the same key as an existing object overwrites it by default. To prevent this, set --forbid-overwrite true.
If bucket versioning is enabled, uploading an object with the same key creates a new version rather than overwriting the previous one. The response includes VersionId. The --forbid-overwrite flag has no effect when versioning is enabled.
OSS does not auto-detect MIME type from the file extension. Set --content-type explicitly for objects served to browsers (for example, image/jpeg or application/pdf).

Warning

When using --body to upload a file, always include the file:// prefix (for example, file://report.pdf). Without the prefix, ossutil uploads the literal string -- not the file contents -- which can cause silent data loss.

Parameters

Required parameters

Parameter	Type	Description
`--bucket`	string	The name of the target bucket.
`--key`	string	The object key, including any prefix path (for example, `project/report.pdf`).

Content parameters

These parameters control what is uploaded and how OSS stores and serves the object.

Parameter	Type	Description
`--body`	string	The content to upload. Use `file://path` for local files or pass a literal string without the prefix. For example, `file://report.pdf` uploads the file, while `"hi oss"` uploads the string directly.
`--content-type`	string	The MIME type of the object (for example, `image/jpeg` or `application/pdf`). OSS does not auto-detect the content type from the file extension.
`--content-encoding`	string	The content encoding of the object body (for example, `gzip`).
`--content-disposition`	string	The `Content-Disposition` response header value. Use this to suggest a filename when the object is downloaded (for example, `attachment;filename=report.pdf`).
`--cache-control`	string	The `Cache-Control` header value (for example, `no-cache` or `max-age=3600`).
`--expires`	string	The HTTP `Expires` response header value. Tells caches and browsers when the content should be considered stale. This does not delete the object.

Access control and storage parameters

These parameters control who can access the object and how OSS stores it.

Parameter	Type	Description
`--object-acl`	string	The access control list (ACL) for the object. Valid values: `default`, `private`, `public-read`, `public-read-write`.
`--storage-class`	string	The storage class of the object. Valid values: `Standard`, `IA` (Infrequent Access), `Archive`, `ColdArchive`, `DeepColdArchive`.
`--forbid-overwrite`	boolean	Only uploads if no object with the same key exists. Default: `false`. Has no effect when bucket versioning is enabled.

Encryption parameters

These parameters enable server-side encryption for the object at rest.

Parameter	Type	Description
`--server-side-encryption`	string	The server-side encryption method. Valid values: `AES256`, `KMS`. When set to `KMS`, the `kms:GenerateDataKey` and `kms:Decrypt` permissions are required.
`--server-side-data-encryption`	string	The data encryption algorithm. Valid value: `SM4`. Only applies when `--server-side-encryption` is set to `KMS`.
`--server-side-encryption-key-id`	string	The ID of the customer master key (CMK) managed by KMS. If not specified, OSS uses the default KMS key.

Metadata and tagging parameters

These parameters attach custom metadata and tags to the object at upload time.

Parameter	Type	Description
`--metadata`	stringArray	A user-defined metadata key-value pair. Keys must use the `x-oss-meta-` prefix (for example, `x-oss-meta-department=engineering`). Keys are stored and returned in lowercase. Specify this flag multiple times for multiple pairs.
`--tagging`	string	Object tags in URL query string format (for example, `TagA=A&TagB=B`). Requires the `oss:PutObjectTagging` permission.

For global options that apply to all ossutil commands, see Global command-line options.

Examples

All examples use Unix shell quoting. Adapt quoting rules for your platform (for example, PowerShell on Windows).

Upload a file from the local filesystem using the file:// prefix.

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

Upload a short string directly as the object body.

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

Attach custom key-value metadata to the object. Specify --metadata multiple times for multiple pairs.

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

Tag the object using URL query string format. Multiple tags are separated by &.

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

Upload with a private ACL and Infrequent Access (IA) storage class to reduce cost for less-frequently accessed objects.

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

Enable KMS server-side encryption with the SM4 data algorithm and a specific customer master key (CMK).

    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****

Reject the upload if an object with the same key already exists.

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

Set the Cache-Control header to prevent downstream caches from serving a stale copy.

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

Use Content-Disposition to suggest a filename when a browser downloads the object.

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

Upload a PDF file with department metadata, environment tags, and a private ACL in a single command.

    ossutil api put-object --bucket examplebucket --key project/report.pdf \
      --body file://report.pdf \
      --metadata department=engineering \
      --tagging "env=prod&team=backend" \
      --object-acl private

Output

On success, ossutil api put-object returns a JSON response. The following table describes the common fields:

Field	Description
`ETag`	The entity tag of the uploaded object. Use this value to verify upload integrity.
`VersionId`	The version ID of the object. Only returned when versioning is enabled on the bucket.
`ServerSideEncryption`	The encryption method applied to the object. Only returned when server-side encryption is used.
`ServerSideEncryptionKeyId`	The ID of the KMS key used. Only returned when KMS encryption is used.

For the full response schema, see the PutObject API reference.

Required permissions

An Alibaba Cloud account has full permissions by default. Resource Access Management (RAM) users and RAM roles have no permissions by default. Grant permissions through a RAM policy or bucket policy.

For a basic upload without tags or KMS encryption, oss:PutObject is the only required permission.

Action	When required
`oss:PutObject`	Required for all uploads.
`oss:PutObjectTagging`	Required when using the `--tagging` flag to set object tags.
`kms:GenerateDataKey`	Required when using `--server-side-encryption KMS`.
`kms:Decrypt`	Required when using `--server-side-encryption KMS`.

What's next

<code data-tag="code" class="inline-code___exakR" id="code_f03a3293">ossutil cp</code> -- High-level command for uploads with automatic multipart support and recursive directory uploads
PutObject -- REST API reference for the underlying PutObject operation
Global command-line options -- Flags shared across all ossutil commands