1 Getting Started with Object Storage Classic
This section describes how to get started with Oracle Cloud Infrastructure Object Storage Classic.
Topics:
- About Oracle Cloud Infrastructure Object Storage Classic
- Before You Begin with Oracle Cloud Infrastructure Object Storage Classic
- Workflow for Getting Started with Oracle Cloud Infrastructure Object Storage Classic
- How to Begin with Oracle Cloud Infrastructure Object Storage Classic Subscriptions
- About Replication Policy for Your Object Storage Classic Instance
- Accessing Oracle Cloud Infrastructure Object Storage Classic
- About Oracle Cloud Infrastructure Object Storage Classic Roles and Users
- About Access Control Lists
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:
Oracle Cloud Infrastructure Object Storage Classic does not support the following OpenStack Swift features:
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 |
|
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 |
|
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 |
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 |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
Uploading files to |
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
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
This topic does not apply to Oracle Cloud at Customer.
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
- 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.
- If you can access the service from the Infrastructure Console, perform the following steps to obtain the REST Endpoint URL:
- 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.
- Click the Account tab.
- Note the Rest Endpoint URL which is displayed in the Rest Endpoint field.
You can construct the authentication URL from the Rest Endpoint URL.
- On the navigation menu, under More Oracle Cloud Services, point to Classic Infrastructure Services, and then click Storage Classic.
- If you can access the service from the Infrastructure Classic Console, perform the following steps to obtain the REST Endpoint URL and authentication URL:
- On the dashboard, look for Storage Classic.
- 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.
- 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
- 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.
-
To construct the authentication URL when the authentication URL is not directly available in the web console:
- Let's consider that the REST Endpoint URL that you have noted is
https://acme.storage.oraclecloud.com/v1/Storage-acme
. - Delete the following portion of the REST Endpoint URL:
v1/Storage-acme
The edited URL is:
https://acme.storage.oraclecloud.com/
- Append the following to the edited URL:
auth/v1.0
The equivalent authentication URL would be
https://acme.storage.oraclecloud.com/auth/v1.0
.
- Let's consider that the REST Endpoint URL that you have noted is
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 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.
- If you use the REST Endpoint URL, then include the header
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
- 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 headerX-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 headerX-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
- 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);
setServiceName
and setServiceUrl
methods in this code example) of your Oracle Cloud Infrastructure Object Storage Classic instance: