Oracle Cloud Infrastructure Documentation

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 A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. 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 up to 10 TiB in size. 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.

Tip

The size of the object determines the appropriate management interface to use to upload objects to Oracle Cloud Infrastructure Object Storage:

  • You can use the Console to upload objects up to 2 GiB in size.
  • You can use the CLI or API to upload objects up to 10 TiB in size.
  • You can use the multipart upload API to upload objects larger than 100 MiB (recommended). See Using Multipart Uploads for details.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be given the required type of access in a An IAM document that specifies who has what type of access to your resources. It is used in different ways: to mean an individual statement written in the policy language; to mean a collection of statements in a single, named "policy" document (which has an Oracle Cloud ID (OCID) assigned to it); and to mean the overall body of policies your organization uses to control access to resources. 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 A collection of related resources that can be accessed only by certain groups that have been given permission by an administrator in your organization. you should work in.

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

Tip

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 linefeed, newline, and NULL.
  • 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.

Object Storage prepends the Object Storage namespace string and bucket name to the object name:

/n/<object_storage_namespace>/b/<bucket>/o/<object_name>

The object name is everything after the /o/.

For example: /n/ansh8lvru1zp/b/accessories/o/backpack_75.jpg

Tip

Object names can include one or more forward slash (/) characters in the name string that follows the /o/ delimiter. 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:

/n/ansh8tvru7zp/b/event_photos/o/marathon/finish_line.jpg

/n/ansh8tvru7zp/b/event_photos/o/marathon/participants/p_21.jpg

If you named your objects so that they exist in Object Storage as a hierarchy, you can use the Command Line Interface (CLI) to perform bulk downloads and bulk deletes of all objects at a specified level of the hierarchy, without affecting objects in levels above or below. In the example above, you can use the CLI to download or delete all objects at the marathon/ level without downloading or deleting objects at the marathon/participants/ sublevel.

When naming objects, you can also use prefix strings without a delimiter so that certain bulk operations can be performed in the CLI by matching 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:

/n/ansh8tvru7zp/b/apparel/o/gloves_27_dark_green.jpg
/n/ansh8tvru7zp/b/apparel/o/gloves_27_light_blue.jpg
        

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

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. For information on multipart uploading see the Using Multipart Uploads topic. This page includes links to API documentation for this functionality. For information on multipart downloading, see the CLI procedure To download an object using multipart download. For API documentation related to multipart downloading, see the GetObject API call and its range parameter.

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. Object-aware 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 an object to a bucket
To download an object from a bucket
To view object details
To rename an object
To restore an object from Archive Storage
To check the status of an Archive Storage object restoration
To delete an object from a bucket

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 CLI Help.

To list objects in a bucket
To get object details
To upload an object to a bucket
To bulk upload objects to a bucket
To download an object from a bucket
To download an object using multipart download
To bulk download all objects within a bucket
To bulk download objects by object name prefix string
To bulk download objects at a specified hierarchy level
To rename an object
To restore an Archive Storage tier object
To check the status of an Archive Storage object restoration
To delete an object
To bulk delete all objects within a bucket
To bulk delete objects by object name prefix string
To bulk delete objects at a specified hierarchy level

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.

Use the following operations to manage objects: