Updating Object Metadata

Updating Custom Metadata for Objects

Custom metadata are arbitrary key-value pairs. You may define and update any custom or arbitrary metadata that you need.

Any user with the Service Administrator role or a role that is specified in the X-Container-Write ACL of the container can perform this task.

The service transforms custom metadata keys as follows:

  • Underscores are converted to hyphens.
  • The first character after a hyphen is capitalized. All other letters are converted to lowercase.
  • The Java library automatically prefixes each key with X-Object-Meta-Custom.
You can update custom metadata for objects by using the following interfaces:
Interface Resources

RESTful API

See Create or Update Object Metadata in REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic.

Java Library

See updateObjectMetadata in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic.

File Transfer Manager API

See class: ObjectMetadata in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.

File Transfer Manager CLI

See Setting Object Metadata in Command-Line Reference for Oracle Cloud Infrastructure Object Storage Classic.

You can also delete custom metadata for objects by sending a POST request. See Deleting Object Metadata.

cURL Command Syntax

curl -v -X POST \
     -H "X-Auth-Token: token" \
     -H "X-Object-Meta-Name-1: value-1" \
     -H "X-Object-Meta-Name-2: value-2" \
     accountURL/containerName/objectName
  • token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
  • Name and value are the metadata header and value to be updated.

    You can specify multiple metadata headers and values that you would like to add or update.

    Note:

    Ensure that the custom metadata name and value comply with the input restrictions mentioned in Character Restrictions.
  • For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
  • containerName is the name of the container that contains the object for which custom metadata should be updated.
  • objectName is the name of the object for which custom metadata should be updated.

Note:

When you send a REST API request to Oracle Cloud Infrastructure Object Storage Classic, all non-ASCII characters in container names, object names and metadata values must be URL-encoded. For example, my container should be encoded as my%20container, where %20 is the HTML encoding for the space character. Similarly, my Über Container should be encoded as my%20%C3%9Cber%20Container, where %20 represents the space character and %C3%9C is the Ü character.

HTTP Response Codes

cURL Command Examples

Sample Cloud account with the following details:
  • Account name: acme
  • REST Endpoint URL: https://acme.storage.oraclecloud.com/v1/Storage-acme
  • REST Endpoint (Permanent) URL: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365

    Note:

    The REST Endpoint (Permanent) URL is displayed for the accounts created after November 2017.
  • Using the REST Endpoint URL obtained from the REST Endpoint field:
    curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         -H "X-Object-Meta-Language: english" \
         -H "X-Object-Meta-Country: US" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer/myObject
    

    The following is an example of the output of this command. Using the above command, the values of the X-Object-Meta-Language and X-Object-Meta-Country metadata headers are updated to english and US respectively.

    > POST /v1/Storage-acme/FirstContainer/myObject HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    > X-Object-Meta-Language: english
    > X-Object-Meta-Country: US
    >
    < HTTP/1.1 202 Accepted
    < Date: Mon, 09 Mar 2015 11:46:34 GMT
    < Content-Length: 76
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txd54813b92dcd46849b009-0054fd8819
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    <
    Accepted. The request is accepted for processing.
  • Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

    This cURL command example applies to the accounts created after November 2017.

    curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         -H "X-Object-Meta-Language: english" \
         -H "X-Object-Meta-Country: US" \
         https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e36/FirstContainer/myObject
    

    The following is an example of the output of this command. Using the above command, the values of the X-Object-Meta-Language and X-Object-Meta-Country metadata headers are updated to english and US respectively.

    > POST /v1/Storage-7b16fede61e1417ab83eb52e06f0e36/FirstContainer/myObject HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: storage-7b16fede61e1417ab83eb52e06f0e36.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    > X-Object-Meta-Language: english
    > X-Object-Meta-Country: US
    >
    < HTTP/1.1 202 Accepted
    < Date: Mon, 09 Mar 2015 11:46:34 GMT
    < Content-Length: 76
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txd54813b92dcd46849b009-0054fd8819
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    <
    Accepted. The request is accepted for processing.

Deleting Object Metadata

To delete all the custom metadata for an object, send a POST request without specifying any metadata header. All the custom metadata is deleted. Note that the system metadata is retained.

To delete specific custom metadata, send a POST request and specify only the metadata headers and their values that you’d like to retain or update. Do not specify the metadata that must be deleted. Any metadata headers that are specified in the request are updated. The headers that aren't specified in the request are deleted.

cURL Command Examples

The following command examples shows how to delete all the custom metadata of the object myObject.

Sample Cloud account with the following details:
  • Account name: acme
  • REST Endpoint URL: https://acme.storage.oraclecloud.com/v1/Storage-acme
  • REST Endpoint (Permanent) URL: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365

    Note:

    The REST Endpoint (Permanent) URL is displayed for the accounts created after November 2017.
  • Using the REST Endpoint URL obtained from the REST Endpoint field:
    curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer/myObject
    

    The following is an example of the output of this command:

    > POST /v1/Storage-acme/FirstContainer/myObject HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    >
    < HTTP/1.1 202 Accepted
    < Date: Mon, 22 Dec 2016 11:46:34 GMT
    < Content-Length: 76
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txd54813b92dcd46849b009-0054fd8819
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    <
    Accepted. The request is accepted for processing.
  • Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

    This cURL command example applies to the accounts created after November 2017.

  • curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer/myObject
    

    The following is an example of the output of this command:

    > POST /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer/myObject HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    >
    < HTTP/1.1 202 Accepted
    < Date: Mon, 22 Dec 2016 11:46:34 GMT
    < Content-Length: 76
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txd54813b92dcd46849b009-0054fd8819
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    <
    Accepted. The request is accepted for processing.

Scheduling Automatic Deletion of Objects

You can schedule deletion of objects at a specified time in the future or after a specified period of time has elapsed, by using the X-Delete-After or X-Delete-At header, respectively.

Note:

You cannot schedule automatic deletion of objects for an Archive container by using the X-Delete-After and X-Delete-At headers. (Not available on Oracle Cloud at Customer)

Any user with the Service Administrator role or a role that is specified in the X-Container-Write ACL of the container can perform this task.

To schedule automatic deletion while creating an object, include the X-Delete-After or X-Delete-At header in the PUT request. To schedule automatic deletion for an existing object, use the POST request. The Java library does not support scheduling automatic deletion of objects.

cURL Command Syntax

To schedule automatic deletion of an existing object after a specified duration:

curl -v -X POST \
     -H "X-Auth-Token: token" \
     -H "X-Delete-After: period" \
     accountURL/containerName/objectName

To schedule automatic deletion of an existing object at a specified time in the future:

curl -v -X POST \
     -H "X-Auth-Token: token" \
     -H "X-Delete-At: time" \
     accountURL/containerName/objectName

cURL Command Examples

Sample Cloud account with the following details:
  • Account name: acme
  • REST Endpoint URL: https://acme.storage.oraclecloud.com/v1/Storage-acme
  • REST Endpoint (Permanent) URL: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365

    Note:

    The REST Endpoint (Permanent) URL is displayed for the accounts created after November 2017.

The REST Endpoint URL for the sample Cloud account is used in the cURL command examples below. To use the REST Endpoint (Permanent) URL, replace https://acme.storage.oraclecloud.com/v1/Storage-acme with https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365.

  • The following command sets the object named myObject to be deleted automatically after 86400 seconds:

    curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         -H "X-Delete-After: 86400" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer/myObject
    

    The following is an example of the output of this command:

    > POST /v1/Storage-acme/myContainer/myObject HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    > X-Delete-After: 86400
    >
    < HTTP/1.1 202 Accepted
    < Date: Mon, 23 Mar 2015 12:32:39 GMT
    < Content-Length: 76
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txbb5a2f22164e47aa8116f-00551007e7
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    <
    The request is accepted for processing.
    

    The following command sets the object named myObject to be deleted automatically on November 30, 2014 at 10:00:00 GMT, represented by the UNIX Epoch timestamp, 1417341600:

    curl -v -X POST \
         -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
         -H "X-Delete-At: 1417341600" \
         https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer/myObject
    

    The following is an example of the output of this command:

    > POST /v1/Storage-acme/myContainer/myObject HTTP/1.1
    > User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.14.0.0 zlib/1.2.3 libidn/1.18 libssh2/1.4.2
    > Host: acme.storage.oraclecloud.com
    > Accept: */*
    > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
    > X-Delete-At: 1417341600
    >
    < HTTP/1.1 202 Accepted
    < Date: Mon, 23 Mar 2015 12:32:39 GMT
    < Content-Length: 76
    < Content-Type: text/html; charset=UTF-8
    < X-Trans-Id: txbb5a2f22164e47aa8116f-00551007e7
    < Cache-Control: no-cache
    < Pragma: no-cache
    < Content-Language: en
    <
    The request is accepted for processing.