Managing Objects

In the Oracle Cloud Infrastructure Object Storage service, an object is a file or unstructured data you upload to a bucket within a compartment  within an Object Storage namespace. The object can be any type of data, for example, multimedia files, data backups, static web content, or logs. You can store objects that are up to 10 TiB. Objects are processed as a single entity. You can't edit or append data to an object, but you can replace the entire object.

This topic describes how to manage objects within a single bucket. For information on copying an object to another bucket, see Copying Objects.

You might also be interested in exploring an Object Storage feature that retains previous versions of objects. Among other things, object versioning protects objects from accidental or malicious overwrite or deletion. For more information, see Using Object Versioning.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

If you're new to policies, see Getting Started with Policies and Common Policies.

For administrators:

Pre-Authenticated Requests

Pre-authenticated requests provide a way to let users access a bucket or object without having their own credentials. For example, you can create a request that lets a user upload backups to a bucket without owning API keys. See Using Pre-Authenticated Requests for details.

Object Names

Unlike other resources, objects do not have Oracle Cloud Identifiers (OCIDs). Instead, users define an object name when they upload an object.

Use the following guidelines when naming an object:

  • Use from 1 to 1024 characters.
  • Valid characters are letters (upper or lower case), numbers, and characters other than line feed, carriage return, and NULL.
    Important

    Bucket names and object names are case-sensitive. Object Storage handles q3-field-assets.xslx and Q3-Field-Assets.XSLX as separate objects.
  • Use only Unicode characters for which the UTF-8 encoding does not exceed 1024 bytes. Clients are responsible for URL-encoding characters.
  • Do not include confidential information.
  • Make the name unique within the bucket. Do not use the name of an existing object within the bucket when naming an object unless you intend to overwrite the existing object with the contents of the new or renamed object.
Tip

Object names can include one or more forward slash (/) characters in the name. See Object Naming Using Prefixes and Hierarchies for more information on using the forward slash in object names to create hierarchies.

Object Naming Using Prefixes and Hierarchies

Within an Object Storage namespace, buckets and objects exist in a flat hierarchy, but you can simulate a directory structure using a prefix string that includes the forward slash (/) to add hierarchy to an object name. Doing so lets you list one directory at a time, which is helpful when navigating a large set of objects.

For example:

marathon/finish_line.jpg
marathon/participants/p_21.jpg	

If you added hierarchy to object names, you can use the CLI or API to perform bulk downloads and bulk deletes of all objects at a specified level of the hierarchy. Bulk downloads and deletes at a specified level of the hierarchy do not affect objects in any level above.

When naming objects, you can also use prefix strings without a delimiter. No delimiters would allow certain bulk operations in the CL or API to match on the prefix portion of the object name. For example, in the object names below, the string gloves_27_ can serve as a prefix for matching purposes when performing bulk downloads or deletions:

gloves_27_dark_green.jpg
gloves_27_light_blue.jpg	

When you perform bulk uploads with the CLI or API, you can also prepend a prefix string to the names of the files you are uploading.

Optional Response Headers and Metadata

When you upload objects, you can provide optional response headers and user-defined metadata. Response headers are HTTP headers sent from Object Storage to Object Storage clients when objects are downloaded. User-defined metadata are name-value pairs stored with an object. You can use the Console, REST API, or CLI to provide these optional attributes.

Important

No validation is performed on the response headers or metadata you provide.

You can specify values for the following response headers:

  • Content-Disposition

    Defines presentation only information for the object. Specifying values for this header has no effect on Object Storage behavior. Programs that read the object determine what to do based on the value provided. For example, you could use this header to let users download objects with custom file names in a browser:

    attachment; filename="fname.ext"

    See https://tools.ietf.org/html/rfc2616#section-19.5.1 for more information.

  • Cache-Control

    Defines the caching behavior for the object. Specifying values for this header has no effect on Object Storage behavior. Programs that read the object determine what to do based on the value provided. For example, you could use this header to identify objects that require caching restrictions:

    no-cache, no-store

    See https://tools.ietf.org/html/rfc2616#section-14.9 for more information.

You specify user-defined metadata in the form of name-value pairs. User-defined metadata names are stored and returned to Object Storage clients with the mandatory prefix of opc-meta-.

Object Lifecycle Management

Using Object Lifecycle Management feature, you can automatically manage the archiving and deletion of objects according to a pre-defined schedule. See Using Object Lifecycle Management for information on this feature.

Multipart Uploading and Downloading

The Oracle Cloud Infrastructure Object Storage service supports multipart uploading and downloading for objects.

Monitoring Resources

You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure resources by using metrics, alarms, and notifications. For more information, see Monitoring Overview and Notifications Overview.

For more information about monitoring objects, see Object Storage Metrics.

Creating Automation for Objects Using the Events Service

You can create automation based on state changes for your Oracle Cloud Infrastructure resources by using event types, rules, and actions. For more information, see Overview of Events.
Events for objects are handled differently than other resources. Objects do not emit events by default. Use the Console, CLI, or API to enable a bucket to emit events for object state changes. You can enable events for object state changes during or after bucket creation.

Using Storage Gateway to Upload and Download Objects

Storage Gateway is another way you can upload objects to and download objects from Oracle Cloud Infrastructure Object Storage.

Storage Gateway is installed in an Oracle Cloud Infrastructure compute instance or as a Linux Docker instance on one or more hosts in your on-premises data center. Applications store and retrieve objects from Oracle Cloud Infrastructure Object Storage through file systems that you create in Storage Gateway. Storage Gateway exposes an NFS mount point that can be mounted to any host that supports an NFSv4 client. The Storage Gateway mount point maps to an Object Storage bucket to upload and download objects.

See Overview of Storage Gateway for details.

Using the Console

To upload objects to a bucket

The Console uses multipart uploads to upload objects larger than 64 MiB.

Tip

If your objects are larger than 64 MiB and uploaded using multipart uploads, you need OBJECT_CREATE and OBJECT_OVERWRITE permissions.

See Using Multipart Uploads and Details for Object Storage, Archive Storage, and Data Transfer for details.

  1. From the Object Storage Details screen, click the bucket name to view its details.

  2. Click Objects under Resources.
  3. In the Objects table, click Upload Objects.
  4. Optionally, specify an Object Name Prefix. If provided, this prefix is prepended to each one of the files you upload. The prefix lets you simulate hierarchy and perform bulk operations. See Object Naming Using Prefixes and Hierarchies for details.
  5. In the Upload Objects dialog box, select the objects that you want to upload in one of two ways:
    • Drag and drop one or more files from your computer.
    • Click the select files link and use the File Upload dialog box.

    The files you select to upload are displayed in a list. If you decide that you do not want to upload a particular file, click the X to the right of the file name.

    If the files you select to upload are already stored in the bucket with the same name, the Console displays messages warning you of an overwrite.

  6. To specify values for optional response headers and metadata to be displayed in Object Details, click Show Optional Response Headers and Metadata.

    1. Select the attribute Type that you are adding.
    2. To add a Response Header, select the Name and enter a Value.
    3. To add Metadata, enter the Name and Value.
    4. To add attributes, click + Add More Headers or Metadata.
  7. Click Upload Objects.

    The selected objects are uploaded and displayed in the list of objects in the bucket.

To download an object from a bucket
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment that contains the bucket that contains your object.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

    A list of objects in the bucket is displayed.

  5. For the object you want to download, click the Actions icon (three dots), and then click Download.

To view object details
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment that contains the bucket that contains your object.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

    A list of objects in the bucket is displayed.

  5. Choose the object for which you want details.

  6. Click the Actions icon (three dots), and then click View Object Details. Object details include:

    • Basic Information
    • Response Headers
    • Metadata
  7. Optionally, click Download to download the selected object.
To rename an object
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment that contains the bucket that contains your object.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

    A list of objects in the bucket is displayed.

  5. For the object you want to rename, click the Actions icon (three dots), and then click Rename.

  6. In the Rename Object dialog box, provide the new name for the object and an optional delimited directory structure prefix. For example, p_94.jpg or /marathon/participants/p_94.jpg.

    Avoid entering confidential information in the object name.

    Warning

    Buckets cannot store two objects that use identical names (case-sensitive). If you choose to rename an object using the name of another object in the same bucket, the object that originally used the name is overwritten.
  7. Click Save Changes.
To restore objects from Archive Storage

Depending on the size of the object, it can take at most an hour to restore an object from Archive Storage. You cannot download an item until the item is fully restored.

Tip

You need OBJECT_RESTORE permissions to restore Archive Storage objects.
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment your bucket is in.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

    A list of objects in the bucket is displayed.

  5. To restore a single object, click the Actions icon (three dots) to the right of the object you want to restore, and then click Restore. To restore multiple objects, select the check boxes to the left of each object you want to restore, then click Restore.

  6. Optionally, specify the Time Available for Download in Hours.

    By default, you have 24 hours to download an object after restoration. However you can alternatively specify a download time of from 1 to 240 hours. You can find out how much download time is remaining by looking at Available for Download in object Details or by looking at the Actions icon (three dots) menu to the right of Download. Refresh the browser to obtain up-to-date remaining download time information.

    After the allotted download time expires, the object returns to Archive Storage.

  7. Click Restore Objects.

    Error messages are generated if there is a problem with restoring the selected objects. You can optionally click Retry failed restore option.

To check the status of an Archive Storage object restoration
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment your bucket is in.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

    A list of objects in the bucket is displayed.

  5. Click the Actions icon (three dots) to the right of the object you want to check the restoration or download status of, then click Details.

  6. Check the Status.

    Status displays one of the following:

    • Archived
    • Restoring
    • Restored
To re-encrypt an object
Tip

You need OBJECT_READ and OBJECT_OVERWRITE permissions to re-encrypt an object.

To encrypt and decrypt an object's data encryption keys with a different master encryption key, you can re-encrypt the object. When re-encrypting an object, you can choose either a different key from the one assigned to the bucket or the most recent version of the key assigned to the bucket. Until you explicitly re-encrypt an object, the key version associated with the bucket (when the object was inserted into the bucket) continues to decrypt all the object's data encryption keys.

You can re-encrypt an object's data encryption keys with a key managed by Oracle, a key that you created and control through a vault that you manage, or a customer-provided encryption key (SSE-C).

Note

If you use server-side encryption with customer-provided keys (SSE-C), you must use the CLI to provide the SSE-C key during the encryption or re-encryption process. Using the CLI, you can re-encrypt an object with a different SSE-C key, a key managed by Oracle, or a key that you manage through the Vault service. In the Console, you can only re-encrypt an object to use the latest version of the Oracle managed key assigned to the bucket or the latest version of a Vault key, whether or not that key version is currently assigned to the bucket.
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.

    A list of the buckets in the compartment you're viewing is displayed. If you don’t see the one you're looking for, verify that you’re viewing the correct compartment (select from the list on the left side of the page).

  2. Click the name of the bucket that has the object for which you want to re-encrypt data encryption keys.

  3. Under Objects, find the object that you want to re-encrypt. Click the Actions icon (three dots), and then click Re-encrypt.

  4. Do one of the following:

    • If the key assigned to the bucket is an Oracle managed key, either re-encrypt the object using the latest version of that key by clicking Use the key assigned to the bucket, or re-encrypt the object using a key in a vault by clicking Use a customer-managed key and choosing a key from a compartment and vault that you have access to.
    • If the key assigned to the bucket is a key in a vault, either re-encrypt the object using the latest version of that key by clicking Use the key assigned to the bucket, or re-encrypt the object using a different Vault key by clicking Use a different customer-managed key and choosing a key from a compartment and vault that you have access to.
  5. When you are ready, click Re-encrypt to re-encrypt all data encryption keys associated with the object.

If you receive an error, verify that you have the correct permissions. If you have access to the object, confirm that the object exists and has not recently been deleted. If you have permissions and the object exists, also confirm whether you encrypted the object with an SSE-C key. If you want to re-encrypt an object that you encrypted with an SSE-C key, you need to use the CLI to provide the SSE-C key to the Object Storage service for use during decryption and subsequent re-encryption, as appropriate. For more information, see the To re-encrypt an object CLI topic.

To delete objects from a bucket

You can permanently delete an object from a bucket. You cannot, however, recover a deleted object.

  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  2. Choose the compartment that contains the bucket that contains the object or objects you want to delete.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

    A list of objects in the bucket is displayed.

  5. To delete a single object, click the Actions icon (three dots) to the right of the object you want to delete, and then click Delete. To delete multiple objects, select the check boxes to the left of each object you want to delete, and then click Delete.

  6. Confirm when prompted.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

Note

The examples in this section use the full syntax for all parameters, for example --namespace and --bucketname. Sometimes, there are shortened parameter terms that you can use instead of the full ones, for example -ns and -bn. See the CLI online help for instances of a shortened parameter associated with a command.
To list objects in a bucket
oci os object list --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:

oci os object list --namespace MyNamespace --bucket-name MyBucket
{
  "data": [
    {
      "md5": "1B2M2Y8AsgTpgAmY7PhCfg==",
      "name": "MyFile.txt",
      "size": 0,
      "time-created": "2019-11-20T04:37:29.857000+00:00"
    },
    {"md5": "6GxlLP9fa71HhVnpLNJ+DQ==",
      "name": "logFile.log",
      "size": 26916,
      "time-created": "2019-11-20T04:31:39.321000+00:00"
    }
  ],
  "prefixes": []
}
To get object details
oci os object head --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name>

For example:

oci os object head --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt
{
  "accept-ranges": "bytes",
  "access-control-allow-credentials": "true",
  "access-control-allow-methods": "POST,PUT,GET,HEAD,DELETE,OPTIONS",
  "access-control-allow-origin": "*",
  "access-control-expose-headers": "accept-ranges,access-control-allow-credentials,access-control-allow-methods,access-control-allow-origin,content-length,content-md5,content-type,etag,last-modified,opc-client-info,opc-client-request-id,opc-request-id,x-api-id",
  "connection": "keep-alive",
  "content-length": "0",
  "content-md5": "1B2M2Y8AsgTpgAmY7PhCfg==",
  "content-type": "application/octet-stream",
  "date": "Wed, 20 Nov 2019 04:47:26 GMT",
  "etag": "3504606b-8412-4b5d-924a-aeaeacf1df1e",
  "last-modified": "Wed, 20 Nov 2019 04:37:29 GMT",
  "opc-client-request-id": "161EF2FCE08745149C493F8F05C7273D",
  "opc-request-id": "phx-1:9UqRVsQYNvmunCHEJMlOCO9oNSHJhP9WYjCif1E6WNUKXecesnHz7rvD-Klzgy0C",
  "x-api-id": "native"
}

If the object resides in an Archive tier bucket, the output also includes archival-state.

To upload an object to a bucket
oci os object put --namespace <object_storage_namespace> --bucket-name <bucket_name> --file <file_location> --name <object_name> --no-multipart

<file_location> is the source directory path of the object being uploaded, such as C:\workspace\Uploads\MyFile.txt or /home/user/Documents/Uploads/MyFile.txt.

<object_name> is the name of the uploaded object excluding the path. This parameter is required if the object is being read from STDIN. If you want to use the filename as the uploaded object's name (if not being read from STDIN), you can omit the --name option. The resulting object name does not include the path information (for example, C:\workspace\Uploads\), just the actual file name by itself (MyFile.txt).

An object can be uploaded as a single part or as multiple parts. Here we describe a single part upload using the --no-multipartoption. For detailed information on multipart uploads, see Using Multipart Uploads.

For example:

oci os object put --namespace MyNamespace --bucket-name MyBucket --file C:\workspace\Uploads\MyFile.txt --name MyFile.txt --no-multipart
{
	"etag": "3504606b-8412-4b5d-924a-aeaeacf1df1e",
	"last-modified": "Wed, 20 Nov 2019 04:37:29 GMT",
	"opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
}

If you omit the --name parameter, the command is:

oci os object put --namespace MyNamespace --bucket-name MyBucket --file C:\workspace\Uploads\MyFile.txt --no-multipart
{
	"etag": "3504606b-8412-4b5d-924a-aeaeacf1df1e",
	"last-modified": "Wed, 20 Nov 2019 04:37:29 GMT",
	"opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
}

To add optional response headers, use one or more of the following options:

  • --cache-control
  • --content-disposition
  • --content-encoding
  • --content-language
  • --content-disposition
  • --content-type

For more information about attributes that you can add when you upload an object, see Optional Response Headers and Metadata. For more details about these headers, see the Command Line Reference.

For example:

oci os object put --namespace MyNamespace --bucket-name MyBucket --file C:\workspace\MyFile --cache-control no-cache --no-multipart

To add custom metadata key-value pairs, use the --metadata option:

oci os object put -ns <object_storage_namespace> -bn <bucket_name> --file <file_location> --name <object_name>  --metadata <json_formatted_key-value_pairs> --no-multipart

<JSON-formatted_key-value_pair> is a key-value pair input as valid formatted JSON. See Passing Complex Input and Using a JSON File for Complex Input for more information about JSON formatting.

For example:

oci os object put --namespace MyNamespace --bucket-name MyBucket --file C:\workspace\MyFile.txt --metadata '{"Department": "Finance"}' --no-multipart
{
  "etag": "3504606b-8412-4b5d-924a-aeaeacf1df1e",
  "last-modified": "Wed, 20 Nov 2019 04:37:29 GMT",
  "opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
}
To bulk upload objects to a bucket
oci os object bulk-upload --namespace <object_storage_namespace> --bucket-name <bucket_name> --src-dir <source_directory_location> --no-multipart

<source_directory_location> is the upload directory path, such as C:\workspace\Upload\ or /home/user/Documents/Upload. If your source directory has subdirectories, the subdirectory names are prepended to the names of the files stored in those subdirectories, delimited with a forward slash (/) character. For example, if a file named maple.jpg is stored in the subdirectory trees, when the file is uploaded, Object Storage assigns the name trees/maple.jpg to the resulting object.

For example:

oci os object bulk-upload --namespace MyNamespace --bucket-name MyBucket --src-dir C:\workspace\Files --no-multipart
Uploaded logFile.log [####################################] 100%
Uploaded MyFile.txt [####################################] 100%

{
  "skipped-objects": [],
  "upload-failures": {},
  "uploaded-objects": {
    "MyFile.txt": {
      "etag": "7ba793ce-a341-4c56-9baf-61ca2c56ad50",
      "last-modified": "Thu, 21 Nov 2019 18:31:09 GMT",
      "opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
  },
    "logFile.log": {
      "etag": "6efa58a6-a723-4696-a31f-3c5099adbec4",
      "last-modified": "Thu, 21 Nov 2019 18:31:09 GMT",
      "opc-content-md5": "6GxlLP9fa71HhVnpLNJ+DQ=="
    }
  }
}

To append a prefix string to the object names created by your uploads, use the --object-prefix option.

For example:

oci os object bulk-upload --namespace MyNamespace --bucket-name MyBucket --src-dir C:\workspace\Files --object-prefix /bicycling/gloves/ --no-multipart
				
Uploaded /bicycling/gloves/gloves_27_A.jpg [####################################] 100%
Uploaded /bicycling/gloves/gloves_31_A.jpg [####################################] 100%

{
  "skipped-objects": [],
  "upload-failures": {},
  "uploaded-objects": {
    "/bicycling/gloves/gloves_27_A.jpg": {
      "etag": "7ba793ce-a341-4c56-9baf-61ca2c56ad50",
      "last-modified": "Thu, 21 Nov 2019 18:35:09 GMT",
      "opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
  },
    "/bicycling/gloves/gloves_31_A.jpg": {
      "etag": "6efa58a6-a723-4696-a31f-3c5099adbec4",
      "last-modified": "Thu, 21 Nov 2019 18:35:09 GMT",
      "opc-content-md5": "6GxlLP9fa71HhVnpLNJ+DQ=="
    }
  }
}

To add custom metadata key-value pairs, use the --metadata <JSON_formatted_key-value_pairs> option.

<JSON-formatted_key-value_pair> is a key-value pair input as valid formatted JSON. See Passing Complex Input and Using a JSON File for Complex Input for information about JSON formatting.

For example:

oci os object bulk-upload --namespace MyNamespace --bucket-name MyBucket --src-dir C:\workspace\Files --no-multipart --metadata '{"Department": "Finance"}'
To download an object from a bucket
oci os object get --namespace <object_storage_namespace> --bucket-name<bucket_name> --name <object_name> --file <file_location>

<file_location> is the destination path for the file being downloaded, such as C:\workspace\Downloads\MyFile.txt or /home/user/Documents/Downloads/MyFile.txt.

The --name <object_name> parameter is required.

For example:

oci os object get --namespace MyNamespace --bucket-name MyBucket --file c:\workspace\Downloads\MyFile.txt --name MyFile.txt

No information is returned when you run the command. The file is downloaded to the specified destination.

To download an object using multipart download

Multipart object downloading is available using the byte-range request standard defined in RFC 7233, section 2.1.

oci os object get --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name> --file <file_location> --range bytes=<byte_range>

For example:

oci os object get --namespace MyNamespace --bucket-name MyBucket --name MyObject.mp4 --file c:\workspace\Downloads\MyObject.mp4 --range bytes=0-499
To bulk download all objects within a bucket
oci os object bulk-download --namespace <object_storage_namespace> --bucket-name <bucket_name> --download-dir <download_directory_location>

<download_directory_location> is the destination path for the objects being downloaded, such as C:\workspace\Downloads\ or /home/user/Documents/Downloads/. If the directory does not exist, Object Storage creates the directory when the command is run.

For example:


oci os object bulk-download --namespace MyNamespace --bucket-name MyBucket --download-dir c:\workspace\Downloads

Downloaded MyFile.txt [####################################] 100%
Downloaded logFile.log [####################################] 100%

{
  "download-failures": {},
  "skipped-objects": []
}

For a complete list of object bulk download options, see the Command Line Reference.

To bulk download objects by object name prefix string

If you have named your objects with prefix strings, you can bulk download objects in a bucket that match a specified prefix string.

oci os object bulk-download --namespace <object_storage_namespace> --bucket-name <bucket_name> --download-dir <download_directory_location> --prefix <prefix_string>

<download_directory_location> is the destination path for the objects being downloaded, such as C:\workspace\Downloads\ or /home/user/Documents/Downloads/. If the directory does not exist, Object Storage creates the directory when the command is run.

For example:

oci os object bulk-download --namespace MyNamespace --bucket-name MyBucket --download-dir c:\workspace\Downloads --prefix gloves_27

In the example above, an object named gloves_27_A.jpg is downloaded, while an object named gloves_31_A.jpg is not downloaded.

If you named your objects so that they exist in Object Storage in a hierarchy, you can download objects at a specified level and below. Specify the prefix that matches the level of your choosing:

oci os object bulk-download --namespace <object_storage_namespace> --bucket-name <bucket_name> --download-dir <download_directory_location> --prefix <level_1/level_2/>

The preceding command downloads the following objects:

  • <level_1/level_2/object_name>
  • <level_1/level_2/level_3/object_name>
  • <level_1/level_2/level_3/level_4/object_name>

To download only those objects at a given hierarchy level (and not objects in levels above or below), see To bulk download objects at a specified hierarchy level.

To bulk download objects at a specified hierarchy level

If you named your objects so that they exist in Object Storage in a hierarchy, you can bulk download all objects at a specified hierarchy level.

oci os object bulk-download --namespace <object_storage_namespace> --bucket-name <bucket_name> --download-dir <download_directory_location> --prefix <level_1/level_2/> --delimiter /

<download_directory_location> is the destination path for the objects being downloaded, such as C:\workspace\Downloads\ or /home/user/Documents/Downloads/. If the directory does not exist, Object Storage creates the directory when the command is run.

Note

Currently, only the forward slash (/) is the supported delimiter for the --delimiter option.

The preceding command downloads objects only at <level_2> of the hierarchy. For example, the following object is downloaded:

<level_1/level_2/object_name>

The preceding command does not download objects in levels above or below <level_2>. For example, the preceding command does not download the following objects:

  • <level_1/object_name>
  • <level_1/level_2/level_3/object_name>
  • <level_1/level_2/level_3/level_4/object_name>

To download objects at a given hierarchy level along with all objects in the hierarchy sublevels, see To bulk download objects by object name prefix string.

To rename an object
oci os object rename --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_original_name> --new-name <object_new_name>

For example:

oci os object rename --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --new-name MyRenamedFile.txt

{
  "etag": "3504606b-8412-4b5d-924a-aeaeacf1df1e"
}

To make the rename operation dependent on the object having a specific entity tag, use the --src-obj-if-match-e-tag option.

For example:

oci os object rename rename --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --new-name MyRenamedFile.txt --src-obj-if-match-e-tag 6672BECB67CCFFBCE0530292F20ZBACE

For rename operations where you intend to overwrite one object in a bucket with another, you can make the renaming dependent on having a specific entity tag. To do so, use the --new-obj-if-match-e-tag option.

For example:

oci os object rename rename --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --new-name MyRenamedFile.txt --new-obj-if-match-e-tag 6672BECB67CCFFBCE0530292F20ZBACE

When renaming an object, you can prevent the system from overwriting another object in the same bucket by using the --new-obj-if-none-match-e-tag * option. This option prevents the renaming operation from completing if an object exists with the --new-name value specified and the same entity tag of the source object.

For example:

oci os object rename rename --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --new-name MyRenamedFile.txt --new-obj-if-none-match-e-tag *
To restore an Archive Storage tier object
Tip

You need OBJECT_RESTORE permissions to restore Archive Storage objects.
oci os object restore --namespace <object_storage_namespace> --bucket-name <archive_bucket_name> --name <archived_object_name> [--hours <#_of_hours>]

By default, you have 24 hours to download an object after restoration. However, you can optionally specify --hours with an integer value of download time of from 1 to 240 hours.

To check the status of an Archive Storage object restoration
oci os object restore-status --namespace <object_storage_namespace> --bucket-name <archive_bucket_name> --name <archived_object_name>
To re-encrypt an object
Tip

You need OBJECT_READ and OBJECT_OVERWRITE permissions to re-encrypt an object.

You can re-encrypt the data encryption keys that encrypt an object. You can do so by re-encrypting the object's data encryption keys with the latest version of the master encryption key assigned to the bucket, whether it's an Oracle managed key or a key in a vault that you manage. You can also re-encrypt the object's data encryption keys with a different key in a vault or a different SSE-C key. If you use SSE-C keys, you must provide the SSE-C key during the object decryption and subsequent re-encryption process, as appropriate.

You can re-encrypt an object's data encryption keys with the latest key version of the key assigned to the bucket.

oci os object reencrypt --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name>

For example:

oci os object reencrypt --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt

The object's data encryption keys are re-encrypted with no further information returned.

If the object's data encryption keys are currently encrypted with an SSE-C key, you must also provide the name of the file that contains the base64-encoded string of the AES-256 source encryption key to first decrypt the object.

oci os object reencrypt --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name> --source-encryption-key-file <name_of_file_containing_base64-encoded_AES-256_key>

For example:

oci os object reencrypt --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --source-encryption-key-file MySSE-CKey

You can re-encrypt an object's data encryption keys with a specific Vault key.

oci os object reencrypt --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name> --kms-key-id <key_OCID>

For example:

oci os object reencrypt --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq

Again, if the key is currently encrypted with an SSE-C key, you must also provide the name of the file that contains the base64-encoded string of the AES-256 source encryption key to first decrypt the object.

oci os object reencrypt --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name> --source-encryption-key-file <name_of_file_containing_base64-encoded_AES-256_key> --kms-key-id <key_OCID>

For example:

oci os object reencrypt --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --source-encryption-key-file MySSE-CKey --kms-key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq

You can re-encrypt an object's data encryption keys with an SSE-C key .

oci os object reencrypt --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name> --encryption-key-file <name_of_file_containing_base64-encoded_AES-256_key>

For example:

oci os object reencrypt --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --encryption-key-file MySSE-CKey

If the object is currently encrypted with an SSE-C key, and you want to encrypt the object's data encryption keys with a different SSE-C key, provide the file name of each key.

oci os object reencrypt --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name> --source-encryption-key-file <name_of_file_containing_base64-encoded_AES-256_key_currently_assigned> --encryption-key-file <name_of_file_containing_base64-encoded_AES-256_key_desired>

For example:

oci os object reencrypt --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt --source-encryption-key-file MySSE-CKey --encryption-key-file MyNewSSE-CKey
To delete an object

You can permanently delete an object.

oci os object delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <object_name>

For example:

oci os object delete --namespace MyNamespace --bucket-name MyBucket --name MyFile.txt

Are you sure you want to delete this resource? [y/N]: y

The object is deleted with no further information returned.

To bulk delete all objects within a bucket
oci os object bulk-delete --namespace <object_storage_namespace> --bucket-name <bucket_name>

For example:

oci os object bulk-delete --namespace MyNamespace --bucket-name MyBucket

WARNING: This command will delete 2 objects. Are you sure you wish to continue? [y/N]:

Deleted MyRenamedFile.txt [####################################] 100%
Deleted logFile.log [####################################] 100%

{
  "delete-failures": {},
  "deleted-objects": [
    "MyRenamedFile.txt",
    "logFile.log"
  ]
}

To see a list of the files impacted by a bulk delete command without actually deleting the files, use the --dry-run option.

For example:

oci os object bulk-delete --namespace MyNamespace --bucket-name MyBucket --dry-run
{
  "delete-failures": {},
  "deleted-objects": [
    "MyFile.txt",
    "logFile.log"
  ]
}
To bulk delete objects by object name prefix string

If you named your objects with prefix strings, you can bulk delete objects in a given bucket by providing a prefix to match.

oci os object bulk-delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --prefix <prefix_string>

For example:

oci os object bulk-delete --namespace MyNamespace --bucket-name MyBucket --prefix gloves_A

The preceding command deletes the objects gloves_27_A.jpg and gloves_31_A.jpg, but does not delete the object shoes_1.jpg.

If you named your objects so that they exist in a hierarchy, specify a prefix to match to bulk delete objects at a given level and below.

oci os object bulk-delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --prefix <level_1/level_2/>

The preceding command deletes the following files:

  • <level_1/level_2/object_name>
  • <level_1/level_2/level_3/object_name>
  • <level_1/level_2/level_3/level_4/object_name>

To delete only those objects at a given hierarchy level (and not objects in levels above or below), see To bulk delete objects at a specified hierarchy level.

To see a list of the files impacted by a bulk delete command without actually deleting the files, use the --dry-run option.

To bulk delete objects at a specified hierarchy level

If you named your objects so that they exist in a hierarchy, you can bulk delete only those objects at a given hierarchy level (and not objects in levels above or below).

oci os object bulk-delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --prefix <level_1/level_2/> --delimiter /
Note

Currently, only the forward slash (/) is the supported delimiter for the --delimiter option.

The preceding bulk delete command deletes the following object:

<level_1/level_2/>object_name

The preceding command does not bulk delete objects in levels above or below <level_2>. For example, the command would not delete the following objects:

  • <level_2/object_name>
  • <level_1/level_2/level_3/object_name>
  • <level_1/level_2/level_3/level_4/object_name>

To delete objects at a given hierarchy level along with all objects in the hierarchy sublevels, see To bulk delete objects by object name prefix string.

To see a list of the files impacted by a bulk delete command without actually deleting the files, use the --dry-run option.

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Object Storage prepends the Object Storage namespace string and bucket name to the object name when constructing a URL for use with the API. Everything :
/n/<object_storage_namespace>/b/<bucket>/o/<object_name>

The object name is everything after the /o/, which could include hierarchy levels and prefix strings.

Use the following API operations to manage objects: