2 Managing Containers in Object Storage Classic

This section provides documentation about managing containers in Oracle Cloud Infrastructure Object Storage Classic.

Topics:

• Typical Workflow for Managing Containers

• Creating Containers

• Creating Archive Containers

• Listing Containers

• Setting a Container-Specific Policy Using the REST API

• Deleting Containers

• Enabling Server-Side Encryption

• Setting Container Metadata

• Getting Container Metadata

• Deleting Container Metadata

Typical Workflow for Managing Containers

Use the following table as a guide to the workflow for managing containers. If you have not yet subscribed to or set up your service, see Workflow for Getting Started with Object Storage Classic.

Task	Description	More Information
Access the service	Access the service through any of the available interfaces.	Accessing Oracle Cloud Infrastructure Object Storage Classic
Generate an authentication token	Generate an authentication token if you are accessing the service through the REST API interface. If you are accessing the service through Java library, the authentication token would be automatically generated and applied.	Authenticating Access When Using REST API
Create containers	Create containers to organize your data.	Creating Containers
Delete containers	Delete empty containers when no longer needed.	Deleting Containers
Update container metadata	Set custom metadata or special metadata on a container.	Updating Container Metadata

Creating Containers

A container is a storage compartment that provides a way to organize the data stored in Oracle Cloud Infrastructure Object Storage Classic.

Any user with the Service Administrator role can create containers. You should create at least one container for your account. Containers are similar to a directory structure but with a key distinction: unlike directories, containers cannot be nested. By default, all containers are of the standard storage class (as opposed to the archive storage class).

Note:

Before you create your first container, check the replication policy set for your account. See About Replication Policy for Your Object Storage Classic Instance.

You can create containers by using the following interfaces:

Interface	Resources
Web Console (Not available on Oracle Cloud at Customer)	See Creating a Container Using the Web Console.
RESTful API	See: Creating a Container Using the REST API Create Container in REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic
Java Library	See createContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic.
File Transfer Manager API	See createContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.
File Transfer Manager CLI	See Creating a Container in Command-Line Reference for Oracle Cloud Infrastructure Object Storage Classic.

To create an archive container, you must set the X-Storage-Class header to Archive. For more information, see Creating Archive Containers. (Not available on Oracle Cloud at Customer)

Creating a Container Using the Web Console

(Not available on Oracle Cloud at Customer)

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Click Create Container.

   The Create Container dialog box is displayed.

3. Enter a name for the container.

   Note:

   Ensure that the container name complies with the input restrictions mentioned in Character Restrictions.
4. Select Standard in the Storage Class field.
5. To set a replication policy for the container, see Setting a Container-Specific Policy Using the Web Console.

   Note:

   This option is available only for accounts created after March 2018.
6. Click Create.

   The container is created and displayed in the console.

Creating a Container Using the REST API

cURL Command Syntax

curl -v -X PUT \
     -H "X-Auth-Token: token" \
     accountURL/containerName

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container to be created.

  Note:

  Ensure that the container name complies with the input restrictions mentioned in Character Restrictions.

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

• Success: 201 Created
• Failure: See Error Code Reference for Oracle Cloud Infrastructure Object Storage Classic

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 PUT \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer
  

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

  > PUT /v1/Storage-acme/FirstContainer 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 201 Created
  < Date: Fri, 06 Mar 2015 10:34:20 GMT
  < Content-Length: 0
  < Content-Type: text/html; charset=UTF-8
  < X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  

• Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

  Note:

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

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

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

  > PUT /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer 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 201 Created
  < Date: Fri, 06 Mar 2015 10:34:20 GMT
  < Content-Length: 0
  < Content-Type: text/html; charset=UTF-8
  < X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  

For setting the replication policy in the container, see Setting a Container-Specific Policy Using the REST API.

For information about getting details of a container, see Getting Container Metadata.

Creating Archive Containers

This topic does not apply to Oracle Cloud at Customer.

A container for which the X-Storage-Class metadata field is set to Archive is called an Archive container. You can use Archive containers to store data that won't be accessed for a while or that will be accessed infrequently. Any user with the Service Administrator role can create Archive containers.

You can create Archive containers by using the following interfaces:

Interface	Resources
Web Console	See Creating an Archive Container Using the Web Console.
RESTful API	See: Creating an Archive Container Using the REST API Create Container in REST API for Archive Storage in Oracle Cloud Infrastructure Object Storage Classic
File Transfer Manager API	See createContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.

Note:

• You can set X-Storage-Class only when creating a new container. After you set X-Storage-Class, you cannot change it.
• You cannot create an Archive container by using the Java API.

Features Not Supported for Archive Containers

The following features are not supported for an Archive container:

• Bulk-creating objects
• Bulk-deleting objects
• Scheduling automatic deletion of objects by using the X-Delete-At and X-Delete-After headers
• Georeplication
• Setting a container-specific replication policy

Creating an Archive Container Using the Web Console

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Click Create Container.

   The Create Container dialog is displayed.

3. Enter a name for the container.

   Note:

   Ensure that the container name complies with the input restrictions mentioned in Character Restrictions.
4. Select Archive in the Storage Class field.
5. Click Create.

   The container is created and displayed in the console.

Creating an Archive Container Using the REST API

cURL Command Syntax

curl -v -X PUT \
     -H "X-Auth-Token: token" \
     -H "X-Storage-Class: Archive" \
     accountURL/containerName

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container to be created.

  Note:

  Ensure that the container name complies with the input restrictions mentioned in Character Restrictions.

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

• Success: 201 Created
• Failure: See Error Code Reference for Oracle Cloud Infrastructure Object Storage Classic

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 PUT \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       -H "X-Storage-Class: Archive" 
       https://acme.storage.oraclecloud.com/v1/Storage-acme/firstArchiveContainer
  

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

  > PUT /v1/Storage-acme/firstArchiveContainer HTTP/1.1
  > User-Agent: curl/7.29.0
  > Host: acme.storage.oraclecloud.com:443 
  > Accept: */*
  > X-Auth-Token: AUTH_tk1ff0554c1fefff9209696d63553722fd
  > X-Storage-Class: Archive
  >
  < HTTP/1.1 201 Created
  < X-Trans-Id: tx1d8e9739df4a47bb847e0-005582875bga
  < Date: Thu, 18 Jun 2015 08:54:51 GMT
  < Content-Type: text/html;charset=UTF-8
  < Content-Length: 0
  <
  

• Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

  Note:

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

  curl -v -X PUT \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       -H "X-Storage-Class: Archive" 
       https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/firstArchiveContainer
  

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

  > PUT /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/firstArchiveContainer HTTP/1.1
  > User-Agent: curl/7.29.0
  > Host: storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com:443 
  > Accept: */*
  > X-Auth-Token: AUTH_tk1ff0554c1fefff9209696d63553722fd
  > X-Storage-Class: Archive
  >
  < HTTP/1.1 201 Created
  < X-Trans-Id: tx1d8e9739df4a47bb847e0-005582875bga
  < Date: Thu, 18 Jun 2015 08:54:51 GMT
  < Content-Type: text/html;charset=UTF-8
  < Content-Length: 0
  <
  

For information about getting details of an Archive container, see Getting Container Metadata.

For creating objects in an Archive container, see Creating Objects.

Listing Containers

All containers within an account can be listed.

Any user within the identity domain can perform this task.

You can list containers by using the following interfaces:

Interface	Resources
Web Console (Not available on Oracle Cloud at Customer)	See Listing Containers Using the Web Console.
RESTful API	See: Listing a Container Using the REST API List Endpoints in REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic.
Java Library	See listContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic
File Transfer Manager API	See listContainers in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.
File Transfer Manager CLI	See Listing Containers in Command-Line Reference for Oracle Cloud Infrastructure Object Storage Classic.

Listing Containers Using the Web Console

(Not available on Oracle Cloud at Customer)

Sign in to the Oracle Cloud Infrastructure Object Storage Classic console. The list of containers is displayed.

Listing a Container Using the REST API

Containers are sorted lexicographically using memcmp(). All containers, up to 10000 by default, will be returned in the list, unless you filter the list by using any of the following query parameters:

• limit: Limit the number of containers listed to the specified value. The default and maximum value is 10000.
• marker: Return containers with names greater than the specified string.
• end_marker: Return containers with names less than the specified string.
• format: Return extended information about each returned container in either xml or json format (REST API only).

cURL Command Syntax

curl -v -X GET \
     -H "X-Auth-Token: token" \
     accountURL[?query_parameter=value]

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• query_parameter=value is the optional filtering parameter.

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

• Success: 200 OK

  Note:

  If there are no containers, the HTTP response code would be 204 OK.
• Failure: See Error Code Reference for Oracle Cloud Infrastructure Object Storage Classic

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) is displayed for the accounts created after November 2017.

• Using the REST Endpoint URL obtained from the REST Endpoint field:

  curl -v -X GET \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       https://acme.storage.oraclecloud.com/v1/Storage-acme?limit=15
  

  This command lists the first 15 containers, lexicographically sorted, in the specified account.

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

  > GET /v1/Storage-acme 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_tk6403794c218a709d1c6c5a76444d01f6
  >
  < HTTP/1.1 200 OK
  < Date: Fri, 06 Mar 2015 10:38:15 GMT
  < Content-Length: 109
  < X-Account-Container-Count: 3
  < Accept-Ranges: bytes
  < X-Account-Object-Count: 843
  < X-Account-Bytes-Used: 10304761355
  < X-Timestamp: 1412823447.62495
  < X-Account-Meta-Test5: test1
  < X-Account-Meta-Quota-Bytes: 107374182400
  < Content-Type: text/plain; charset=utf-8
  < X-Account-Meta-Test: test
  < X-Account-Meta-Test1: test1
  < X-Trans-Id: tx29052c64fe384fc690ccc-0054f98397
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  <
  FirstContainer
  hello
  lab
  

• Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

  Note:

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

• curl -v -X GET \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365?limit=15
  

  This command lists the first 15 containers, lexicographically sorted, in the specified account.

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

  > GET /v1/Storage-7b16fede61e1417ab83eb52e06f0e365 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_tk6403794c218a709d1c6c5a76444d01f6
  >
  < HTTP/1.1 200 OK
  < Date: Fri, 06 Mar 2015 10:38:15 GMT
  < Content-Length: 109
  < X-Account-Container-Count: 3
  < Accept-Ranges: bytes
  < X-Account-Object-Count: 843
  < X-Account-Bytes-Used: 10304761355
  < X-Timestamp: 1412823447.62495
  < X-Account-Meta-Test5: test1
  < X-Account-Meta-Quota-Bytes: 107374182400
  < Content-Type: text/plain; charset=utf-8
  < X-Account-Meta-Test: test
  < X-Account-Meta-Test1: test1
  < X-Trans-Id: tx29052c64fe384fc690ccc-0054f98397
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  <
  FirstContainer
  hello
  lab
  

Setting a Container-Specific Policy

This topic does not apply to Oracle Cloud at Customer.

You can specify a different replication policy for each container other than the account-level replication policy. The container-specific policy enables you to control, at a more granular level, what data gets replicated to a geographical distant data center (DC).

You can set a container-specific replication policy by using the following interfaces:

Interface	Resources
Web Console	See Setting a Container-Specific Policy Using the Web Console.
RESTful API	See: Setting a Container-Specific Policy in a Data Center Within the Same Region Using the REST API Setting a Container-Specific Policy in a Different Region Using the REST API
File Transfer Manager CLI	See Setting a Container-Specific Replication Policy in Command-Line Reference for Oracle Cloud Infrastructure Object Storage Classic.
File Transfer Manager API	See ContainerReplicationPolicy in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.

Topics:

• Setting a Container-Specific Policy Using the Web Console
• Setting a Container-Specific Policy Using the REST API

Setting a Container-Specific Policy Using the Web Console

Important:

This topic applies to the accounts created after March 2018, wherein, for these accounts, the account-level replication policy has been set to any, by default.

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Click Create Container.

   The Create Container dialog box is displayed.

3. Enter a name for the container.

   Note:

   Ensure that the container name complies with the input restrictions mentioned in Character Restrictions.
4. Select Standard in the Storage Class field.
5. Select the data center in the Data Center field, in which the container must be created.

   The data center in which the container is created is the source data center.

6. Select Replicate to Data Center(s) under Advanced to replicate the container in the desired data center.

   The data center selected to replicate the container is the target data center. You can select multiple target DCs for a container.

7. Click Create.

   The container is created in the source data center and displayed in the web console.

Viewing the Container Replicated in the Target Data Center

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Select the target data center in the Containers pane.

   The list of containers created in your account is displayed.

3. Identify the container that you created in the source data center.
4. Select the container.

   The following message is displayed:

   You are currently viewing a READ ONLY copy of this container. Switch to source environment to edit this container.

Setting a Container-Specific Policy Using the REST API

This topic does not apply to Oracle Cloud at Customer.

You can specify a different replication policy for each container other than the account-level policy. The container-level policy overrides the account-level policy. This enables you to control, at a more granular level, what data gets replicated to a geographical distant data center (DC).

Any user with the Service Administrator role can perform this task.

Note:

• You cannot set replication policies for archive containers.
• You can set the container-level replication policy when you create a container or when the container is empty.

Setting a Container-Specific Policy in a Data Center Within the Same Region Using the REST API

You can set your container’s source DC and georeplication DC to be a subset of that of the service instance. For example, if the primary DC of your service instance is us2 and the georeplication DCs are us6 and uscom-central-1, then the primary DC of your container can be us6, us2, or uscom-central-1. One or both of the remaining DCs can be selected as the replication DC of the container. Specify your container’s primary DC URL and replication DC URLs in the sourceRegion and targetRegions parameters respectively in the request body JSON file.

Write requests to a container for which you've set a replication policy must be sent to the DC-specific REST endpoint URL, and not to the global namespace URL.

DC-specific REST endpoint URLs are in the format:

https://dataCenterCode.storage.oraclecloud.com/v1/Storage-identityDomainID

Example: https://us2.storage.oraclecloud.com/Storage-myDomain

Setting a Container-Specific Policy in a Different Region Using the REST API

You can specify a replication policy for your container by selecting a data center outside the region where the primary DC and georeplication DC of your service instance are located. For example, if the primary DC and georeplication DC of your service instance are us2 and us6 in the US region, then you can select a data center, say em2 that’s located in a non-US region to replicate your container. Specify the external container to which the objects from your container must be replicated by specifying the external container’s URL in the externalTargetRegions parameter of the request body JSON file. You can specify multiple external replication DCs for your container.

When your container is the destination for the replication of objects from an external container, specify the external container’s URL in the externalSourceRegions parameter of the request body JSON file. Your container can be the destination for replication of objects from multiple source containers.

Note:

While setting the container’s replication policy in a different region, first set the replication policy of the target region with the externalSourceRegions parameter, and next set the replication of the source region with the externalTargetRegions parameter.

Important:

To set the container’s replication policy in a different region, ensure that the REST Endpoint URLs specified in the request body JSON file are in the GUID format. For example: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer.

Do not use the friendly name format. For example: https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer. The friendly name REST Endpoint URLs may change and lead to invalid replication policy.

Creating the Request Body JSON File

Create a request body JSON file using the following template and store it on your host:

{
  "sourceRegion": {
    "name": "primary_DC_code",
    "url": "primary_DC_url"},
  "targetRegions": [{
    "name": "replication_DC_code",
    "url": "replication_DC_url"}],
  "externalSourceRegions": [{
    "name": "external",
    "url": "external_source_url"}],
  "externalTargetRegions": [{
    "name": "external",
    "url": "external_target_url"}]
}

• primary_DC_code is the data center code of the primary DC of your container.

• primary_DC_url is the URL of your container located in the primary DC of your container. This is an optional parameter.

• replication_DC_code is the data center code of the replication DC of your container.

• replication_DC_url is the URL of the replication of your container located in the replication DC of your container. This is an optional parameter.

• external_source_url is the URL of the container in an external region from which the objects would be replicated into your container.

• external_target_url is the URL of the container in an external region into which the objects in your container must be replicated.

Note:

The parameters primary_DC_url and replication_DC_url are optional. Providing the data center code is sufficient for the normal working of the command.

• Example request body JSON file for your container myContainer in the following scenario:

  • Your service instance has us2 primary DC.

  • Your service instance has us6 and uscom-central-1 replication DCs.

  • Primary DC for your container is us6.

  • Replication DCs for your container areus2 and uscom-central-1 within the same region.

  Note that the examples demonstrate the use of GUID-based URLs to set the source and target regions. If the GUID-based URL for the container is https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.

  {
    "sourceRegion": {
      "name": "us6",
      "url": "https://<foo1>.storage.oraclecloud.com/v1/Storage-<bar1>/myContainer"},
    "targetRegions": [{
      "name": "us2",
      "url": "https://<foo2>.storage.oraclecloud.com/v1/Storage-<bar2>/myContainer"}, {
      "name": "uscom-central-1",
      "url": "https://<foo3>.storage.oraclecloud.com/v1/Storage-<bar3>/myContainer"}],
    "externalSourceRegions": [],
    "externalTargetRegions": []
  }

• Example request body JSON file for your container mySecondContainer in the following scenario:

  • Your service instance has us2 primary DC and us6 replication DC.

  • Primary DC for your container is us2.

  • Replication DC for your container is us6 within the same region.

  • Your container is the destination for replication from a container externalSourceContainer1 and externalSourceContainer2 that reside in different regions.

  • The objects in your container are replicated to the container externalTargetContainer in a data center of a different region.

  Note that the examples demonstrate the use of GUID-based URLs to set the source and target regions. If the GUID-based URL for the container is https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.

  {
    "sourceRegion": {
      "name": "us2",
      "url": "https://<foo4>.storage.oraclecloud.com/v1/Storage-<bar4>/mySecondContainer"},
    "targetRegions": [{
      "name": "us6",
      "url": "https://<foo5>.storage.oraclecloud.com/v1/Storage-<bar5>/mySecondContainer"}],
    "externalSourceRegions": [{
      "name": "external",
      "url": "https://<foo6>.storage.oraclecloud.com/v1/Storage-<bar6>/externalSourceContainer1"}, {
      "name": "external",
      "url": "https://<foo7>.storage.oraclecloud.com/v1/Storage-<bar7>/externalSourceContainer2"}],
    "externalTargetRegions": [{
      "name": "external",
      "url": "https://<foo8>.storage.oraclecloud.com/v1/Storage-<bar8>/externalTargetContainer"}]
  }

cURL Command Syntax to Specify the Replication Policy for a Container

• To specify a replication policy for an empty container:

  curl -v -X POST \
       -H "X-Auth-Token: token" \
       -H "Content-Type: application/json" \
       -d "@file" \
       accountURL/containerName?repPolicy
  

• To specify a replication policy while creating a container:

  curl -v -X PUT \
       -H "X-Auth-Token: token" \
       -d "@file" \
       accountURL/containerName?repPolicy
  

• To read a container’s replication policy:

  curl -v -X GET \
       -H "X-Auth-Token: token" \
       accountURL/containerName?repPolicy
  

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• file is the full path and name of the file that contains the required container-level policy, in JSON format.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the container for which the replication policy must be set.

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

• Success:
  • When updating a container with the replication policy: 204 No Content
  • When creating a container and specifying the replication policy: 201 Created
  • When reading a container’s replication policy: 200 OK
• Failure: See Error Code Reference for Object Storage Classic

cURL Command Examples

1. This command sets the replication policy for the container FirstContainer:

   curl -v -X POST \
        -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
        -H "Content-Type: application/json" \
        -d "@requestbody.json" \
        https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer?repPolicy
   

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

   > POST /v1/Storage-acme/FirstContainer?repPolicy HTTP/1.1
   > User-Agent: curl/7.49.1
   > Host: acme.storage.oraclecloud.com
   > Accept: */*
   > Content-Type: application/json
   > Content-Length: 489
   > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
   >
   * upload completely sent off: 489 out of 489 bytes
   < HTTP/1.1 204 No Content
   < Date: Fri, 10 Nov 2017 06:32:55 GMT
   < Content-Type: text/html;charset=UTF-8
   < X-Trans-Id: txe8869b3edea348e5b49eb-0054f99743
   

2. This command specifies the replication policy while creating the container SecondContainer:

   curl -v -X PUT \
        -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
        -d "@requestbody.json" \
        https://acme.storage.oraclecloud.com/v1/Storage-acme/SecondContainer?repPolicy
   

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

   > PUT /v1/Storage-acme/SecondContainer?repPolicy HTTP/1.1
   > User-Agent: curl/7.49.1
   > Host: acme.storage.oraclecloud.com
   > Accept: */*
   > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
   >
   < HTTP/1.1 201 Created
   < Date: Thu, 09 Nov 2017 10:03:18 GMT
   < Content-Type: text/html; charset=UTF-8
   < X-Trans-Id: txe8869b3edea348e5b49eb-0054f99678
   < X-Last-Modified-Timestamp: 1510221797.90473
   < Cache-Control: no-cache
   < Pragma: no-cache
   < Content-Language: en
   

3. This command displays the replication policy of the container FirstContainer:

   curl -v -X GET \
        -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
        https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer?repPolicy
   

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

   > GET /v1/Storage-acme/FirstContainer?repPolicy HTTP/1.1
   > User-Agent: curl/7.49.1
   > Host: acme.storage.oraclecloud.com
   > Accept: */*
   > X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b
   >
   < HTTP/1.1 200 OK
   < < Date: Fri, 10 Nov 2017 06:17:44 GMT
   < Content-Type: application/json;charset=UTF-8
   < X-Trans-Id: txe8869b3edea348e5b49eb-0054f99838
   {
     "mode": "ACTIVE_PASSIVE",
     "sourceRegion": {
       "name": "us2",
       "url": "https://<foo9>.storage.oraclecloud.com/v1/Storage-<bar9>/FirstContainer"
     },
     "targetRegions": [{
       "name": "us6",
       "url": "https://<foo10>.storage.oraclecloud.com/v1/Storage-<bar10>/FirstContainer"
     }],
     "externalSourceRegions": [{
       "name": "external",
       "url": "https://<foo11>.storage.oraclecloud.com/v1/Storage-<bar11>/ExternalSourceContainer"
     }],
     "externalTargetRegions": [{
       "name": "external",
       "url": "https://<foo12>.storage.oraclecloud.com/v1/Storage-<bar12>/ExternalTargetContainer"
     }]
   * STATE: PERFORM => DONE handle 0x600057870; line 1955 (connection #0)
   * multi_done
   * Connection #0 to host left intact
   }

   Note that the example output displays the GUID-based URLs that are used to set the source and target regions. If the GUID-based URL for the container is https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.

Deleting Containers

All objects within a container must first be deleted before the container can be deleted.

Any user with the Service Administrator role can perform this task.

You can delete containers by using the following interfaces:

Interface	Resources
Web Console (Not available on Oracle Cloud at Customer)	See Deleting a Container Using the Web Console.
RESTful API	See Delete Container in REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic.
Java Library	See deleteContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic.
File Transfer Manager CLI	See Deleting Containers in Command-Line Reference for Oracle Cloud Infrastructure Object Storage Classic.
File Transfer Manager API	See deleteContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.

For information about deleting multiple objects in a container in a single operation, see Bulk-Deleting Objects.

Deleting a Container Using the Web Console

(Not available on Oracle Cloud at Customer)

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.

   The list of containers is displayed.

2. Identify the container that you want to delete.
3. Click delete on the left side of the container name.

   The delete button is displayed only for empty containers.

   The following message appears:

   Are you sure want to delete this container?

4. Click OK.

   The container is deleted.

Deleting a Container Using the REST API

All objects within a container must first be deleted before the container can be deleted. To find out whether a container contains any objects, send a HEAD request to the container URL.

cURL Command Syntax

curl -v -X DELETE \
     -H "X-Auth-Token: token" \
     accountURL/containerName

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container to be deleted.

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

• Success: 204 No Content
• Failure: See Error Code Reference for Oracle Cloud Infrastructure Object Storage Classic

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) is displayed for the accounts created after November 2017.

• Using the REST Endpoint URL obtained from the REST Endpoint field:

  curl -v -X DELETE \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer
  

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

  > DELETE /v1/Storage-acme/FirstContainer 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 204 No Content
  < Date: Fri, 06 Mar 2015 10:43:38 GMT
  < Content-Length: 0
  < Content-Type: text/html; charset=UTF-8
  < X-Trans-Id: txc100a7408d564f82916fb-0054f984da
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  <
  

• Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

  Note:

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

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

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

  > DELETE /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer 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 204 No Content
  < Date: Fri, 06 Mar 2015 10:43:38 GMT
  < Content-Length: 0
  < Content-Type: text/html; charset=UTF-8
  < X-Trans-Id: txc100a7408d564f82916fb-0054f984da
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  <
  

Enabling Server-Side Encryption

Topics

• About Server-Side Encryption
• Enabling Server-Side Encryption Using the Web Console
• Enabling Server-Side Encryption Using an Oracle-Provided Key
• Enabling Server-Side Encryption Using a Customer-Provided Key
• Verifying Server-Side Encryption

About Server-Side Encryption

You can configure containers in your service instance to store all the data uploaded to them in an encrypted form. The encryption and decryption occur entirely on the server. When you download objects from such containers, the object is decrypted on the server and then delivered to you. Server-side encryption uses AES-256 encryption algorithm.

You can enable encryption for a container by adding the X-Server-Side-Encryption metadata header. This header can have one of the following values:

• BASE_ENCRYPTION: Indicates that data in the container must be encrypted.
• NONE: Indicates that server-side encryption is not enabled for the container. This is equivalent to omitting this header entirely.

Provide your own Base64-encoded AES-256 master encryption key for a specific container. You must include the X-Server-Side-Encryption-Container-Key metadata header and provide your master key, in addition to the X-Server-Side-Encryption metadata header.

If you do not specify the X-Server-Side-Encryption-Container-Key header, the container is encrypted using an Oracle-provided, randomly generated master key.

Note:

You can enable server-side encryption only while creating a container.

Server-side encryption is not available in all Oracle data regions. If you don’t see the Enable Encryption option under Advanced in the Create a Container dialog box in the web console, then this feature is not available in your data region.

You can't enable or disable this feature for an existing container. Once server-side encryption is set, the feature is immutable.

Enabling Server-Side Encryption Using the Web Console

This topic does not apply to Oracle Cloud at Customer.

Note:

Server-side encryption can be enabled only while creating a container, not later.

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Click Create Container.

   The Create Container dialog box is displayed.

3. Enter a name for the container.

   For the list of character restrictions while creating a container, see Character Restrictions.

4. Select Standard or Archive in the Storage Class field, based on your choice of the storage class for the container.
5. To enable server-side encryption of the data stored in the container, select Enable Encryption.

   All the data stored in the container is encrypted using an Oracle-provided key.

6. To enable server-side encryption using your master encryption key:
   • Generate an AES 256 encryption key using the OpenSSL toolkit.

     openssl enc -aes256 -k password -P

     Example:

     openssl enc -aes256 -k mypassword -P

     Output:

     salt=ADCA338FB4594CC6
     key=08A8C5A2C81EB0508AAA1EAB7C81BC7AC9747E3E752E04FECAEE8D09E83A8C09
     iv=4586BFB397A9CE3FFB7F90D14BF6B506

   • Encode the key in Base64 format.

     echo 'value_from_key_field' | xxd -r -p | base64

     Example:

     echo "08A8C5A2C81EB0508AAA1EAB7C81BC7AC9747E3E752E04FECAEE8D09E83A8C09" | xxd -r -p | base64

     Output:

     CKjFosgesFCKqh6rfIG8esl0fj51LgT+yu6NCeg6jAk=

   • Enter the Base64-encoded AES-256 encryption key in the Server Side Encryption w/ Customer Master Keys field in the console.
7. Click Create.

   The container is created and displayed in the console.

Enabling Server-Side Encryption Using an Oracle-Provided Key

To enable server-side encryption, create a container and assign it the X-Server-Side-Encryption metadata header. All objects written to a container with this header will be encrypted.

curl -v -X PUT \
     -H "X-Auth-Token: token" \
     -H "X-Server-Side-Encryption: BASE_ENCRYPTION" \
     accountURL/containerName

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container to be created.

  For the list of character restrictions while creating a container, see Character Restrictions.

• X-Server-Side-Encryption is the header to enable server-side encryption.

Example:

Create a container MyEncryptedCont and assign the server-side encryption metadata header.

curl -v -X PUT \
     -H "X-Auth-Token: AUTH_tk57dee23521d6e4d809deeffa6bd23cd6" 
     -H "X-Server-Side-Encryption: BASE_ENCRYPTION" 
     https://acme.storage.oraclecloud.com/v1/Storage-acme/MyEncryptedCont 

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

PUT /v1/Storage-acme/MyEncryptedCont 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-Server-Side-Encryption: BASE_ENCRYPTION 
< HTTP/1.1 201 Created
< Date: Wed, 06 Dec 2016 10:34:20 GMT
< Content-Length: 0
< Content-Type: text/html; charset=UTF-8
< X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Language: en

Enabling Server-Side Encryption Using a Customer-Provided Key

To enable server-side encryption using your master encryption key, generate a Base64-encoded AES-256 encryption key and assign the following headers when you create the container:

• X-Server-Side-Encryption
• X-Server-Side-Encryption-Container-Key

1. Generate an AES 256 encryption key.

   openssl enc -aes256 -k password -P

   Example:

   openssl enc -aes256 -k mypassword -P

   Output:

   salt=ADCA338FB4594CC6
   key=08A8C5A2C81EB0508AAA1EAB7C81BC7AC9747E3E752E04FECAEE8D09E83A8C09
   iv=4586BFB397A9CE3FFB7F90D14BF6B506

2. Encode the key in Base64 format.

   echo 'value_from_key_field' | xxd -r -p | base64

   Example:

   echo "08A8C5A2C81EB0508AAA1EAB7C81BC7AC9747E3E752E04FECAEE8D09E83A8C09" | xxd -r -p | base64

   Output:

   CKjFosgesFCKqh6rfIG8esl0fj51LgT+yu6NCeg6jAk=

3. Create a container and assign the server-side encryption metadata headers.

   curl -v -X PUT \
        -H "X-Auth-Token: token" \
        -H "X-Server-Side-Encryption: BASE_ENCRYPTION" \
        -H "X-Server-Side-Encryption-Container-Key: master_encryption_key"
        accountURL/containerName

   • token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
   • For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
   • containerName is the name of the container to be created.

     For the list of character restrictions while creating a container, see Character Restrictions.

   • X-Server-Side-Encryption is the header to enable server-side encryption.
   • master_encryption_key is the Base64–encoded AES-256 encryption key generated in the previous step.

   Example:

   Create a container MyEncryptedCont and assign the server-side encryption metadata headers.

   curl -v -X PUT \
        -H "X-Auth-Token: AUTH_tk57dee23521d6e4d809deeffa6bd23cd6" 
        -H "X-Server-Side-Encryption: BASE_ENCRYPTION" 
        -H "X-Server-Side-Encryption-Container-Key: CKjFosgesFCKqh6rfIG8esl0fj51LgT+yu6NCeg6jAk="
        https://acme.storage.oraclecloud.com/v1/Storage-acme/MyEncryptedCont 

   Note:

   The URL of the account in this example is https://acme.storage.oraclecloud.com/v1/Storage-acme. Replace this URL with the URL for your account. For the steps to find out your account URL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.

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

   PUT /v1/Storage-acme/MyEncryptedCont 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-Server-Side-Encryption: BASE_ENCRYPTION 
   > X-Server-Side-Encryption-Container-Key: CKjFosgesFCKqh6rfIG8esl0fj51LgT+yu6NCeg6jAk=
   < HTTP/1.1 201 Created
   < Date: Wed, 07 Dec 2016 10:34:20 GMT
   < Content-Length: 0
   < Content-Type: text/html; charset=UTF-8
   < X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
   < Cache-Control: no-cache
   < Pragma: no-cache
   < Content-Language: en

Verifying Server-Side Encryption

Verify the container metadata to check if server-side encryption is enabled for the container.

curl -v -X HEAD \
     -H "X-Auth-Token:token" \
     accountURL/containerName

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container to be created.

Example:

curl -v -X HEAD \
     -H "X-Auth-Token: AUTH_tk64e7143df33fcbf2f20047c3c37984db" \
      https://acme.storage.oraclecloud.com/v1/Storage-acme/MyEncryptedCont

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

> HEAD /v1/Storage-acme/MyEncryptedCont HTTP/1.1
> User-Agent: curl/7.29.0
> Host: acme.storage.oraclecloud.com
> Accept: */*
> X-Auth-Token: AUTH_tk64e7143df33fcbf2f20047c3c37984db
< 
< HTTP/1.1 204 No Content
< Date: Wed, 7 Dec 2016 11:40:11 GMT
< X-Container-Object-Count: 0
< X-Container-Write: Storage-acme.Storage.Storage_ReadWriteGroup,Storage-acme.myCustomRole
< X-Container-Meta-Category: Books
< Accept-Ranges: bytes
< X-Container-Meta-Quota-Count: 100
< X-Timestamp: 1425639066.56315
< X-Container-Read: .r:*,.rlistings
< X-Server-Side-Encryption: BASE_ENCRYPTION
< X-Container-Bytes-Used: 0
< Content-Type: text/plain; charset=utf-8
< X-Container-Meta-Quota-Bytes: 10737418240
< X-Trans-Id: txb0b9882eceba45b287266-0054f9921b
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Language: en

The X-Server-Side-Encryption metadata header is displayed in the output with the value BASE_ENCRYPTION, confirming that server-side encryption is enabled in the container.

Getting Container Metadata

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

You can retrieve information about an object in a container by sending a HEAD request, which returns the following information:

• Container ACLs (X-Container-Read and X-Container-Write)
• Container quotas: (X-Container-Meta-Quota-Count and X-Container-Meta-Quota-Bytes)
• Number of objects in the container (X-Container-Object-Count)
• Storage space used by all objects in the container, in bytes (X-Container-Bytes-Used)
• Custom metadata (X-Container-Meta-Name)
• Storage class of the container (X-Storage-Class), returned only for Archive containers

You can view the container metadata by using the following interfaces:

Interface	Resources
Oracle Cloud Infrastructure Object Storage Classic Console (Not available on Oracle Cloud at Customer)	See Getting Container Metadata Using the Web Console.
RESTful API	See Show Container Metadata in REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic.
File Transfer Manager API	See getContainer in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager.
File Transfer Manager CLI	See Getting Container Metadata in Command-Line Reference for Oracle Cloud Infrastructure Object Storage Classic.

Getting Container Metadata Using the Web Console

(Not available on Oracle Cloud at Customer)

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Select a container from the list. Expand Container Information pane for the container.

   The details of the container are displayed in the Container Information pane.

Getting Container Metadata Using the REST API

cURL Command Syntax

curl -v -X HEAD \
     -H "X-Auth-Token: token" \
     accountURL/containerName

• token is the authentication token obtained earlier from Oracle Cloud Infrastructure Object Storage Classic. See Authenticating Access When Using the REST API.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container for which metadata should be retrieved.

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

• Success: 204 No Content
• Failure: See Error Code Reference for Oracle Cloud Infrastructure Object Storage Classic

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 HEAD \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer
  

  The following is an example of the output of this command for a Standard container:

  > HEAD /v1/Storage-acme/FirstContainer 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 204 No Content
  < Date: Fri, 06 Mar 2015 11:40:11 GMT
  < X-Container-Object-Count: 0
  < X-Container-Write: Storage-acme.Storage.Storage_ReadWriteGroup,Storage-acme.myCustomRole
  < X-Container-Meta-Category: Books
  < Accept-Ranges: bytes
  < X-Container-Meta-Quota-Count: 100
  < X-Timestamp: 1425639066.56315
  < X-Container-Read: .r:*,.rlistings
  < X-Container-Bytes-Used: 0
  < Content-Type: text/plain; charset=utf-8
  < X-Container-Meta-Quota-Bytes: 10737418240
  < X-Trans-Id: txb0b9882eceba45b287266-0054f9921b
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  

  For an Archive container, the header X-Storage-Class displays the value Archive in the metadata. The following is an example of this command:

  > HEAD /v1/Storage-acme/firstArchiveContainer1 HTTP/1.1
  > User-Agent: curl/7.29.0
  > Host: acme.storage.oraclecloud.com:443
  > Accept: */*
  > X-Auth-Token: AUTH_tk32486a5bbed54ee74213a30d6d128f9d
  >
  < HTTP/1.1 204 No Content
  < X-Container-Object-Count: 0
  < X-Container-Write: cloudua001.Storage.Storage_ReadWriteGroup
  < Accept-Ranges: bytes
  < X-Timestamp: 1434733473.12286
  < X-Container-Read: cloudua001.Storage.Storage_ReadOnlyGroup,cloudua001.Storage.Storage_ReadWriteGroup
  < X-Container-Bytes-Used: 0
  < X-Trans-Id: txfcffc30b5a0c44cb91491-005584544ega
  < Date: Fri, 19 Jun 2015 17:41:34 GMT
  < X-Storage-Class: Archive
  < Content-Type: text/plain;charset=utf-8
  

• Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

  Note:

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

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

  The following is an example of the output of this command for a Standard container:

  > HEAD /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer 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 204 No Content
  < Date: Fri, 06 Mar 2015 11:40:11 GMT
  < X-Container-Object-Count: 0
  < X-Container-Write: Storage-7b16fede61e1417ab83eb52e06f0e365.Storage.Storage_ReadWriteGroup,Storage-7b16fede61e1417ab83eb52e06f0e365.myCustomRole
  < X-Container-Meta-Category: Books
  < Accept-Ranges: bytes
  < X-Container-Meta-Quota-Count: 100
  < X-Timestamp: 1425639066.56315
  < X-Container-Read: .r:*,.rlistings
  < X-Container-Bytes-Used: 0
  < Content-Type: text/plain; charset=utf-8
  < X-Container-Meta-Quota-Bytes: 10737418240
  < X-Trans-Id: txb0b9882eceba45b287266-0054f9921b
  < Cache-Control: no-cache
  < Pragma: no-cache
  < Content-Language: en
  

  For an Archive container, the header X-Storage-Class displays the value Archive in the metadata. The following is an example of this command:

  > HEAD /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/firstArchiveContainer1 HTTP/1.1
  > User-Agent: curl/7.29.0
  > Host: storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com:443
  > Accept: */*
  > X-Auth-Token: AUTH_tk32486a5bbed54ee74213a30d6d128f9d
  >
  < HTTP/1.1 204 No Content
  < X-Container-Object-Count: 0
  < X-Container-Write: cloudua001.Storage.Storage_ReadWriteGroup
  < Accept-Ranges: bytes
  < X-Timestamp: 1434733473.12286
  < X-Container-Read: cloudua001.Storage.Storage_ReadOnlyGroup,cloudua001.Storage.Storage_ReadWriteGroup
  < X-Container-Bytes-Used: 0
  < X-Trans-Id: txfcffc30b5a0c44cb91491-005584544ega
  < Date: Fri, 19 Jun 2015 17:41:34 GMT
  < X-Storage-Class: Archive
  < Content-Type: text/plain;charset=utf-8
  

Deleting Container Metadata

You can delete container metadata by using the following interfaces:

Interface	Resources
Oracle Cloud Infrastructure Object Storage Classic Console (Not available on Oracle Cloud at Customer)	See Deleting Container Metadata Using the Web Console.
RESTful API	See: Deleting Container Metadata Using the REST API Create, update, or delete container metadata in REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic
Java Library	See deleteContainerMetadata in Java API Reference for Oracle Cloud Infrastructure Object Storage Classic.

Deleting Container Metadata Using the Web Console

(Not available on Oracle Cloud at Customer)

1. Sign in to the Oracle Cloud Infrastructure Object Storage Classic console.
2. Select the container from which you would like to delete the metadata.
3. Expand Container Information.

   The details of the container are displayed.

4. Click Edit.

   Look for the Custom Metadata field.

5. Identify the metadata name and value that you want to delete.
6. Click on the right side of the metadata value.
7. Click Save.

   The metadata name and value are deleted.

Deleting Container Metadata Using the REST API

cURL Command Syntax

curl -v -X POST \
     -H "X-Auth-Token: token" \
     -H "X-Remove-Container-Meta-Name: any_arbitrary_string" \
     accountURL/containerName

• 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 key and value to be deleted.
• For the syntax of accountURL, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources.
• containerName is the name of the container from which the metadata should be deleted.

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

• Success: 204 No Content
• Failure: See Error Code Reference for Oracle Cloud Infrastructure Object Storage Classic

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-Remove-Container-Meta-Category: Books" \
       https://acme.storage.oraclecloud.com/v1/Storage-acme/FirstContainer
  

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

  > POST /v1/Storage-acme/FirstContainer 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-Remove-Container-Meta-Category: Books
  >
  < HTTP/1.1 204 No Content
  < X-Trans-Id: tx30d406ea72b340378476a-00585b78c7ga
  < Date: Thu, 22 Dec 2016 06:55:04 GMT
  < Connection: keep-alive
  < X-Last-Modified-Timestamp: 1482389703.89669
  < Content-Type: text/html;charset=UTF-8
  <
  

• Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field:

  Note:

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

  curl -v -X POST \
       -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
       -H "X-Remove-Container-Meta-Category: Books" \
       https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer
  

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

  > POST /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/FirstContainer 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
  > X-Remove-Container-Meta-Category: Books
  >
  < HTTP/1.1 204 No Content
  < X-Trans-Id: tx30d406ea72b340378476a-00585b78c7ga
  < Date: Thu, 22 Dec 2016 06:55:04 GMT
  < Connection: keep-alive
  < X-Last-Modified-Timestamp: 1482389703.89669
  < Content-Type: text/html;charset=UTF-8
  <