buckets

Creates, updates, deletes, gets or lists a buckets resource.

Overview

Name	`buckets`
Type	Resource
Id	`oci.object_storage.buckets`

Fields

The following fields are returned by SELECT queries:

get
list

A bucket representation for the requested bucket.

Name	Datatype	Description
`id`	`string`	The [OCID](/Content/General/Concepts/identifiers.htm) of the bucket.
`name`	`string`	The name of the bucket. Avoid entering confidential information. Example: my-new-bucket1
`approximateCount`	`integer (int64)`	The approximate number of objects in the bucket. Count statistics are reported periodically. You will see a lag between what is displayed and the actual object count.
`approximateSize`	`integer (int64)`	The approximate total size in bytes of all objects in the bucket. Size statistics are reported periodically. You will see a lag between what is displayed and the actual size of the bucket.
`autoTiering`	`string`	The auto tiering status on the bucket. A bucket is created with auto tiering `Disabled` by default. For auto tiering `InfrequentAccess`, objects are transitioned automatically between the 'Standard' and 'InfrequentAccess' tiers based on the access pattern of the objects. (Disabled, InfrequentAccess)
`bucketScope`	`string`	The bucket scope determines weather the bucket name must be unique within the tenancy and region (essentially the namespace) or across all tenancies in the region. The bucket scope also determines if the bucket supports S3 virtual-hosted style URL's or not. Allowed values: NAMESPACE: Only supports path-style bucket access, bucket name only needs to be unique within the tenancy and region. REGION: Supports both path-style and virtual-hosted URL style access, bucket name needs to be unique across all tenancies in the region. (NAMESPACE, REGION)
`compartmentId`	`string`	The compartment ID in which the bucket is authorized.
`createdBy`	`string`	The [OCID](/Content/General/Concepts/identifiers.htm) of the user who created the bucket.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`etag`	`string`	The entity tag (ETag) for the bucket.
`freeformTags`	`object`	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](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`isBucketKeyEnabled`	`boolean`	Specifies whether Object Storage should use intermediate cached Bucket Encryption Keys with server-side encryption using KMS (SSE-KMS) for new objects in the bucket. This reduces calls to OCI Vault Key Management Service (KMS). Existing objects are not affected.
`isReadOnly`	`boolean`	Whether or not this bucket is read only. By default, `isReadOnly` is set to `false`. This will be set to 'true' when this bucket is configured as a destination in a replication policy.
`kmsKeyId`	`string`	The [OCID](/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`	`object`	Arbitrary string keys and values for user-defined metadata.
`namespace`	`string`	The Object Storage namespace in which the bucket resides.
`objectEventsEnabled`	`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](/Content/Events/Concepts/eventsoverview.htm).
`objectLifecyclePolicyEtag`	`string`	The entity tag (ETag) for the live object lifecycle policy on the bucket.
`publicAccessType`	`string`	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. (NoPublicAccess, ObjectRead, ObjectReadWithoutList)
`replicationEnabled`	`boolean`	Whether or not this bucket is a replication source. By default, `replicationEnabled` is set to `false`. This will be set to 'true' when you create a replication policy for the bucket.
`storageTier`	`string`	The storage tier type assigned to the bucket. A bucket is set to `Standard` tier by default, which means objects uploaded or copied to the bucket will be in the standard storage tier. When the `Archive` tier type is set explicitly for a bucket, objects uploaded or copied to the bucket will be stored in archive storage. The `storageTier` property is immutable after bucket is created. (Standard, Archive)
`timeCreated`	`string (date-time)`	The date and time the bucket was created, as described in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.29).
`versioning`	`string`	The versioning status on the bucket. A bucket is created with versioning `Disabled` by default. For versioning `Enabled`, objects are protected from overwrites and deletes, by maintaining their version history. When versioning is `Suspended`, the previous versions will still remain but new versions will no longer be created when overwitten or deleted. (Enabled, Suspended, Disabled)

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](/Content/Identity/Concepts/policygetstarted.htm).

Name	Datatype	Description
`name`	`string`	The name of the bucket. Avoid entering confidential information. Example: my-new-bucket1
`bucketScope`	`string`	The bucket scope determines weather the bucket name must be unique within the tenancy and region (essentially the namespace) or across all tenancies in the region. The bucket scope also determines if the bucket supports S3 virtual-hosted style URL's or not. Allowed values: NAMESPACE: Only supports path-style bucket access, bucket name only needs to be unique within the tenancy and region. REGION: Supports both path-style and virtual-hosted URL style access, bucket name needs to be unique across all tenancies in the region. (x-obmcs-enumref: #/definitions/Bucket/bucketScope)
`compartmentId`	`string`	The compartment ID in which the bucket is authorized.
`createdBy`	`string`	The [OCID](/Content/General/Concepts/identifiers.htm) of the user who created the bucket.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`etag`	`string`	The entity tag (ETag) for the bucket.
`freeformTags`	`object`	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](/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`namespace`	`string`	The Object Storage namespace in which the bucket lives.
`timeCreated`	`string (date-time)`	The date and time the bucket was created, as described in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.29).

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`namespaceName`, `bucketName`, `region`	`if-match`, `if-none-match`, `opc-client-request-id`, `fields`	Gets the current representation of the given bucket in the given Object Storage namespace.<br />
`list`	`select`	`namespaceName`, `compartmentId`, `region`	`limit`, `page`, `fields`, `opc-client-request-id`	Gets a list of all BucketSummary items in a compartment. A BucketSummary contains only summary fields for the bucket<br />and does not contain fields like the user-defined metadata.<br /><br />ListBuckets returns a BucketSummary containing at most 1000 buckets. To paginate through more buckets, use the returned<br />`opc-next-page` value with the `page` request parameter.<br /><br />To use this and other API operations, you must be authorized in an IAM policy. If you are not authorized,<br />talk to an administrator. If you are an administrator who needs to write policies to give users access, see<br />[Getting Started with Policies](/Content/Identity/Concepts/policygetstarted.htm).<br />
`create`	`insert`	`namespaceName`, `region`, `name`, `compartmentId`	`opc-client-request-id`	Creates a bucket in the given namespace with a bucket name and optional user-defined metadata. Avoid entering<br />confidential information in bucket names.<br />
`update`	`update`	`namespaceName`, `bucketName`, `region`	`if-match`, `opc-client-request-id`	Performs a partial or full update of a bucket's user-defined metadata.<br /><br />Use UpdateBucket to move a bucket from one compartment to another within the same tenancy. Supply the compartmentID<br />of the compartment that you want to move the bucket to. For more information about moving resources between compartments,<br />see [Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br />
`delete`	`delete`	`namespaceName`, `bucketName`, `region`	`if-match`, `opc-client-request-id`	Deletes a bucket if the bucket is already empty. If the bucket is not empty, use<br />[DeleteObject](#/en/objectstorage/20160918/Object/DeleteObject) first. In addition,<br />you cannot delete a bucket that has a multipart upload in progress or a pre-authenticated<br />request associated with that bucket.<br />

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`bucketName`	`string`	The name of the bucket. Avoid entering confidential information. Example: `my-new-bucket1`
`compartmentId`	`string`	The ID of the compartment in which to list buckets.
`namespaceName`	`string`	The Object Storage namespace used for the request.
`region`	`string`	OCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
`fields`	`array`	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'.
`if-match`	`string`	The entity tag (ETag) to match with the ETag of an existing resource. If the specified ETag matches the ETag of the existing resource, GET and HEAD requests will return the resource and PUT and POST requests will upload the resource.
`if-none-match`	`string`	The entity tag (ETag) to avoid matching. Wildcards ('*') are not allowed. If the specified ETag does not match the ETag of the existing resource, the request returns the expected response. If the ETag matches the ETag of the existing resource, the request returns an HTTP 304 status without a response body.
`limit`	`integer`	For list pagination. The maximum number of results per page, or items to return in a paginated "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
`opc-client-request-id`	`string`	The client request ID for tracing.
`page`	`string`	For list pagination. The value of the `opc-next-page` response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

`SELECT` examples

get
list

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

SELECT
id,
name,
approximateCount,
approximateSize,
autoTiering,
bucketScope,
compartmentId,
createdBy,
definedTags,
etag,
freeformTags,
isBucketKeyEnabled,
isReadOnly,
kmsKeyId,
metadata,
namespace,
objectEventsEnabled,
objectLifecyclePolicyEtag,
publicAccessType,
replicationEnabled,
storageTier,
timeCreated,
versioning
FROM oci.object_storage.buckets
WHERE namespaceName = '{{ namespaceName }}' -- required
AND bucketName = '{{ bucketName }}' -- required
AND region = '{{ region }}' -- required
AND if-match = '{{ if-match }}'
AND if-none-match = '{{ if-none-match }}'
AND opc-client-request-id = '{{ opc-client-request-id }}'
AND fields = '{{ fields }}'
;

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. ListBuckets returns a BucketSummary containing at most 1000 buckets. To paginate through more buckets, use the returned opc-next-page value with the page request parameter. 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](/Content/Identity/Concepts/policygetstarted.htm).

SELECT
name,
bucketScope,
compartmentId,
createdBy,
definedTags,
etag,
freeformTags,
namespace,
timeCreated
FROM oci.object_storage.buckets
WHERE namespaceName = '{{ namespaceName }}' -- required
AND compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND fields = '{{ fields }}'
AND opc-client-request-id = '{{ opc-client-request-id }}'
;

`INSERT` examples

create
Manifest

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

INSERT INTO oci.object_storage.buckets (
autoTiering,
bucketScope,
compartmentId,
definedTags,
freeformTags,
isBucketKeyEnabled,
kmsKeyId,
metadata,
name,
objectEventsEnabled,
publicAccessType,
storageTier,
versioning,
namespaceName,
region,
opc-client-request-id
)
SELECT 
'{{ autoTiering }}',
'{{ bucketScope }}',
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ freeformTags }}',
{{ isBucketKeyEnabled }},
'{{ kmsKeyId }}',
'{{ metadata }}',
'{{ name }}' /* required */,
{{ objectEventsEnabled }},
'{{ publicAccessType }}',
'{{ storageTier }}',
'{{ versioning }}',
'{{ namespaceName }}',
'{{ region }}',
'{{ opc-client-request-id }}'
RETURNING
id,
name,
approximateCount,
approximateSize,
autoTiering,
bucketScope,
compartmentId,
createdBy,
definedTags,
etag,
freeformTags,
isBucketKeyEnabled,
isReadOnly,
kmsKeyId,
metadata,
namespace,
objectEventsEnabled,
objectLifecyclePolicyEtag,
publicAccessType,
replicationEnabled,
storageTier,
timeCreated,
versioning
;

# Description fields are for documentation purposes
- name: buckets
props:
  - name: namespaceName
    value: "{{ namespaceName }}"
    description: Required parameter for the buckets resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the buckets resource.
  - name: autoTiering
    value: "{{ autoTiering }}"
    description: |
      Set the auto tiering status on the bucket. By default, a bucket is created with auto tiering `Disabled`.
      Use this option to enable auto tiering during bucket creation. Objects in a bucket with auto tiering set to
      `InfrequentAccess` are transitioned automatically between the 'Standard' and 'InfrequentAccess'
      tiers based on the access pattern of the objects.
  - name: bucketScope
    value: "{{ bucketScope }}"
    description: |
      The bucket scope determines weather the bucket name must be unique within the tenancy and region (essentially the namespace) or across all tenancies in the region. The bucket scope also determines if the bucket supports S3 virtual-hosted style URL's or not.
      Allowed values:
      NAMESPACE: Only supports path-style bucket access, bucket name only needs to be unique within the tenancy and region.
      REGION: Supports both path-style and virtual-hosted URL style access, bucket name needs to be unique across all tenancies in the region.
  - name: compartmentId
    value: "{{ compartmentId }}"
    description: |
      The ID of the compartment in which to create the bucket.
  - name: definedTags
    value: "{{ definedTags }}"
    description: |
      Defined tags for this resource. Each key is predefined and scoped to a namespace.
      For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Operations": {"CostCenter": "42"}}`
  - name: freeformTags
    value: "{{ freeformTags }}"
    description: |
      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](/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: isBucketKeyEnabled
    value: {{ isBucketKeyEnabled }}
    description: |
      Specifies whether Object Storage should use intermediate cached Bucket Encryption Keys with server-side
      encryption using KMS (SSE-KMS) for new objects in the bucket. This reduces calls to OCI Vault Key Management
      Service (KMS). Existing objects are not affected.
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"
    description: |
      The [OCID](/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.
  - name: metadata
    value: "{{ metadata }}"
    description: |
      Arbitrary string, up to 4KB, of keys and values for user-defined metadata.
  - name: name
    value: "{{ name }}"
    description: |
      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
  - name: objectEventsEnabled
    value: {{ objectEventsEnabled }}
    description: |
      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](/Content/Events/Concepts/eventsoverview.htm).
  - name: publicAccessType
    value: "{{ publicAccessType }}"
    description: |
      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.
    valid_values: ['NoPublicAccess', 'ObjectRead', 'ObjectReadWithoutList']
  - name: storageTier
    value: "{{ storageTier }}"
    description: |
      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.
    valid_values: ['Standard', 'Archive']
  - name: versioning
    value: "{{ versioning }}"
    description: |
      Set the versioning status on the bucket. By default, a bucket is created with versioning `Disabled`. Use this option to enable versioning during bucket creation. Objects in a version enabled bucket are protected from overwrites and deletions. Previous versions of the same object will be available in the bucket.
    valid_values: ['Enabled', 'Disabled']
  - name: opc-client-request-id
    value: "{{ opc-client-request-id }}"
    description: The client request ID for tracing.
    description: The client request ID for tracing.

`UPDATE` examples

update

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](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).

UPDATE oci.object_storage.buckets
SET 
autoTiering = '{{ autoTiering }}',
bucketScope = '{{ bucketScope }}',
compartmentId = '{{ compartmentId }}',
definedTags = '{{ definedTags }}',
freeformTags = '{{ freeformTags }}',
isBucketKeyEnabled = {{ isBucketKeyEnabled }},
kmsKeyId = '{{ kmsKeyId }}',
metadata = '{{ metadata }}',
name = '{{ name }}',
namespace = '{{ namespace }}',
objectEventsEnabled = {{ objectEventsEnabled }},
publicAccessType = '{{ publicAccessType }}',
versioning = '{{ versioning }}'
WHERE 
namespaceName = '{{ namespaceName }}' --required
AND bucketName = '{{ bucketName }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND opc-client-request-id = '{{ opc-client-request-id}}'
RETURNING
id,
name,
approximateCount,
approximateSize,
autoTiering,
bucketScope,
compartmentId,
createdBy,
definedTags,
etag,
freeformTags,
isBucketKeyEnabled,
isReadOnly,
kmsKeyId,
metadata,
namespace,
objectEventsEnabled,
objectLifecyclePolicyEtag,
publicAccessType,
replicationEnabled,
storageTier,
timeCreated,
versioning;

`DELETE` examples

delete

Deletes a bucket if the bucket is already empty. If the bucket is not empty, use [DeleteObject](#/en/objectstorage/20160918/Object/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.

DELETE FROM oci.object_storage.buckets
WHERE namespaceName = '{{ namespaceName }}' --required
AND bucketName = '{{ bucketName }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND opc-client-request-id = '{{ opc-client-request-id }}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​