Method: projects.instances.backups.copy

Starts copying a Cloud Spanner Backup. The returned backup long-running operation will have a name of the formatprojects/<project>/instances/<instance>/backups/<backup>/operations/<operationId> and can be used to track copying of the backup. The operation is associated with the destination backup. The metadata field type isCopyBackupMetadata. The response field type isBackup, if successful. Cancelling the returned operation will stop the copying and delete the destination backup. Concurrent backups.copy requests can run on the same source backup.

HTTP request


POST https://spanner.googleapis.com/v1/{parent=projects/*/instances/*}/backups:copy

The URLs usegRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The name of the destination instance that will contain the backup copy. Values are of the form:projects/<project>/instances/<instance>.

Authorization requires the followingIAM permission on the specified resourceparent:

  • spanner.backups.create

Request body

The request body contains data with the following structure:

JSON representation
{"backupId":string,"sourceBackup":string,"expireTime":string,"encryptionConfig":{object (CopyBackupEncryptionConfig)}}
Fields
backupId

string

Required. The id of the backup copy. ThebackupId appended toparent forms the full backup_uri of the formprojects/<project>/instances/<instance>/backups/<backup>.

sourceBackup

string

Required. The source backup to be copied. The source backup needs to be in READY state for it to be copied. Once backups.copy is in progress, the source backup cannot be deleted or cleaned up on expiration until backups.copy is finished. Values are of the form:projects/<project>/instances/<instance>/backups/<backup>.

Authorization requires the followingIAM permission on the specified resourcesourceBackup:

  • spanner.backups.copy
expireTime

string (Timestamp format)

Required. The expiration time of the backup in microsecond granularity. The expiration time must be at least 6 hours and at most 366 days from thecreateTime of the source backup. Once theexpireTime has passed, the backup is eligible to be automatically deleted by Cloud Spanner to free the resources used by the backup.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples:"2014-10-02T15:01:23Z","2014-10-02T15:01:23.045123456Z" or"2014-10-02T15:01:23+05:30".

encryptionConfig

object (CopyBackupEncryptionConfig)

Optional. The encryption configuration used to encrypt the backup. If this field is not specified, the backup will use the same encryption configuration as the source backup by default, namelyencryptionType =USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION.

Response body

If successful, the response body contains an instance ofOperation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/spanner.admin
  • https://www.googleapis.com/auth/cloud-platform

For more information, see theAuthentication Overview.

IAM Permissions

Requires the followingIAM permission on theparent resource:

  • spanner.backups.create

Requires the followingIAM permission on thesourceBackup resource:

  • spanner.backups.copy

For more information, see theIAM documentation.

CopyBackupEncryptionConfig

Encryption configuration for the copied backup.

JSON representation
{"encryptionType":enum (EncryptionType),"kmsKeyName":string,"kmsKeyNames":[string]}
Fields
encryptionType

enum (EncryptionType)

Required. The encryption type of the backup.

kmsKeyName

string

Optional. This field is maintained for backwards compatibility. For new callers, we recommend usingkmsKeyNames to specify the KMS key. Only usekmsKeyName if the location of the KMS key matches the database instance's configuration (location) exactly. For example, if the KMS location is inus-central1 ornam3, then the database instance must also be inus-central1 ornam3.

The Cloud KMS key that is used to encrypt and decrypt the restored database. Set this field only whenencryptionType isCUSTOMER_MANAGED_ENCRYPTION. Values are of the formprojects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kmsKeyName>.

kmsKeyNames[]

string

Optional. Specifies the KMS configuration for the one or more keys used to protect the backup. Values are of the formprojects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kmsKeyName>. KMS keys specified can be in any order.

The keys referenced bykmsKeyNames must fully cover all regions of the backup's instance configuration. Some examples:

  • For regional (single-region) instance configurations, specify a regional location KMS key.
  • For multi-region instance configurations of typeGOOGLE_MANAGED, either specify a multi-region location KMS key or multiple regional location KMS keys that cover all regions in the instance configuration.
  • For an instance configuration of typeUSER_MANAGED, specify only regional location KMS keys to cover each region in the instance configuration. Multi-region location KMS keys aren't supported forUSER_MANAGED type instance configurations.

EncryptionType

Encryption types for the backup.

Enums
ENCRYPTION_TYPE_UNSPECIFIEDUnspecified. Do not use.
USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTIONThis is the default option forbackups.copy whenencryptionConfig is not specified. For example, if the source backup is usingCustomer_Managed_Encryption, the backup will be using the same Cloud KMS key as the source backup.
GOOGLE_DEFAULT_ENCRYPTIONUse Google default encryption.
CUSTOMER_MANAGED_ENCRYPTIONUse customer managed encryption. If specified, eitherkmsKeyName orkmsKeyNames must contain valid Cloud KMS keys.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-12 UTC.