Use the get-object command to query an object - Object Storage Service

Download an object from an OSS bucket.

Description

The get-object command downloads an object from a bucket. It maps directly to the GetObject REST API.

Use conditional headers (--if-match, --if-none-match, --if-modified-since, --if-unmodified-since) to download an object only when specific conditions are met. Use --range to download a byte range instead of the full object.

Before downloading an object in the Archive storage class, submit a RestoreObject request and wait for it to complete. Attempting to download an unrestored Archive object returns an error.

Usage notes

The GetObject API supports both HTTP and HTTPS by default. To restrict access to HTTPS only, configure a bucket policy. For more information, see Authorize user access to specific resources through bucket policies.
For supported global command-line options, see Global command-line options.

Required permissions

Alibaba Cloud accounts have full permissions by default. RAM users and RAM roles have no permissions by default. An administrator must grant permissions through a RAM policy or bucket policy.

Action	When required
`oss:GetObject`	Always
`oss:GetObjectVersion`	When using `--version-id`
`kms:Decrypt`	When the object metadata contains `X-Oss-Server-Side-Encryption: KMS`

Syntax

ossutil api get-object --bucket <bucket-name> --key <object-key> [flags]

Required parameters

Parameter	Type	Description
`--bucket`	string	Name of the bucket that contains the object.
`--key`	string	Full path of the object to download.

Optional parameters

Parameter	Type	Description
`--accept-encoding`	string	Encoding type the client accepts. For example, set to `gzip` to request compressed transfer.
`--if-match`	string	ETag value to match. Returns `200 OK` if the object ETag matches; returns `412 Precondition Failed` otherwise.
`--if-modified-since`	string	Timestamp in HTTP date format. Returns `200 OK` if the object was modified after the specified time; returns `304 Not Modified` otherwise.
`--if-none-match`	string	ETag value to exclude. Returns `200 OK` if the object ETag does not match; returns `304 Not Modified` otherwise.
`--if-unmodified-since`	string	Timestamp in HTTP date format. Returns `200 OK` if the object was not modified after the specified time; returns `412 Precondition Failed` otherwise.
`--range`	stringArray	Byte range to download. Format: `bytes=<start>-<end>`.
`--response-cache-control`	string	Override the `Cache-Control` header in the response.
`--response-content-disposition`	string	Override the `Content-Disposition` header in the response.
`--response-content-encoding`	string	Override the `Content-Encoding` header in the response.
`--response-content-language`	string	Override the `Content-Language` header in the response.
`--response-expires`	string	Override the `Expires` header in the response.
`--version-id`	string	Version ID of the object to download. Required when downloading a specific version from a versioning-enabled bucket.

Examples

Download an object

ossutil api get-object --bucket examplebucket --key exampleobject

Download a specific object version

Download the version with ID 123 from a versioning-enabled bucket.

ossutil api get-object --bucket examplebucket --key exampleobject --version-id 123

Download a byte range

Download only bytes 1 through 10.

ossutil api get-object --bucket examplebucket --key exampleobject --range bytes=1-10

Conditional download based on modification time

Download only if the object was modified after the specified timestamp. If unchanged, OSS returns 304 Not Modified.

ossutil api get-object --bucket examplebucket --key exampleobject --if-modified-since "Mon, 11 May 2020 08:16:23 GMT"

Conditional download based on ETag

Download only if the object ETag matches the specified value. If the ETag does not match, OSS returns 412 Precondition Failed.

ossutil api get-object --bucket examplebucket --key exampleobject --if-match 123

Download with gzip compression

Request gzip-compressed transfer to reduce bandwidth usage.

ossutil api get-object --bucket examplebucket --key exampleobject --accept-encoding gzip

Related API

This command calls the GetObject REST API. To build custom integrations, call the REST API directly. Direct API calls require manual signature calculation.