Query object metadata with the ossutil head-object command - Object Storage Service

Retrieves the metadata of an object without returning the object content.

Permissions

By default, an Alibaba Cloud account has full permissions on resources in the account. RAM users and RAM roles initially have no permissions. To grant access, attach a RAM policy or bucket policy that includes the following action.

API	Action	Description
HeadObject	`oss:GetObject`	Queries the metadata of an object

Command syntax

ossutil api head-object --bucket <value> --key <value> [flags]

Parameters

Required parameters

Parameter	Type	Description
`--bucket`	string	Name of the bucket
`--key`	string	Full path of the object

Conditional request parameters

Parameter	Type	Response behavior
`--if-match`	string	Returns 200 OK and metadata if the object's ETag matches the specified value. Otherwise returns 412 Precondition Failed.
`--if-none-match`	string	Returns 200 OK and metadata if the object's ETag does not match the specified value. Otherwise returns 304 Not Modified.
`--if-modified-since`	string	Returns 200 OK and metadata if the object was modified after the specified time (HTTP-date format, e.g., `Thu, 11 Jul 2024 06:36:31 GMT`). Otherwise returns 304 Not Modified.
`--if-unmodified-since`	string	Returns 200 OK and metadata if the object was last modified at or before the specified time (HTTP-date format). Otherwise returns 412 Precondition Failed.

Version parameter

Parameter	Type	Description
`--version-id`	string	Version ID of the object. Use this to retrieve metadata for a specific version.

Note

The head-object command maps to the HeadObject API operation. For supported global flags, see Command-line options.

Examples

Retrieve object metadata

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

Retrieve metadata in JSON format

ossutil api head-object --bucket examplebucket --key exampleobject --output-format json

Retrieve metadata for a specific version

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

Retrieve metadata only if the ETag matches

Returns 200 OK if the ETag matches; returns 412 Precondition Failed otherwise.

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

Retrieve metadata only if the object was modified after a given time

Returns 200 OK if the object was modified after the specified time; returns 304 Not Modified otherwise.

ossutil api head-object --bucket examplebucket --key exampleobject --if-modified-since "Thu, 11 Jul 2024 06:36:31 GMT"