OBJECTSTORAGE

11.17 OBJECTSTORAGE

Use the OBJECTSTORAGE command to use the Object Storage Service API to manage objects, and related resources.

This command enables you to:

List objects in a bucket
Store an object in a bucket
Retrieve an object from a bucket
Delete an object from a bucket

The sub-commands are:

Set
Object

11.17.1 Set

Configures global options used for OCI Object Storage operations. This is used to avoid repeating required options for object sub command operations: GET, PUT, LIST, and DELETE.

Syntax

objectstorage  set {PARAMETERS}

Parameters

Parameter	Description
Required
`<global-option> {BUCKET-NAME\|NAMESPACE}`	Provides the option name to set as a default (for example, `BUCKET-NAME` or `NAMESPACE`).
`<value>`	Provides the required value to assign to the chosen global option.

Example

objectstorage set namespace ociNamespace

       objectstorage set bucket-name ociBucketName

       objectstorage object get -object-name someObject.txt -file
    /path/to/output.txt

11.17.2 Object

Manages an object in OCI Object Storage.

Syntax

objectstorage   object {SUBCOMMAND}

Sub-commands

Sub-command	Description
`GET`	Retrieves an object from the OCI Object Storage.
`PUT`	Uploads a resource to the OCI Object Storage.
`LIST`	Lists the objects contained in a bucket in OCI Object Storage.
`DELETE`	Deletes an object from the OCI Object Storage.

11.17.2.1 LIST

Lists the objects within a bucket in the OCI Object Storage.

Syntax

objectstorage list {OPTIONS}

Options

Option	Description
Optional
`-namespace\|-ns <namespace>`	Specifies the OCI `namespace`. Note: Omit this option if you previously specified `objectstorage set namespace <name>` by using the set sub-command.
`-bucket-name\|-bn <bucket-name>`	Specifies the OCI `bucket name` Note: Omit this option if you previously specified `objectstorage set bucket-name <name>` by using the set sub-command.
`-start <start>`	Specifies the string to use for matching against object names which are lexicographically greater than or equal to specified string.
`-end <end>`	Specifies the string to use for matching against object names which are lexicographically strictly less than this specified string.
`-prefix <prefix>`	Specifies the string to use for matching against the start of object names in a list query.
`-fields <fields>`	Specifies the string to include `size` (object size in bytes), `etag`, `md5`, `timeCreated` (object creation date and time), `timeModified` (object modification date and time), `storageTier` and `archivalState` fields. Specify the values as a comma-separated, case-insensitive list of those field names. For example: `name`,`etag`,`timeCreated`,`md5`,`timeModified`,`storageTier`,`archivalState`. Supported values are: `name` `size` `etag` `timeCreated` `md5` `timeModified` `storageTier` `archivalState`
`-limit <limit>`	Specifies the maximum number of results per page, or items to return in a paginated "List".
`-all <all> (false)`	Specifies a flag to indicate to return all object names within the bucket. Note: If you provide this option, then you cannot provide the `-limit <limit>` option.
`-client-request-id\|-cid <client-request-id>`	Specifies the client request ID to use for tracing.

11.17.2.2 GET

Retrieves an object from the OCI Object Storage.

Syntax

objectstorage get {OPTIONS}

Options

Option	Description
Required
`-object-name\|-on <object-name>`	Specifies the name of an OCI object within a bucket.
`-file\|-f <file>`	Specifies the location of the file to store the object's content.
Optional
`-etag\|-et <etag>`	Specifies the entity tag (`ETag`) to match with the `ETag` of an existing object. If the specified `ETag` matches the `ETag` of the existing object, then the object is downloaded.
`-avoid-etag-match\|-aem <avoid-etag-match>`	Specifies the entity tag ( `ETag`) to avoid matching while retrieving the objects. Retrieves the object only when `ETag` does not match.
`-client-request-id\|-cid <client-request-id>`	Specifies the client request ID to use for tracing.
`-namespace\|-ns <namespace>`	Specifies the OCI `namespace`. Note: Omit this option if you previously specified `objectstorage set namespace <name>` by using the set sub-command.
`-bucket-name\|-bn <bucket-name>`	Specifies the OCI `bucket name`. Note: Omit this option if you previously specified `objectstorage set bucket-name <name>` by using the set sub-command.

Examples

GET an OCI object to download to the file location:

objectstorage object get -namespace ociNamespace -bucket-name
    ociBucketName -object-name someObject.txt -etag
    a1111111-b222-c333-d444-e55555555555 -file /path/to/output.txt

GET an OCI object that matches the entity tag (ETag) and download to the file location:

 objectstorage object get -namespace ociNamespace -bucket-name
    ociBucketName -object-name someObject.txt -etag
    a1111111-b222-c333-d444-e55555555555 -file /path/to/output.txt

GET an OCI object that does not match the entity tag (ETag) and download to the file location:

objectstorage object get -namespace ociNamespace -bucket-name
    ociBucketName -object-name someObject.txt -avoid-etag-match
    a9999999-b888-c777-d444-e66666666666 -file /path/to/output.txt

11.17.2.3 PUT

Uploads an object to the OCI Object Storage.

Syntax

objectstorage put {OPTIONS}

Options

Option	Description
Required
`-file\|-f <file>`	Specifies the location of the file to store the object's content.
Optional
`-namespace\|-ns <namespace>`	Specifies the OCI `namespace`. Note: Omit this option if you previously specified `objectstorage set namespace <name>` by using the set sub-command.
`-bucket-name\|-bn <bucket-name>`	Specifies the OCI `bucket name` Note: Omit this option if you previously specified `objectstorage set bucket-name <name>` by using the set sub-command.
`-cache-control\|-cc <cache-control>`	Specifies cache-control HTTP header that defines the caching behavior.
`-checksum-algorithm\|-csa <checksum-algorithm> {CRC32C\|SHA256\|SHA384}`	Specifies an additional checksums for the HTTP request body in addition to the default MD5, to enhance object data integrity verification. Supported values are: `CRC32C` `SHA256` `SHA384`
`-checksum-content\|-csc <checksum-content>`	Specifies the checksum value corresponding to the selected checksum algorithm (`CRC32C`, `SHA256`, or `SHA384`) for the HTTP request body.
`-client-request-id\|-cid <client-request-id>`	Specifies the client request ID to use for tracing.
`-content-disposition\|-cd <content-disposition>`	Specifies the optional content-disposition header that defines presentational information for the object
`-content-encoding\|-ce <content-encoding>`	Specifies the content-encoding header that defines the content encodings that were applied to the object to upload. Content encoding primarily used to compress a document without losing the identity of its underlying media type.
`-content-language\|-cl <content-language>`	Specifies the content-encoding header that defines the content encodings that were applied to the object to upload. The natural language for the intended audience for the resource.
`-content-md5\|-cm <content-md5>`	Specifies the Base64-encoded MD5 hash of the request body for object data integrity verification.
`-content-type\|-ct <content-type>`	Specifies the content-type header that defines the standard MIME type format of the object.
`-etag\|-et <etag>`	Specifies the `ETag` to match with the `ETag` of an existing resource. If the specified `ETag` matches the `ETag` of the existing resource, `PUT` command uploads the resource.
`-object-name\|-on <object-name>`	Specifies the name of the OCI object.
`-overwrite\|-ow <overwrite> (true)`	Specifies to overwrite an object that already exists with the same object name or file name.
`-storage-tier\|-st <storage-tier> {Archive\|InfrequentAccess\|Standard}`	Specifies the storage tier that the objects should be stored in. If not specified, the objects are stored in the same storage tier as the bucket. The supported values are: `STANDARD` `INFREQUENTACCESS` `ARCHIVE`

Examples

Upload a file to OCI from the file location:

objectstorage object put -namespace ociNamespace -bucket-name
      ociBucketName -object-name someObject.txt -file /path/to/myfile.txt

Specify the -checksum-algorithm and its -checksum-content:

 objectstorage object put -namespace ociNamespace -bucket-name
      ociBucketName -object-name someObject.txt -checksum-algorithm SHA256
      -checksum-content <SHA256 hash base64 encoding> -file /path/to/myfile.txt

Specify multiple options:

objectstorage object put -namespace ociNamespace
      -bucket-nameociBucketName -object-name someObject.txt -file
      /path/to/myfile.txt -cache-control max-age=3600  -content-language en-US
      -content-type text/plain -content-disposition 'attachment;
      filename="example_file.txt"'

11.17.2.4 DELETE

Deletes an object from the OCI Object Storage.

Syntax

objectstorage delete {OPTIONS}

Options

Option	Description
Required
`-object-name\|-on <object-name>`	Specifies the name of an OCI object within a bucket.
Optional
`-namespace\|-ns <namespace>`	Specifies the OCI `namespace`. Note: Omit this option if you previously specified `objectstorage set namespace <name>` by using the set sub-command.
`-bucket-name\|-bn <bucket-name>`	Specifies the OCI `bucket name`. Note: Omit this option if you previously specified `objectstorage set bucket-name <name>` by using the set sub-command.
`-etag\|-et <etag>`	Specifies the entity tag (`ETag`) to match with the `ETag` of an existing object. If the specified `ETag` matches the `ETag` of the existing object, then the object is deleted.