Accessing Oracle Storage Cloud Service

You can access Oracle Storage Cloud Service using either the RESTful web service API or the Java library.

Topics:

Interfaces to Oracle Storage Cloud Service

The following table summarizes the interfaces to Oracle Storage Cloud Service.

Interface Description More Information

RESTful Web Service API

Oracle Storage Cloud Service provides REST APIs based on OpenStack Swift. The following major additions have been made:

  • Centralized identity management across Oracle Cloud

  • Centralized reporting of usage metrics

For information about the REST URLs for Oracle Storage Cloud Service resources, see About REST URLs for Oracle Storage Cloud Service Resources.

Oracle Storage Cloud Service does not support the following OpenStack Swift features:

  • Object versioning

  • Static website support

  • Cross-origin resource sharing (CORS) support

  • Static large objects

  • Container synchronization

  • Temporary URLs

  • Form post

  • Account ACLs

  • Rate limits

The RESTful web service API is available only over HTTPS.

Managing Containers in Oracle Storage Cloud Service

Managing Objects in Oracle Storage Cloud Service

API Operations for Storage Services in OpenStack Object Storage Service API Reference

Java Library

A Java library that wraps the RESTful web service API.

Most major functionality of the RESTful web service API is available, but not all. For more information about the operations supported by RESTful API and Java library interfaces, see Operations Supported by RESTful API and Java Library

The Java library also provides client-side encryption utilities.

It can be downloaded from Oracle Technology Network.

Managing Containers in Oracle Storage Cloud Service

Managing Objects in Oracle Storage Cloud Service

Java API Reference for Oracle Storage Cloud Service

Tasks Supported by the RESTful API and Java Library Interfaces

Use the following table as a guide to select the interface to Oracle Storage Cloud Service:

Task RESTful API Java Library

Setting account metadata

Yes

No

Getting account metadata

Yes

No

Creating, deleting, and listing containers

Yes

Yes

Setting custom metadata for containers

Yes

Yes

Setting container ACLs

Yes

Yes

Setting container quotas

Yes

No

Creating, deleting, and listing objects

Yes

Yes

Bulk-creating and bulk-deleting objects

Yes

No

Downloading objects

Yes

Yes

Updating custom metadata for objects

Yes

Yes

Updating special metadata for objects

Yes

No

Copying objects

Yes

No

Encrypting objects

No

Yes

Accessing Oracle Storage Cloud Service Using the REST API

The REST API can be accessed from any application or programming platform that correctly and completely understands the Hypertext Transfer Protocol (HTTP) and has Internet connectivity. The REST API makes use of advanced facets of HTTP such as secure communication over HTTPS, HTTP headers, and specialized HTTP verbs (PUT, DELETE).

Some applications that meet these requirements are:

  • cURL

  • Web browsers

    Support varies across vendors. Some browser plugins may be needed for full support.

Many programming platforms (Java, Ruby, Perl, PHP, .NET, and so on) also meet these requirements, although some may require the use of third party libraries for full support. See your programming platform's documentation for guidance.

About REST API URLs for Oracle Storage Cloud Service Resources

Accounts, containers, and objects in an Oracle Storage Cloud Service instance are represented as REST resources and are accessible through HTTP uniform resource locators (URLs).

URL for the Account

The URL for the account is also the REST API endpoint of the service instance. You can find the REST API endpoint in the Oracle Cloud My Services page, under the Additional Information section, in the Service REST Endpoint field.

The URL for the Oracle Storage Cloud Service REST API is in the following format:
  • Metered subscription: https://storage.dataCenterCode.oraclecloud.com/v1/Storage-identityDomainName

  • Nonmetered subscription: https://storage.dataCenterCode.oraclecloud.com/v1/serviceInstanceName-identityDomainName

In these URL formats,
  • identityDomainName is the identity domain in which the service instance is provisioned.

  • dataCenterCode is the identifier of the data center in which the service instance is provisioned.

  • serviceInstanceName is the customer-specified name of the service instance.

For example, for a service instance named myStorage2 that is provisioned in the myIdentity3 domain in the us2 data center, the REST API URLs would be:
  • Metered subscription: https://storage.us2.oraclecloud.com/v1/Storage-myIdentity3

  • Nonmetered subscription: https://storage.us2.oraclecloud.com/v1/myStorage2-myIdentity3

URLs for Containers

Containers are resources within an account.

For the sample REST API URL above for a metered subscription, the URL for a container named myContainer4 would be https://storage.us2.oraclecloud.com/v1/Storage–myIdentity3/myContainer4

URLs for Objects

Objects are resources within containers.

For the sample REST API URL above for a metered subscription, the URL for an object named myObject5 in the myContainer4 container would be https://storage.us2.oraclecloud.com/v1/Storage–myIdentity3/myContainer4/myObject5

Accessing Oracle Storage Cloud Service Using the Java Library

The Java library makes use of the REST API. So the Java library, too, requires Internet connectivity.

The Java library requires Java Runtime Environment (JRE) version 1.6 or later. The Java library has several runtime-dependent Java libraries, all of which are included with the downloadable Java SDK.

To use the Java library in your own Java applications:

  1. Download the Oracle Storage Cloud Service Java SDK from the Downloads page on OTN at: http://www.oracle.com/technetwork/topics/cloud/downloads/cloud-service-java-sdk-2121032.html
  2. Extract the Java library's classes and runtime dependencies somewhere onto your Java application's class path.
  3. Import the Java library's classes and interfaces into your Java application.
  4. Refer to Managing Containers in Oracle Storage Cloud Service and Managing Objects in Oracle Storage Cloud Service for details on how to use the Java library to access the service for your specific needs.

Authenticating Access to Oracle Storage Cloud Service

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

Authentication tokens are requested from the service by authenticating your user credentials with the service. All provisioned 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 following URL:

https://storage.dataCenterCode.oraclecloud.com/auth/v1.0

Include your user credentials in the following headers:

  • X-Storage-User

    • Syntax for metered subscriptions:

      X-Storage-User: Storage-identityDomainName:userName

    • Syntax for nonmetered subscriptions:

      X-Storage-User: serviceInstanceName-identityDomainName:userName

  • X-Storage-Pass: password

If your user credentials are not authenticated, the service will return an HTTP response with a status code of 401 and no authentication token will be returned. If your credentials are authenticated, the service will either return your currently active authentication token or generate a new authenticate token. Authentication tokens are returned as the value of the HTTP header X-Storage-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.

To use your authentication token, include it as the value of the X-Storage-Token HTTP header in every HTTP request to the service instance. If your authentication token is not valid, or has expired, the service will return an HTTP response with a status code of 401 and your requested operation will fail. If your 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.

Here’s an example of a cURL command for requesting an authentication token:

curl -v -X GET \
     -H 'X-Storage-User: myService-myIdentityDomain:myUsername' \
     -H 'X-Storage-Pass: myPassword' \
     https://storage.us2.oraclecloud.com/auth/v1.0

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

< HTTP/1.1 200 OK
< X-Storage-Url: https://storage.us2.oraclecloud.com/v1/myService-myIdentityDomain
< 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

Here’s an example of a cURL command for storing an object in an account using an authentication token:

curl -v -X PUT \
     -H 'X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6' \
     -d 'Hello, World!' \
     https://storage.us2.oraclecloud.com/v1/myService-myIdentityDomain/myContainer/myObject

> PUT /v1/myService-myIdentityDomain/myContainer/myObject HTTP/1.1
> Host: storage.us2.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 apply an authentication token; the Java library will automatically request and apply 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.

The following is an example of Java code for providing user credentials and creating an object. The values used in this example are illustrative. While developing Java code to use Oracle Storage Cloud Service, ensure that the code complies with the IT security standards and requirements of your organization.

CloudStorageConfig myConfig = new CloudStorageConfig();
 myConfig.setServiceName("myService-myIdentityDomain")
   .setUsername("myUsername")
   .setPassword("myPassword".toCharArray())
   .setServiceUrl("https://storage.us2.oraclecloud.com");
 CloudStorage myConnection = CloudStorageFactory.getStorage(myConfig);
 FileInputStream fis = new FileInputStream("hello_world.txt");
 myConnection.storeObject("MyContainer", "hello_world.txt", "text/plain", fis);