OS_BUCKET(1)

NAME
os_bucket -

DESCRIPTION

A bucket is a container for storing objects in a compartment within a namespace. A bucket is associated with a single compartment. The compartment has policies that indicate what actions a user can perform on a bucket and all the objects in the bucket. For more information, see Managing Buckets <https://docs.cloud.oracle.com/Content/Object/Tasks/managingbuckets.htm>.

To use any of the API operations, you must be authorized in an IAM policy. If you are not authorized, talk to an administrator. If you are an administrator who needs to write policies to give users access, see Getting Started with Policies <https://docs.cloud.oracle.com/Content/Identity/Concepts/policygetstarted.htm>.

AVAILABLE COMMANDS

•   create

•   delete

•   get

•   list

•   reencrypt

•   update

  create

  Description

Creates a bucket in the given namespace with a bucket name and optional user-defined metadata. Avoid entering confidential information in bucket names.

  Usage

oci os bucket create [OPTIONS]

  Required Parameters

--compartment-id, -c [text]

    The ID of the compartment in which to create the bucket.

--name [text]

    The name of the bucket. Valid characters are uppercase or lowercase letters, numbers, hyphens, underscores, and periods. Bucket names must be unique within an Object Storage namespace. Avoid entering confidential information. example: Example: my-new-bucket1

  Optional Parameters

--defined-tags [complex type]

    Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags <https://docs.cloud.oracle.com/Content/General/Concepts/resourcetags.htm>. Example: {"Operations": {"CostCenter": "42"}} This is a complex type whose value must be valid JSON. The value can be provided as a string on the command line or passed in as a file using the file://path/to/file syntax.

    The --generate-param-json-input option can be used to generate an example of the JSON which must be provided. We recommend storing this example in a file, modifying it as needed and then passing it back in via the file:// syntax.

--freeform-tags [complex type]

    Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags <https://docs.cloud.oracle.com/Content/General/Concepts/resourcetags.htm>. Example: {"Department": "Finance"} This is a complex type whose value must be valid JSON. The value can be provided as a string on the command line or passed in as a file using the file://path/to/file syntax.

    The --generate-param-json-input option can be used to generate an example of the JSON which must be provided. We recommend storing this example in a file, modifying it as needed and then passing it back in via the file:// syntax.

--from-json [text]

    Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    The --generate-full-command-json-input option can be used to generate a sample json file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array.

    Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used.

    For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--kms-key-id [text]

    The OCID <https://docs.cloud.oracle.com/Content/General/Concepts/identifiers.htm> of a master encryption key used to call the Key Management service to generate a data encryption key or to encrypt or decrypt a data encryption key.

--metadata [complex type]

    Arbitrary string, up to 4KB, of keys and values for user-defined metadata. This is a complex type whose value must be valid JSON. The value can be provided as a string on the command line or passed in as a file using the file://path/to/file syntax.

    The --generate-param-json-input option can be used to generate an example of the JSON which must be provided. We recommend storing this example in a file, modifying it as needed and then passing it back in via the file:// syntax.

--namespace-name, --namespace, -ns [text]

    The Object Storage namespace used for the request. If not provided, this parameter will be obtained internally using a call to 'oci os ns get'

--object-events-enabled [boolean]

    Whether or not events are emitted for object state changes in this bucket. By default, objectEventsEnabled is set to false. Set objectEventsEnabled to true to emit events for object state changes. For more information about events, see Overview of Events <https://docs.cloud.oracle.com/Content/Events/Concepts/eventsoverview.htm>.

--public-access-type [text]

    The type of public access enabled on this bucket. A bucket is set to NoPublicAccess by default, which only allows an authenticated caller to access the bucket and its contents. When ObjectRead is enabled on the bucket, public access is allowed for the GetObject, HeadObject, and ListObjects operations. When ObjectReadWithoutList is enabled on the bucket, public access is allowed for the GetObject and HeadObject operations.

    Accepted values are:

    NoPublicAccess, ObjectRead, ObjectReadWithoutList

--storage-tier [text]

    The type of storage tier of this bucket. A bucket is set to 'Standard' tier by default, which means the bucket will be put in the standard storage tier. When 'Archive' tier type is set explicitly, the bucket is put in the Archive Storage tier. The 'storageTier' property is immutable after bucket is created.

    Accepted values are:

    Archive, Standard

  Global Parameters

Use oci --help for help on global parameters.

--auth, --cert-bundle, --cli-rc-file, --config-file, --debug, --defaults-file, --endpoint, --generate-full-command-json-input, --generate-param-json-input, --help, --no-retry, --opc-client-request-id, --opc-request-id, --output, --profile, --query, --raw-output, --region, --request-id, --version, -?, -d, -h, -v

  delete

  Description

Deletes a bucket if the bucket is already empty. If the bucket is not empty, use DeleteObject <https://docs.cloud.oracle.com/api/#/en/objectstorage/20160918/methods/DeleteObject> first. In addition, you cannot delete a bucket that has a multipart upload in progress or a pre-authenticated request associated with that bucket.

  Usage

oci os bucket delete [OPTIONS]

  Required Parameters

--bucket-name, --name, -bn [text]

    The name of the bucket. Avoid entering confidential information. Example: my-new-bucket1

  Optional Parameters

--force

    Perform deletion without prompting for confirmation.

--from-json [text]

    Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    The --generate-full-command-json-input option can be used to generate a sample json file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array.

    Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used.

    For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--if-match [text]

    The entity tag (ETag) to match. For creating and committing a multipart upload to an object, this is the entity tag of the target object. For uploading a part, this is the entity tag of the target part.

--namespace-name, --namespace, -ns [text]

    The Object Storage namespace used for the request. If not provided, this parameter will be obtained internally using a call to 'oci os ns get'

  Global Parameters

Use oci --help for help on global parameters.

--auth, --cert-bundle, --cli-rc-file, --config-file, --debug, --defaults-file, --endpoint, --generate-full-command-json-input, --generate-param-json-input, --help, --no-retry, --opc-client-request-id, --opc-request-id, --output, --profile, --query, --raw-output, --region, --request-id, --version, -?, -d, -h, -v

  get

  Description

Gets the current representation of the given bucket in the given Object Storage namespace.

  Usage

oci os bucket get [OPTIONS]

  Required Parameters

--bucket-name, --name, -bn [text]

    The name of the bucket. Avoid entering confidential information. Example: my-new-bucket1

  Optional Parameters

--fields [text]

    Bucket summary includes the 'namespace', 'name', 'compartmentId', 'createdBy', 'timeCreated', and 'etag' fields. This parameter can also include 'approximateCount' (approximate number of objects) and 'approximateSize' (total approximate size in bytes of all objects). For example 'approximateCount,approximateSize'.

    Accepted values are:

    approximateCount, approximateSize

--from-json [text]

    Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    The --generate-full-command-json-input option can be used to generate a sample json file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array.

    Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used.

    For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--if-match [text]

    The entity tag (ETag) to match. For creating and committing a multipart upload to an object, this is the entity tag of the target object. For uploading a part, this is the entity tag of the target part.

--if-none-match [text]

    The entity tag (ETag) to avoid matching. The only valid value is '*', which indicates that the request should fail if the object already exists. For creating and committing a multipart upload, this is the entity tag of the target object. For uploading a part, this is the entity tag of the target part.

--namespace-name, --namespace, -ns [text]

    The Object Storage namespace used for the request. If not provided, this parameter will be obtained internally using a call to 'oci os ns get'

  Global Parameters

Use oci --help for help on global parameters.

--auth, --cert-bundle, --cli-rc-file, --config-file, --debug, --defaults-file, --endpoint, --generate-full-command-json-input, --generate-param-json-input, --help, --no-retry, --opc-client-request-id, --opc-request-id, --output, --profile, --query, --raw-output, --region, --request-id, --version, -?, -d, -h, -v

  list

  Description

Gets a list of all BucketSummary items in a compartment. A BucketSummary contains only summary fields for the bucket and does not contain fields like the user-defined metadata.

To use this and other API operations, you must be authorized in an IAM policy. If you are not authorized, talk to an administrator. If you are an administrator who needs to write policies to give users access, see Getting Started with Policies <https://docs.cloud.oracle.com/Content/Identity/Concepts/policygetstarted.htm>.

  Usage

oci os bucket list [OPTIONS]

  Required Parameters

--compartment-id, -c [text]

    The ID of the compartment in which to list buckets.

  Optional Parameters

--all

    Fetches all pages of results. If you provide this option, then you cannot provide the --limit option.

--fields [text]

    Bucket summary in list of buckets includes the 'namespace', 'name', 'compartmentId', 'createdBy', 'timeCreated', and 'etag' fields. This parameter can also include 'tags' (freeformTags and definedTags). The only supported value of this parameter is 'tags' for now. Example 'tags'.

    Accepted values are:

    tags

--from-json [text]

    Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    The --generate-full-command-json-input option can be used to generate a sample json file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array.

    Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used.

    For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--limit [integer]

    The maximum number of items to return.

--namespace-name, --namespace, -ns [text]

    The Object Storage namespace used for the request. If not provided, this parameter will be obtained internally using a call to 'oci os ns get'

--page [text]

    The page at which to start retrieving results.

--page-size [integer]

    When fetching results, the number of results to fetch per call. Only valid when used with --all or --limit, and ignored otherwise.

  Global Parameters

Use oci --help for help on global parameters.

--auth, --cert-bundle, --cli-rc-file, --config-file, --debug, --defaults-file, --endpoint, --generate-full-command-json-input, --generate-param-json-input, --help, --no-retry, --opc-client-request-id, --opc-request-id, --output, --profile, --query, --raw-output, --region, --request-id, --version, -?, -d, -h, -v

  reencrypt

  Description

Re-encrypts the unique data encryption key that encrypts each object written to the bucket by using the most recent version of the master encryption key assigned to the bucket. (All data encryption keys are encrypted by a master encryption key. Master encryption keys are assigned to buckets and managed by Oracle by default, but you can assign a key that you created and control through the Oracle Cloud Infrastructure Key Management service.) The kmsKeyId property of the bucket determines which master encryption key is assigned to the bucket. If you assigned a different Key Management master encryption key to the bucket, you can call this API to re-encrypt all data encryption keys with the newly assigned key. Similarly, you might want to re-encrypt all data encryption keys if the assigned key has been rotated to a new key version since objects were last added to the bucket. If you call this API and there is no kmsKeyId associated with the bucket, the call will fail.

Calling this API starts a work request task to re-encrypt the data encryption key of all objects in the bucket. Only objects created before the time of the API call will be re-encrypted. The call can take a long time, depending on how many objects are in the bucket and how big they are. This API returns a work request ID that you can use to retrieve the status of the work request task.

  Usage

oci os bucket reencrypt [OPTIONS]

  Required Parameters

--bucket-name, -bn [text]

    The name of the bucket. Avoid entering confidential information. Example: my-new-bucket1

  Optional Parameters

--from-json [text]

    Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    The --generate-full-command-json-input option can be used to generate a sample json file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array.

    Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used.

    For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--max-wait-seconds [integer]

    The maximum time to wait for the work request to reach the state defined by --wait-for-state. Defaults to 1200 seconds.

--namespace-name, --namespace, -ns [text]

    The Object Storage namespace used for the request. If not provided, this parameter will be obtained internally using a call to 'oci os ns get'

--wait-for-state [text]

    This operation asynchronously creates, modifies or deletes a resource and uses a work request to track the progress of the operation. Specify this option to perform the action and then wait until the work request reaches a certain state. Multiple states can be specified, returning on the first state. For example, --wait-for-state SUCCEEDED --wait-for-state FAILED would return on whichever lifecycle state is reached first. If timeout is reached, a return code of 2 is returned. For any other error, a return code of 1 is returned.

    Accepted values are:

    ACCEPTED, CANCELED, CANCELING, COMPLETED, FAILED, IN_PROGRESS

--wait-interval-seconds [integer]

    Check every --wait-interval-seconds to see whether the work request to see if it has reached the state defined by --wait-for-state. Defaults to 30 seconds.

  Global Parameters

Use oci --help for help on global parameters.

--auth, --cert-bundle, --cli-rc-file, --config-file, --debug, --defaults-file, --endpoint, --generate-full-command-json-input, --generate-param-json-input, --help, --no-retry, --opc-client-request-id, --opc-request-id, --output, --profile, --query, --raw-output, --region, --request-id, --version, -?, -d, -h, -v

  update

  Description

Performs a partial or full update of a bucket's user-defined metadata.

Use UpdateBucket to move a bucket from one compartment to another within the same tenancy. Supply the compartmentID of the compartment that you want to move the bucket to. For more information about moving resources between compartments, see Moving Resources to a Different Compartment <https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes>.

  Usage

oci os bucket update [OPTIONS]

  Required Parameters

--bucket-name, --name, -bn [text]

    The name of the bucket. Avoid entering confidential information. Example: my-new-bucket1

  Optional Parameters

--compartment-id, -c [text]

    The compartmentId for the compartment to move the bucket to.

--defined-tags [complex type]

    Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see Resource Tags <https://docs.cloud.oracle.com/Content/General/Concepts/resourcetags.htm>. Example:
    `
    {"Operations": {"CostCenter": "42"}} This is a complex type whose value must be valid JSON. The value can be provided as a string on the command line or passed in as a file using the file://path/to/file syntax.

    The --generate-param-json-input option can be used to generate an example of the JSON which must be provided. We recommend storing this example in a file, modifying it as needed and then passing it back in via the file:// syntax.

--freeform-tags [complex type]

    Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see Resource Tags <https://docs.cloud.oracle.com/Content/General/Concepts/resourcetags.htm>. Example: {"Department": "Finance"} This is a complex type whose value must be valid JSON. The value can be provided as a string on the command line or passed in as a file using the file://path/to/file syntax.

    The --generate-param-json-input option can be used to generate an example of the JSON which must be provided. We recommend storing this example in a file, modifying it as needed and then passing it back in via the file:// syntax.

--from-json [text]

    Provide input to this command as a JSON document from a file using the file://path-to/file syntax.

    The --generate-full-command-json-input option can be used to generate a sample json file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array.

    Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used.

    For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions

--if-match [text]

    The entity tag (ETag) to match. For creating and committing a multipart upload to an object, this is the entity tag of the target object. For uploading a part, this is the entity tag of the target part.

--kms-key-id [text]

    The OCID <https://docs.cloud.oracle.com/Content/General/Concepts/identifiers.htm> of the Key Management master encryption key to associate with the specified bucket. If this value is empty, the Update operation will remove the associated key, if there is one, from the bucket. (The bucket will continue to be encrypted, but with an encryption key managed by Oracle.)

--metadata [complex type]

    Arbitrary string, up to 4KB, of keys and values for user-defined metadata. This is a complex type whose value must be valid JSON. The value can be provided as a string on the command line or passed in as a file using the file://path/to/file syntax.

    The --generate-param-json-input option can be used to generate an example of the JSON which must be provided. We recommend storing this example in a file, modifying it as needed and then passing it back in via the file:// syntax.

--namespace-name, --namespace, -ns [text]

    The Object Storage namespace used for the request. If not provided, this parameter will be obtained internally using a call to 'oci os ns get'

--object-events-enabled [boolean]

    Whether or not events are emitted for object state changes in this bucket. By default, objectEventsEnabled is set to false. Set objectEventsEnabled to true to emit events for object state changes. For more information about events, see Overview of Events <https://docs.cloud.oracle.com/Content/Events/Concepts/eventsoverview.htm>.

--public-access-type [text]

    The type of public access enabled on this bucket. A bucket is set to NoPublicAccess by default, which only allows an authenticated caller to access the bucket and its contents. When ObjectRead is enabled on the bucket, public access is allowed for the GetObject, HeadObject, and ListObjects operations. When ObjectReadWithoutList is enabled on the bucket, public access is allowed for the GetObject and HeadObject operations.

    Accepted values are:

    NoPublicAccess, ObjectRead, ObjectReadWithoutList

  Global Parameters

Use oci --help for help on global parameters.

--auth, --cert-bundle, --cli-rc-file, --config-file, --debug, --defaults-file, --endpoint, --generate-full-command-json-input, --generate-param-json-input, --help, --no-retry, --opc-client-request-id, --opc-request-id, --output, --profile, --query, --raw-output, --region, --request-id, --version, -?, -d, -h, -v

AUTHOR
Oracle

COPYRIGHT
2016, 2020, Oracle