1. Using Oracle Cloud Infrastructure Object Storage Classic
  2. Getting Started with Object Storage Classic

1 Getting Started with Object Storage Classic

This section describes how to get started with Oracle Cloud Infrastructure Object Storage Classic.

Topics:

For the definitions of the terms used in this and other documents in the Oracle Cloud library, see Oracle Cloud Terminology in Getting Started with Oracle Cloud.

Interfaces to Object Storage Classic

The following table summarizes the Oracle-provided interfaces to Oracle Cloud Infrastructure Object Storage Classic.

Note:

Oracle has certified certain third-party products for use with Oracle Cloud Infrastructure Object Storage Classic. For more information, see Certified Third-Party Products.
Interface Description More Information

Web Console

(Not available on Oracle Cloud at Customer)

A web-based console to manage your service instances, containers, and objects.

RESTful Web Service API

Oracle Cloud Infrastructure Object Storage Classic provides REST APIs that are compatible with OpenStack Swift. The following major additions have been made:

  • Centralized identity management across Oracle Cloud
  • Centralized reporting of usage metrics
  • Global namespace URL to access the service
  • Archiving and restoring objects

Oracle Cloud Infrastructure Object Storage Classic does not support the following OpenStack Swift features:

  • Object versioning
  • Static website support
  • Container synchronization
  • Form post
  • Account ACLs
  • Rate limits

The RESTful web service API is available only over HTTPS.

Oracle Cloud Infrastructure Storage Software Appliance

(Not available on Oracle Cloud at Customer)

Oracle Cloud Infrastructure Storage Software Appliance is a tool that you can install on-premises and then use to easily connect your on-premises applications and workflows to Oracle Cloud Infrastructure Object Storage Classic.

Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager API

Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager API is a Java library that provides a simple interface to upload or download individual and multiple objects of various sizes to standard and archive containers in Oracle Cloud Infrastructure Object Storage Classic.

Oracle Cloud Infrastructure Object Storage Classic CLI

The Oracle Cloud Infrastructure Object Storage Classic CLI is a cross-platform Java-based command line tool that you can use to upload and download objects of various sizes to standard and archive containers in Oracle Cloud Infrastructure Object Storage Classic.

Java Library

A Java library that wraps the RESTful web service API.

The Java library supports most of the major features of the RESTful web service API.

The Java library also provides client-side encryption utilities.

Tasks Supported by the Interfaces of Object Storage Classic

Use the following table as a guide to select the interface to Oracle Cloud Infrastructure Object Storage Classic. Yes indicates that the task can be performed using the interface.

Task Web Console(Not available on Oracle Cloud at Customer) RESTful API Java Library Storage Software Appliance 1.4(Not available on Oracle Cloud at Customer) FTM API (version 2.4) FTM CLI (version 2.4)

Setting account metadata

Yes

Yes

No

No

Yes

Yes

Getting account metadata

Yes

Yes

No

No

Yes

Yes

Creating containers

Yes

Yes

Yes

Yes

See Note.

Yes

Yes

Creating archive containers

Yes

Yes

No

Yes

Yes

Yes

Deleting containers

Yes

Yes

Yes

No

Yes

Yes

Listing containers

Yes

Yes

Yes

No

Yes

Yes

Setting custom metadata for containers

Yes

Yes

Yes

No

Yes

Yes

Setting container ACLs

Yes

Yes

Yes

No

Yes

Yes

Setting container quotas

Yes

Yes

No

No

Yes

Yes

Setting a replication policy for a container

No

Yes

No

No

Yes

Yes

Getting container metadata

Yes

Yes

No

No

Yes

Yes

Making objects in a container immutable

No

Yes

No

No

Yes

Yes

Uploading files to standard containers

Yes

Yes

Yes

Yes

Yes

Yes

Uploading files to archive containers

Yes

Yes

No

No

Yes

Yes

Uploading multiple objects in parallel

No

No

No

Yes

Yes

Yes

Listing objects

Yes

Yes

Yes

Yes

Yes

Yes

Deleting objects

Yes

Yes

Yes

Yes

Yes

Yes

Uploading multiple files in one operation

No

Yes

No

No

Yes

Yes

Deleting multiple objects in one operation

No

Yes

No

No

Yes

Yes

Downloading objects

Yes

Yes

Yes

Yes

Yes

Yes

Downloading multiple objects

No

No

No

Yes

Yes

Yes

Updating custom metadata for objects

No

Yes

Yes

No

Yes

Yes

Updating special metadata for objects

No

Yes

No

No

Yes

Yes

Copying objects

No

Yes

No

No

Yes

Yes

Encrypting objects

No

No

Yes

Yes

Yes

Yes

Restoring archive objects

Yes

Yes

No

Yes

Yes

Yes

Resuming interrupted uploads

No

No

No

Yes

Yes

Yes

Ensuring the integrity of uploaded data

No

No

No

Yes

Yes

Yes

Supporting NFS protocol

No

No

No

Yes

No

No

Monitoring upload activity

No

No

No

Yes

Yes

No

Rotating encryption keys

No

No

Yes

Yes

Yes

Yes

Local disk caching

No

No

No

Yes

No

No

Network throttling

No

No

No

Yes

No

No

Automatic segmentation of large files

No

No

No

Yes

Yes

Yes

Note:

During an upload operation, if the container specified doesn't exist, then it is created. But you can't create an empty container.

Workflow for Getting Started with Object Storage Classic

Not Oracle Cloud Machine This topic does not apply to Oracle Cloud Machine.

Use the following table as a guide to the workflow for getting started with Oracle Cloud Infrastructure Object Storage Classic:

Task Description More Information

Request a trial or purchase a subscription to Oracle Cloud Infrastructure Object Storage Classic

Provide your information, and sign up for a free trial or purchase a subscription. After activation, create accounts for your users and assign them appropriate privileges and roles.

How to Begin with Oracle Cloud Infrastructure Object Storage Classic Subscriptions

Monitor the service

Check on the day-to-day operation of your service, monitor performance, and review important notifications.

Managing and Monitoring Oracle Cloud Services in Managing and Monitoring Oracle Cloud

Access the service

Access the service through the REST API or Java library interface.

Accessing Oracle Cloud Infrastructure Object Storage Classic

About Replication Policy for Your Object Storage Classic Instance

Not Oracle Cloud at Customer This topic does not apply to Oracle Cloud at Customer.

Topics

About Georeplication

If your account was created after March 2018, then once your Oracle Cloud Infrastructure Object Storage Classic subscription is activated, the replication policy for your instance is set to any, by default.

With the any policy set by default at the service instance level, you can now create a container and set any authorized replication policy to the container.

If your account was created before March 2018, then see About Replication Policy for Accounts Created Before March 2018.

Verifying the Replication Policy for Your Service Instance

Using the Web Console

To find out the replication policy that is set for your Oracle Cloud Infrastructure Object Storage Classic service instance, sign in to the web console. Expand Account Information. The details of your service instances are displayed in the Account Information pane. Look for the Georeplication Policy field.

Using the REST API

Send a HEAD request to view the replication policy details for your service instance. Look for the header X-Account-Meta-Policy-Georeplication in the output. See Getting Account Metadata.

Authenticating Access to Object Storage Classic

Oracle Cloud Infrastructure Object Storage Classic requires authentication when executing operations against your service instance. Authentication is provided to the service instance in the form of an authentication token.

You request an authentication token from the service by sending your user credentials to the service. Authentication tokens are temporary and expire in 30 minutes. This is a session time out and not an idle time out, which means that tokens expire even if they are in use. You must include your current authentication token with every operation against your service instance.

Topics:

Authenticating Access When Using the REST API

To request an authentication token, send a GET request to the authentication URL for your account. You’ll need your sign-in credentials to access your account and obtain the authentication URL to perform any operation on the resources.

Topics:

Obtaining the Authentication URL

  1. Sign in to your Oracle Cloud account.

    If you see Infrastructure Classic at the top of the page when you sign in to Oracle Cloud, then you are using the Infrastructure Classic Console to access your services and your subscription does not support access to the Infrastructure Console. See Signing In to Your Cloud Account in Getting Started with Oracle Cloud.

    If you can access the service from the Infrastructure Console, see Signing In to the Console in Oracle Cloud Infrastructure documentation.

  2. If you can access the service from the Infrastructure Console, perform the following steps to obtain the REST Endpoint URL:
    1. On the navigation menu, under More Oracle Cloud Services, point to Classic Infrastructure Services, and then click Storage Classic.

      The Oracle Cloud Infrastructure Object Storage Classic console is displayed.

    2. Click the Account tab.
    3. Note the Rest Endpoint URL which is displayed in the Rest Endpoint field.

      You can construct the authentication URL from the Rest Endpoint URL.

  3. If you can access the service from the Infrastructure Classic Console, perform the following steps to obtain the REST Endpoint URL and authentication URL:
    1. On the dashboard, look for Storage Classic.
    2. Select View Details from the Actions menu. Alternatively, click the Storage Classic link on the Dashboard page.

      On the resulting page, the details of your Oracle Cloud Infrastructure Object Storage Classic account are displayed.

    3. Note the authentication URL, which is displayed in the Auth V1 Endpoint field under the Additional Information section.

      For example: https://acme.storage.oraclecloud.com/auth/v1.0

    4. If the Auth V1 Endpoint field is not displayed, then you must construct the authentication URL from the REST Endpoint URL. Note the REST Endpoint URL, which is displayed in the REST Endpoint field under the Additional Information section.

  4. To construct the authentication URL when the authentication URL is not directly available in the web console:

    1. Let's consider that the REST Endpoint URL that you have noted is https://acme.storage.oraclecloud.com/v1/Storage-acme.
    2. Delete the following portion of the REST Endpoint URL:

      v1/Storage-acme

      The edited URL is: https://acme.storage.oraclecloud.com/

    3. Append the following to the edited URL:

      auth/v1.0

      The equivalent authentication URL would be https://acme.storage.oraclecloud.com/auth/v1.0.

Using Your Account Details

You’ll need your sign-in credentials to access your account and perform any operation on the resources.

When you sign up for the account, you’ll receive a Welcome mail with your sign-in credentials.

Make a note of your sign-in credentials, as shown in the following example:
Description of new_account_information_email-2017.jpg follows
Description of the illustration new_account_information_email-2017.jpg

If you don't have your Welcome email, ask your account administrator for your Oracle Cloud user name, password, and identity domain.

Note:

For traditional accounts, you can request Oracle Cloud to send the email to the administrator again. See Resending Welcome Email with Administrator Sign-in Credentials.

If your user credentials are not authenticated, the service returns an HTTP response with a status code of 401 and no authentication token is returned.

If the credentials are authenticated, the service either returns the currently active authentication token or generates a new authenticate token. Authentication tokens are returned as the value of the HTTP header X-Auth-Token in the HTTP response. Requesting an authentication token with credentials that already have an active authentication token will not extend the expiration time of the existing authentication token.

Requesting an Authentication Token

When you send the GET request to the authentication URL, include the user credentials in the following headers:

  • Depending on the REST Endpoint URL in your account:
    • If you use the REST Endpoint URL, then include the header X-Storage-User: Storage-account_name:userName
    • If you use the REST Endpoint URL (Permanent), then include the header X-Storage-User: Storage-GUID:userName

      Note:

      The REST Endpoint (Permanent) URL is displayed for the accounts created after November 2017.
  • X-Storage-Pass: password
  • http://account_name.storage.oraclecloud.com/auth/v1.0 is the authentication URL.

Note:

For traditional accounts, the identity domain name and the account name are the same.

cURL Command Examples

Sample Cloud account with the following details:
  • Account name: acme

    For traditional accounts, account name and identity domain name are the same.

  • REST Endpoint URL: https://acme.storage.oraclecloud.com/v1/Storage-acme
  • REST Endpoint (Permanent) URL: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365
  • Authentication URL: https://acme.storage.oraclecloud.com/auth/v1.0

cURL Command Examples – Requesting an Authentication Token:

  • Using the account name acme obtained from the REST Endpoint URL in the header X-Storage-User:
    curl -v -X GET \
     -H "X-Storage-User: Storage-acme:myUsername" \
     -H "X-Storage-Pass: myPassword" \
     https://acme.storage.oraclecloud.com/auth/v1.0

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

    > GET /auth/v1.0 HTTP/1.1
> Host: acme.storage.oraclecloud.com
> Accept: */*
> X-Storage-User: Storage-acme:myUsername
> X-Storage-Pass: myPassword

< HTTP/1.1 200 OK
< X-Storage-Url: https://acme.storage.oraclecloud.com/v1/Storage-acme
< X-Storage-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
< X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
< X-Trans-Id: txba4aa8f776164c33b7aa587554c29fb6
< Content-Length: 0
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: text/plain
< Content-Language: en
  • Using the GUID 7b16fede61e1417ab83eb52e06f0e365 obtained from the REST Endpoint (Permanent) URL in the header X-Storage-User:
    curl -v -X GET \
     -H "X-Storage-User: Storage-7b16fede61e1417ab83eb52e06f0e365:myUsername" \
     -H "X-Storage-Pass: myPassword" \
     https://acme.storage.oraclecloud.com/auth/v1.0

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

    > GET /auth/v1.0 HTTP/1.1
> Host: acme.storage.oraclecloud.com
> Accept: */*
> X-Storage-User: Storage-7b16fede61e1417ab83eb52e06f0e365:myUsername
> X-Storage-Pass: myPassword

< HTTP/1.1 200 OK
< X-Storage-Url: https://acme.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365
< X-Storage-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
< X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
< X-Trans-Id: txba4aa8f776164c33b7aa587554c29fb6
< Content-Length: 0
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: text/plain
< Content-Language: en

To use your authentication token, include it as the value of the X-Auth-Token HTTP header in every HTTP request to the service instance. If your authentication token is not valid, or has expired, the service returns an HTTP response with the status code 401 and the requested operation will fail. If the authentication token has expired, you must request a new token. If you are reading publicly accessible objects, you do not need to provide an authentication token in your HTTP request; anonymously accessible objects do not need an authentication token.

cURL Command Examples – Storing an Object in an Account Using an Authentication Token:

  • Using the REST Endpoint URL obtained from the REST Endpoint field: 
    curl -v -X PUT \
     -H "X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6" \
     -d "Hello, World!" \
     https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer/myObject

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

    > PUT /v1/Storage-acme/myContainer/myObject HTTP/1.1
> Host: acme.storage.oraclecloud.com
> Accept: */*
> X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
> Content-Length: 13
> Content-Type: application/x-www-form-urlencoded

< HTTP/1.1 201 Created
< Content-Length: 0
< Etag: 65a8e27d8879283831b664bd8b7f0ad4
< Content-Type: text/html; charset=UTF-8
< X-Trans-Id: tx287a1a8e33cc45e5a1431817e3e87621
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Language: en
  • 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 PUT \
     -H "X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6" \
     -d "Hello, World!" \
     https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer/myObject

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

    > PUT /v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer/myObject HTTP/1.1
> Host: storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com
> Accept: */*
> X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
> Content-Length: 13
> Content-Type: application/x-www-form-urlencoded

< HTTP/1.1 201 Created
< Content-Length: 0
< Etag: 65a8e27d8879283831b664bd8b7f0ad4
< Content-Type: text/html; charset=UTF-8
< X-Trans-Id: tx287a1a8e33cc45e5a1431817e3e87621
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Language: en

Authenticating Access When Using the Java Library

When using the Java library, you do not need to manually request and use an authentication token; the Java library will automatically request and use it.

The Java library will also try to request a new authentication token when the current authentication token expires.

When using the Java library, you must pass your user credentials to a CloudStorageConfig object. The CloudStorageConfig object is then passed to a CloudStorageFactory object and, upon successful authentication, ultimately returns a CloudStorage object. The CloudStorage object provides the methods for all supported functionality to the service instance.

Code Examples

Sample Cloud account with the following details:
  • Account name: acme

    For traditional accounts, account name and identity domain name are the same.

  • 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 following are examples of Java code for providing user credentials and creating an object. The values used in the examples are illustrative. While developing Java code to use Oracle Cloud Infrastructure Object Storage Classic, ensure that the code complies with the IT security standards and requirements of your organization.

  • Using the REST Endpoint URL obtained from the REST Endpoint field:
    CloudStorageConfig myConfig = new CloudStorageConfig();
myConfig.setServiceName("Storage-acme")
   .setUsername("john.doe@example.com")
   .setPassword("Password".toCharArray())
   .setServiceUrl("https://acme.storage.oraclecloud.com");
CloudStorage myConnection = CloudStorageFactory.getStorage(myConfig);
FileInputStream fis = new FileInputStream("hello_world.txt");
myConnection.storeObject("MyContainer", "hello_world.txt", "text/plain", fis);
  • 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.

    CloudStorageConfig myConfig = new CloudStorageConfig();
myConfig.setServiceName("Storage-7b16fede61e1417ab83eb52e06f0e365")
   .setUsername("john.doe@example.com ")
   .setPassword("Password".toCharArray())
   .setServiceUrl("https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com");
CloudStorage myConnection = CloudStorageFactory.getStorage(myConfig);
FileInputStream fis = new FileInputStream("hello_world.txt");
myConnection.storeObject("MyContainer", "hello_world.txt", "text/plain", fis);
To identify the service URL and service name (for the setServiceName and setServiceUrl methods in this code example) of your Oracle Cloud Infrastructure Object Storage Classic instance:
  1. Sign in to your Oracle Cloud account.

    If you see Infrastructure Classic at the top of the page when you sign in to Oracle Cloud, then you are using the Infrastructure Classic Console to access your services and your subscription does not support access to the Infrastructure Console. See Signing In to Your Cloud Account in Getting Started with Oracle Cloud.

    If you can access the service from the Infrastructure Console, see Signing In to the Console in Oracle Cloud Infrastructure documentation.

  2. If you can access the service from the Infrastructure Console, perform the following steps to obtain the REST Endpoint URL:
    1. On the navigation menu, under More Oracle Cloud Services, point to Classic Infrastructure Services, and then click Storage Classic.
      The Oracle Cloud Infrastructure Object Storage Classic console is displayed.
    2. Click the Account tab.
    3. Note the Rest Endpoint URL which is displayed in the Rest Endpoint field.
  3. If you can access the service from the Infrastructure Classic Console, perform the following steps to obtain the REST Endpoint URL:
    1. On the Dashboard, look for Storage Classic.
    2. Select View Details from the Actions menu. Alternatively, click the Storage Classic link on the Dashboard.

      On the resulting page, the details of your Oracle Cloud Infrastructure Object Storage Classic account are displayed.

    3. Note the REST Endpoint URL, which is displayed in the REST Endpoint field in the Additional Information section. For example: https://acme.storage.oraclecloud.com/v1/Storage-acme.
  4. You can identify the value for the service URL and service name of your Oracle Cloud Infrastructure Object Storage Classic instance from the REST Endpoint URL.

    For example: https://acme.storage.oraclecloud.com/v1/Storage-acme is the REST Endpoint URL.

    In this example, the following are the service URL and name:

    • Service URL: https://acme.storage.oraclecloud.com

    • Service Name: Storage-acme