All Products
Search

This Product

    Object Storage Service:head-object

    Document Center

    Object Storage Service:head-object

    Last Updated:Apr 11, 2025

    The head-object command is used to query the metadata of an object.

    Note

    • Content of the object is not returned in the response when you run this command.

    Permissions

    By default, an Alibaba Cloud account has full permissions on resources in the account. In contrast, RAM users and RAM roles associated with an Alibaba Cloud account initially have no permissions. To manage resources by using a RAM user or role, you must grant the required permissions via RAM policies or Bucket policies.

    API

    Action

    Description

    HeadObject

    oss:GetObject

    Queries the metadata of an object.

    Command syntax

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

    Parameter

    Type

    Description

    --bucket

    string

    Name of the bucket.

    --key

    string

    Full path of the Object.

    --if-match

    string

    If the ETag value that is specified in the request matches the ETag value of the object, 200 OK and the metadata of the object are returned. Otherwise, 412 precondition failed is returned.

    --if-modified-since

    string

    If the specified time is earlier than the last modified time of the object, the metadata of the object and 200 OK are returned. Otherwise, 304 Not Modified is returned.

    --if-none-match

    string

    If the input ETag does not match the ETag of the object, the metadata of the object and 200 OK are returned. Otherwise, 304 Not Modified is returned.

    --if-unmodified-since

    string

    If the specified time is equal to or later than the last modified time of the object, the metadata of the object and 200 OK are returned. Otherwise, 412 Precondition Failed is returned.

    --version-id

    string

    Version ID of the object.

    Note

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

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

    Examples

    • Query the metadata of exampleobject .

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

    • Query the metadata of exampleobject and display the output in the JSON format.

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

    • Query the metadata of exampleobject whose version ID is 123.

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

    • Query the metadata of exampleobject whose ETag value is 123.

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

    • Query the metadata of exampleobject of which the actual modification time is earlier than 'Thu, 11 Jul 2024 06:36:31 GMT'.

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