This page describes how to manage the lifecycle of a Cloud Spanner long-running operation using operations APIs.
Long-running operations are method calls that may take a substantial amount of
time to complete. Cloud Spanner creates long-running operations for several
instance, database, and backup actions. An example is the method to restore a database,
projects.instances.databases.restore
.
When you restore a database, the Cloud Spanner service creates a long-running operation to track restore progress.
Cloud Spanner provides operations APIs that allow you to check the status of
long-running operations. You can also list and cancel long-running operations,
as well as delete long-running instance operations.
This page describe how to manage long-running operations with the REST API. But, you can also manage long-running operations with:
- Cloud Spanner client libraries
- The
gcloud
command-line tool - The Spanner page in the Google Cloud Console
Manage your Cloud Spanner long-running operations using these methods:
Action | Long-running database operations | Long-running backup operations | Long-running instance operations |
---|---|---|---|
Cancel a long-running operation | cancel |
cancel |
cancel |
Delete a long-running operation | Unsupported | Unsupported | delete |
Get the status of a long-running operation | get |
get |
get |
List long-running operations | list |
list |
list |
Database operations
The following are long-running database operations.
projects.instances.databases.create
projects.instances.databases.restore
projects.instances.databases.updateDdl
projects.instances.databaseOperations.list
Get the status of a long-running database operation
Use projects.instances.databases.operations.get
to get the status of a long-running database operation.
As an example, this is a response from
projects.instances.databases.create
:
{
"name": "projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206",
"metadata": {
"@type": "type.googleapis.com/google.spanner.admin.database.v1.CreateDatabaseMetadata",
"database": "projects/[PROJECT_ID]/instances/test-instance/databases/example-db"
}
}
The name
value at the top of the response shows the Cloud Spanner service
created a long-running database operation named
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206
.
To get the status of the long-running database operation:
- Click
projects.instances.databases.operations.get
. For name, enter the long-running database operation name as shown in the response to
projects.instances.databases.create
orprojects.instances.databases.updateDdl
. For example:projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206
(Use the operation name you received instead of this value.) You can also retrieve the database operation name by listing long-running database operations.
Click Execute and view the response. When an operation is done, the
done
field will be set totrue
.
To poll a long-running database operation, repeatedly invoke the
projects.instances.databases.operations.get
method until the operation is
done. Use a backoff between each poll request. For example, poll every 10
seconds.
List long-running database operations
Use projects.instances.databases.operations.list
to list long-running database operations.
- Click
projects.instances.databases.operations.list
. For name, enter:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations
Click Execute. The response contains the long-running database operations.
Cancel a long-running database operation
Use projects.instances.databases.operations.cancel
to cancel a long-running database operation.
- Click
projects.instances.databases.operations.cancel
. For name, enter the long-running database operation name as shown in the long-running database operation response. For example:
projects/[PROJECT_ID]/instances/test-instance/databases/example-db/operations/_auto_1492721321097206
(Use the operation name you received instead of this value.) You can also retrieve the database operation name by listing long-running database operations.
Click Execute.
Backup operations
The following are long-running backup operations.
Get the status of a long-running backup operation
Use projects.instances.backups.operations.get
to get the status of a long-running backup operation.
As an example, this is a response from
projects.instances.backups.create
:
{
"name": "projects/[PROJECT_ID]/instances/test-instance/backups/example-db-backup-5/operations/_auto_1492721321097206",
"metadata": {
"@type": "type.googleapis.com/google.spanner.admin.database.v1.CreateBackupMetadata",
"name": "projects/[PROJECT_ID]/instances/test-instance/backup/example-db-backup-5"
}
}
The name
value at the top of the response shows the Cloud Spanner service
created a long-running backup operation named
projects/[PROJECT_ID]/instances/test-instance/backups/example-db/operations/_auto_op_0cf69250b487c2f7
.
To get the status of the long-running backup operation:
- Click
projects.instances.backups.operations.get
. For name, enter the long-running backup operation name as shown in the response to
projects.instances.backups.create
. For example:projects/[PROJECT_ID]/instances/test-instance/backups/example-db/operations/_auto_1492721321097206
(Use the operation name you received instead of this value.) You can also retrieve the backup operation name by listing long-running backup operations.
Click Execute and view the response. When an operation is done, the
done
field will be set totrue
.
To poll a long-running backup operation, repeatedly invoke the
projects.instances.backups.operations.get
method until the operation is
done. Use a backoff between each poll request. For example, poll every 10
seconds.
List long-running backup operations
Use projects.instances.backups.operations.list
to list the operations on a single backup or projects.instances.backupOperations.list
to list all backup operations in the instance.
- Click
projects.instances.backups.operations.list
. For name, enter:
projects/[PROJECT_ID]/instances/test-instance/backups/example-db-backup-4/operations
Click Execute. The response contains the long-running operations.
Cancel a long-running backup operation
Use projects.instances.backups.operations.cancel
to cancel a long-running backup operation.
- Click
projects.instances.backups.operations.cancel
. For name, enter the long-running backup operation name as shown in the long-running backup operation response. For example:
projects/[PROJECT_ID]/instances/test-instance/backups/example-db-backup-4/operations/_auto_1492721321097206
(Use the operation name you received instead of this value.) You can also retrieve the backup operation name by listing long-running backup operations.
Click Execute.
Instance operations
The following are long-running instance operations.
Get the status of a long-running instance operation
Use projects.instances.operations.get
to get the status of a long-running instance operation.
As an example, this is a response from
projects.instances.create
:
{
"name": "projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e",
"metadata": {
"@type": "type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceMetadata",
"instance": {
"name": "projects/[PROJECT_ID]/instances/test-instance",
"config": "projects/[PROJECT_ID]/instanceConfigs/regional-us-central1",
"displayName": "Test Instance",
"nodeCount": 1,
"state": "READY"
},
"startTime": "2017-04-24T22:45:41.130854Z"
}
}
The name
value at the top of the response shows the Cloud Spanner service
created a long-running instance operation named
projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
.
To get the status of the long-running instance operation:
- Click
projects.instances.operations.get
. For name, enter the long-running instance operation name as shown in the response to
projects.instances.create
orprojects.instances.patch
. For example:projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
(Use the operation name you received instead of this value.) You can also retrieve the instance operation name by listing long-running instance operations.
Click Execute and view the response. When an operation is done, the
done
field will be set totrue
.
To poll a long-running instance operation, repeatedly invoke the
projects.instances.operations.get
method until the operation is done. Use a
backoff between each poll request. For example, poll every 10 seconds.
List long-running instance operations
Use projects.instances.operations.list
to list long-running instance operations.
- Click
projects.instances.operations.list
. For name, enter:
projects/[PROJECT_ID]/instances/test-instance/operations
Click Execute. The response contains the long-running instance operations.
Cancel a long-running instance operation
Use projects.instances.operations.cancel
to cancel a long-running instance operation.
- Click
projects.instances.operations.cancel
. For name, enter the long-running instance operation name as shown in the long-running instance operation response. For example:
projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
(Use the operation name you received instead of this value.) You can also retrieve the instance operation name by listing long-running instance operations.
Click Execute.
Delete a long-running instance operation
Use projects.instances.operations.delete
to delete a long-running instance operation.
- Click
projects.instances.operations.delete
. For name, enter the long-running instance operation name as shown in the long-running instance operation response. For example:
projects/[PROJECT_ID]/instances/test-instance/operations/9af0cf8c1e123a2e
(Use the operation name you received instead of this value.) You can also retrieve the instance operation name by listing long-running instance operations.
Click Execute.