volume_backups

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

Overview

Name	`volume_backups`
Type	Resource
Id	`oci.block_storage.volume_backups`

Fields

The following fields are returned by SELECT queries:

get
list

The volume backup was retrieved.

Name	Datatype	Description
`id`	`string`	The OCID of the volume backup.
`compartmentId`	`string`	The OCID of the compartment that contains the volume backup.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`displayName`	`string`	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
`expirationTime`	`string (date-time)`	The date and time the volume backup will expire and be automatically deleted. Format defined by [RFC3339](https://tools.ietf.org/html/rfc3339). This parameter will always be present for backups that were created automatically by a scheduled-backup policy. For manually created backups, it will be absent, signifying that there is no expiration time and the backup will last forever until manually deleted.
`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](/iaas/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`kmsKeyId`	`string`	The OCID of the Vault service key which is the master encryption key for the volume backup. For more information about the Vault service and encryption keys, see [Overview of Vault service](/iaas/Content/KeyManagement/Concepts/keyoverview.htm) and [Using Keys](/iaas/Content/KeyManagement/Tasks/usingkeys.htm).
`lifecycleState`	`string`	The current state of a volume backup. (CREATING, AVAILABLE, TERMINATING, TERMINATED, FAULTY, REQUEST_RECEIVED)
`sizeInGBs`	`integer (int64)`	The size of the volume, in GBs.
`sizeInMBs`	`integer (int64)`	The size of the volume in MBs. The value must be a multiple of 1024. This field is deprecated. Please use sizeInGBs.
`sourceType`	`string`	Specifies whether the backup was created manually, or via scheduled backup policy. (MANUAL, SCHEDULED)
`sourceVolumeBackupId`	`string`	The OCID of the source volume backup.
`timeCreated`	`string (date-time)`	The date and time the volume backup was created. This is the time the actual point-in-time image of the volume data was taken. Format defined by [RFC3339](https://tools.ietf.org/html/rfc3339).
`timeRequestReceived`	`string (date-time)`	The date and time the request to create the volume backup was received. Format defined by [RFC3339]https://tools.ietf.org/html/rfc3339.
`type`	`string`	The type of a volume backup. (FULL, INCREMENTAL)
`uniqueSizeInGBs`	`integer (int64)`	The size used by the backup, in GBs. It is typically smaller than sizeInGBs, depending on the space consumed on the volume and whether the backup is full or incremental.
`uniqueSizeInMbs`	`integer (int64)`	The size used by the backup, in MBs. It is typically smaller than sizeInMBs, depending on the space consumed on the volume and whether the backup is full or incremental. This field is deprecated. Please use uniqueSizeInGBs.
`volumeId`	`string`	The OCID of the volume.

A point-in-time copy of a volume that can then be used to create a new block volume or recover a block volume. For more information, see [Overview of Cloud Volume Storage](/iaas/Content/Block/Concepts/overview.htm). To use any of the API operations, you must be authorized in an IAM policy. If you're not authorized, talk to an administrator. If you're an administrator who needs to write policies to give users access, see [Getting Started with Policies](/iaas/Content/Identity/Concepts/policygetstarted.htm). Warning: Oracle recommends that you avoid using any confidential information when you supply string values using the API.

Name	Datatype	Description
`id`	`string`	The OCID of the volume backup.
`compartmentId`	`string`	The OCID of the compartment that contains the volume backup.
`definedTags`	`object`	Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/iaas/Content/General/Concepts/resourcetags.htm). Example: `{"Operations": {"CostCenter": "42"}}`
`displayName`	`string`	A user-friendly name. Does not have to be unique, and it's changeable. Avoid entering confidential information.
`expirationTime`	`string (date-time)`	The date and time the volume backup will expire and be automatically deleted. Format defined by [RFC3339](https://tools.ietf.org/html/rfc3339). This parameter will always be present for backups that were created automatically by a scheduled-backup policy. For manually created backups, it will be absent, signifying that there is no expiration time and the backup will last forever until manually deleted.
`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](/iaas/Content/General/Concepts/resourcetags.htm). Example: `{"Department": "Finance"}`
`kmsKeyId`	`string`	The OCID of the Vault service key which is the master encryption key for the volume backup. For more information about the Vault service and encryption keys, see [Overview of Vault service](/iaas/Content/KeyManagement/Concepts/keyoverview.htm) and [Using Keys](/iaas/Content/KeyManagement/Tasks/usingkeys.htm).
`lifecycleState`	`string`	The current state of a volume backup. (CREATING, AVAILABLE, TERMINATING, TERMINATED, FAULTY, REQUEST_RECEIVED)
`sizeInGBs`	`integer (int64)`	The size of the volume, in GBs.
`sizeInMBs`	`integer (int64)`	The size of the volume in MBs. The value must be a multiple of 1024. This field is deprecated. Please use sizeInGBs.
`sourceType`	`string`	Specifies whether the backup was created manually, or via scheduled backup policy. (MANUAL, SCHEDULED)
`sourceVolumeBackupId`	`string`	The OCID of the source volume backup.
`timeCreated`	`string (date-time)`	The date and time the volume backup was created. This is the time the actual point-in-time image of the volume data was taken. Format defined by [RFC3339](https://tools.ietf.org/html/rfc3339).
`timeRequestReceived`	`string (date-time)`	The date and time the request to create the volume backup was received. Format defined by [RFC3339]https://tools.ietf.org/html/rfc3339.
`type`	`string`	The type of a volume backup. (FULL, INCREMENTAL)
`uniqueSizeInGBs`	`integer (int64)`	The size used by the backup, in GBs. It is typically smaller than sizeInGBs, depending on the space consumed on the volume and whether the backup is full or incremental.
`uniqueSizeInMbs`	`integer (int64)`	The size used by the backup, in MBs. It is typically smaller than sizeInMBs, depending on the space consumed on the volume and whether the backup is full or incremental. This field is deprecated. Please use uniqueSizeInGBs.
`volumeId`	`string`	The OCID of the volume.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`volumeBackupId`, `region`		Gets information for the specified volume backup.
`list`	`select`	`compartmentId`, `region`	`volumeId`, `limit`, `page`, `displayName`, `sourceVolumeBackupId`, `sortBy`, `sortOrder`, `lifecycleState`	Lists the volume backups in the specified compartment. You can filter the results by volume.<br />
`create`	`insert`	`region`, `volumeId`	`opc-retry-token`	Creates a new backup of the specified volume. For general information about volume backups,<br />see [Overview of Block Volume Service Backups](/iaas/Content/Block/Concepts/blockvolumebackups.htm)<br /><br />When the request is received, the backup object is in a REQUEST_RECEIVED state.<br />When the data is imaged, it goes into a CREATING state.<br />After the backup is fully uploaded to the cloud, it goes into an AVAILABLE state.<br />
`update`	`update`	`volumeBackupId`, `region`	`if-match`	Updates the display name for the specified volume backup.<br />Avoid entering confidential information.<br />
`delete`	`delete`	`volumeBackupId`, `region`	`if-match`	Deletes a volume backup.
`change_compartment`	`exec`	`volumeBackupId`, `region`, `compartmentId`	`opc-request-id`	Moves a volume backup into a different compartment within the same tenancy.<br />For information about moving resources between compartments,<br />see [Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).<br />
`copy_volume_backup`	`exec`	`volumeBackupId`, `region`, `destinationRegion`	`opc-retry-token`, `opc-request-id`	Creates a volume backup copy in specified region. For general information about volume backups,<br />see [Overview of Block Volume Service Backups](/iaas/Content/Block/Concepts/blockvolumebackups.htm)<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
`compartmentId`	`string`	The [OCID](/iaas/Content/General/Concepts/identifiers.htm) of the compartment.
`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)
`volumeBackupId`	`string`	The OCID of the volume backup.
`displayName`	`string`	A filter to return only resources that match the given display name exactly.
`if-match`	`string`	For optimistic concurrency control. In the PUT or DELETE call for a resource, set the `if-match` parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
`lifecycleState`	`string`	A filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
`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). Example: `50`
`opc-request-id`	`string`	Unique identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
`opc-retry-token`	`string`	A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
`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).
`sortBy`	`string`	The field to sort by. You can provide one sort order (`sortOrder`). Default order for TIMECREATED is descending. Default order for DISPLAYNAME is ascending. The DISPLAYNAME sort order is case sensitive. Note: In general, some "List" operations (for example, `ListInstances`) let you optionally filter by availability domain if the scope of the resource type is within a single availability domain. If you call one of these "List" operations without specifying an availability domain, the resources are grouped by availability domain, then sorted.
`sortOrder`	`string`	The sort order to use, either ascending (`ASC`) or descending (`DESC`). The DISPLAYNAME sort order is case sensitive.
`sourceVolumeBackupId`	`string`	A filter to return only resources that originated from the given source volume backup.
`volumeId`	`string`	The OCID of the volume.

`SELECT` examples

get
list

Gets information for the specified volume backup.

SELECT
id,
compartmentId,
definedTags,
displayName,
expirationTime,
freeformTags,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceType,
sourceVolumeBackupId,
timeCreated,
timeRequestReceived,
type,
uniqueSizeInGBs,
uniqueSizeInMbs,
volumeId
FROM oci.block_storage.volume_backups
WHERE volumeBackupId = '{{ volumeBackupId }}' -- required
AND region = '{{ region }}' -- required
;

Lists the volume backups in the specified compartment. You can filter the results by volume.

SELECT
id,
compartmentId,
definedTags,
displayName,
expirationTime,
freeformTags,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceType,
sourceVolumeBackupId,
timeCreated,
timeRequestReceived,
type,
uniqueSizeInGBs,
uniqueSizeInMbs,
volumeId
FROM oci.block_storage.volume_backups
WHERE compartmentId = '{{ compartmentId }}' -- required
AND region = '{{ region }}' -- required
AND volumeId = '{{ volumeId }}'
AND limit = '{{ limit }}'
AND page = '{{ page }}'
AND displayName = '{{ displayName }}'
AND sourceVolumeBackupId = '{{ sourceVolumeBackupId }}'
AND sortBy = '{{ sortBy }}'
AND sortOrder = '{{ sortOrder }}'
AND lifecycleState = '{{ lifecycleState }}'
;

`INSERT` examples

create
Manifest

Creates a new backup of the specified volume. For general information about volume backups, see [Overview of Block Volume Service Backups](/iaas/Content/Block/Concepts/blockvolumebackups.htm) When the request is received, the backup object is in a REQUEST_RECEIVED state. When the data is imaged, it goes into a CREATING state. After the backup is fully uploaded to the cloud, it goes into an AVAILABLE state.

INSERT INTO oci.block_storage.volume_backups (
definedTags,
displayName,
freeformTags,
kmsKeyId,
type,
volumeId,
region,
opc-retry-token
)
SELECT 
'{{ definedTags }}',
'{{ displayName }}',
'{{ freeformTags }}',
'{{ kmsKeyId }}',
'{{ type }}',
'{{ volumeId }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
expirationTime,
freeformTags,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceType,
sourceVolumeBackupId,
timeCreated,
timeRequestReceived,
type,
uniqueSizeInGBs,
uniqueSizeInMbs,
volumeId
;

# Description fields are for documentation purposes
- name: volume_backups
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the volume_backups resource.
  - 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](/iaas/Content/General/Concepts/resourcetags.htm).
      Example: `{"Operations": {"CostCenter": "42"}}`
  - name: displayName
    value: "{{ displayName }}"
    description: |
      A user-friendly name. Does not have to be unique, and it's changeable.
      Avoid entering confidential information.
  - 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](/iaas/Content/General/Concepts/resourcetags.htm).
      Example: `{"Department": "Finance"}`
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"
    description: |
      The OCID of the Vault service key which is the master encryption key for the volume backup.
      For more information about the Vault service and encryption keys, see
      [Overview of Vault service](/iaas/Content/KeyManagement/Concepts/keyoverview.htm) and
      [Using Keys](/iaas/Content/KeyManagement/Tasks/usingkeys.htm).
  - name: type
    value: "{{ type }}"
    description: |
      The type of backup to create. If omitted, defaults to INCREMENTAL.
    valid_values: ['FULL', 'INCREMENTAL']
  - name: volumeId
    value: "{{ volumeId }}"
    description: |
      The OCID of the volume that needs to be backed up.
  - name: opc-retry-token
    value: "{{ opc-retry-token }}"
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 
    description: A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected). 

`UPDATE` examples

update

Updates the display name for the specified volume backup. Avoid entering confidential information.

UPDATE oci.block_storage.volume_backups
SET 
definedTags = '{{ definedTags }}',
displayName = '{{ displayName }}',
freeformTags = '{{ freeformTags }}',
kmsKeyId = '{{ kmsKeyId }}'
WHERE 
volumeBackupId = '{{ volumeBackupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
RETURNING
id,
compartmentId,
definedTags,
displayName,
expirationTime,
freeformTags,
kmsKeyId,
lifecycleState,
sizeInGBs,
sizeInMBs,
sourceType,
sourceVolumeBackupId,
timeCreated,
timeRequestReceived,
type,
uniqueSizeInGBs,
uniqueSizeInMbs,
volumeId;

`DELETE` examples

delete

Deletes a volume backup.

DELETE FROM oci.block_storage.volume_backups
WHERE volumeBackupId = '{{ volumeBackupId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
;

Lifecycle Methods

change_compartment
copy_volume_backup

Moves a volume backup into a different compartment within the same tenancy. For information about moving resources between compartments, see [Moving Resources to a Different Compartment](/iaas/Content/Identity/Tasks/managingcompartments.htm#moveRes).

EXEC oci.block_storage.volume_backups.change_compartment 
@volumeBackupId='{{ volumeBackupId }}' --required, 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"compartmentId": "{{ compartmentId }}"
}'
;

Creates a volume backup copy in specified region. For general information about volume backups, see [Overview of Block Volume Service Backups](/iaas/Content/Block/Concepts/blockvolumebackups.htm)

EXEC oci.block_storage.volume_backups.copy_volume_backup 
@volumeBackupId='{{ volumeBackupId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@opc-request-id='{{ opc-request-id }}' 
@@json=
'{
"destinationRegion": "{{ destinationRegion }}", 
"displayName": "{{ displayName }}", 
"kmsKeyId": "{{ kmsKeyId }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​