管理和观察长时间运行的操作

本页面介绍如何使用 REST API 操作管理 Spanner 长时间运行的操作的生命周期。

长时间运行的操作是可能需要大量时间才能完成的方法调用。Spanner 会为多个实例、数据库和备份操作创建长时间运行的操作。例如，恢复数据库的方法 projects.instances.databases.restore。

在您恢复数据库时，Spanner 服务会创建一个长时间运行的操作来跟踪恢复进度。Spanner 提供了操作 API，可让您检查长时间运行的操作的进度。您还可以列出和取消长时间运行的操作，以及删除长时间运行的实例操作。

您可以通过以下方式查看和管理长时间运行的操作：

使用 REST API 管理长时间运行的 Spanner 操作

使用以下 REST 方法管理 Spanner 长时间运行的操作：

操作	长时间运行的数据库操作	长时间运行的实例操作
取消长时间运行的操作	`cancel`	`cancel`
删除长时间运行的操作	不支持	不受支持
查看长时间运行的操作的进度	`get`	`get`
列出长时间运行的操作	`list`	`list`

如需了解如何将 REST 与 Spanner 搭配使用，请参阅通过 REST 开始使用 Spanner。

数据库操作

以下是长时间运行的数据库操作。

查看长时间运行的数据库操作的进度

使用 projects.instances.databases.operations.get 检查长时间运行的数据库操作的进度。

例如，这是来自 projects.instances.databases.create 的响应：

  {
    "name": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance/databases/example-db/operations/_auto_1492721321097206",
    "metadata": {
      "@type": "type.googleapis.com/google.spanner.admin.database.v1.CreateDatabaseMetadata",
      "database": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance/databases/example-db"
    }
  }

响应顶部的 name 值表明 Spanner 服务创建了一个名为 projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/_auto_1492721321097206 的长时间运行的数据库操作。

如需检查长时间运行的数据库操作的进度，请执行以下操作：

点击“projects.instances.databases.operations.get”。
对于名称，请输入长时间运行的数据库操作的名称，如 projects.instances.databases.create 或 projects.instances.databases.updateDdl 的响应中所示。例如：

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/OPERATION-ID

替换以下内容：
- 将 PROJECT-ID 替换为项目 ID。
- 将 OPERATION-ID 替换为操作 ID。
通过列出长时间运行的数据库操作来检索数据库操作的名称。
点击执行。操作完成后，done 字段会设置为 true。

如需持续更新，请反复调用 projects.instances.databases.operations.get 方法，直到操作完成。在每个请求之间使用退避时间。例如，每 10 秒发出请求一次。

列出长时间运行的数据库操作

使用 projects.instances.databases.operations.list 可列出长时间运行的数据库操作。

点击 projects.instances.databases.operations.list。
对于 name，输入：

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations
点击执行。响应包含长时间运行的操作列表。

取消长时间运行的数据库操作

使用 projects.instances.databases.operations.cancel 可取消长时间运行的数据库操作。

点击 projects.instances.databases.operations.cancel。
对于名称，请输入长时间运行的数据库操作的名称，如长时间运行的数据库操作响应中所示。例如：

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/_auto_1492721321097206

（请使用您收到的操作名称，而不要使用此值。）您还可以通过列出长时间运行的数据库操作来检索数据库操作的名称。
点击执行。

架构更新操作

以下是长时间运行的架构更新操作。

projects.instances.databases.updateDdl

查看长时间运行的架构更新操作的进度

控制台

在 Spanner 导航菜单中，选择操作标签页。操作页面会显示当前正在运行的操作列表。
在列表中找到架构操作。如果操作仍在运行，结束时间列中的进度条会显示操作完成的百分比，如下图所示：

进度指示器显示 98% 的屏幕截图

gcloud

使用 gcloud spanner operations describe 检查操作的进度。

获取操作 ID：
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
替换以下内容：
- 将 INSTANCE-NAME 替换为 Spanner 实例名称。
- 将 DATABASE-NAME 替换为数据库的名称。

运行 gcloud spanner operations describe：

gcloud spanner operations describe OPERATION-ID\
--instance=INSTANCE-NAME \
--database=DATABASE-NAME

替换以下内容：

OPERATION-ID：您要检查的操作的操作 ID。
INSTANCE-NAME：Spanner 实例名称。
DATABASE-NAME：Spanner 数据库名称。

输出中的 progress 部分显示操作完成百分比。输出类似于以下内容：

done: true
metadata:
...
  progress:
  - endTime: '2022-03-01T00:28:06.691403Z'
    progressPercent: 100
    startTime: '2022-03-01T00:28:04.221401Z'
  - endTime: '2022-03-01T00:28:17.624588Z'
    startTime: '2022-03-01T00:28:06.691403Z'
    progressPercent: 100
...

REST v1

获取操作 ID：

gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

替换以下内容：

将 INSTANCE-NAME 替换为 Spanner 实例名称。
将 DATABASE-NAME 替换为数据库的名称。

在使用任何请求数据之前，请先进行以下替换：

project-id：项目 ID。
instance-id：实例 ID。
database-id：数据库 ID。
operation-id：操作 ID。

HTTP 方法和网址：

GET https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
...
    "progress": [
      {
        "progressPercent": 100,
        "startTime": "2023-05-27T00:52:27.366688Z",
        "endTime": "2023-05-27T00:52:30.184845Z"
      },
      {
        "progressPercent": 100,
        "startTime": "2023-05-27T00:52:30.184845Z",
        "endTime": "2023-05-27T00:52:40.750959Z"
      }
    ],
...
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

如果操作花费的时间过长，您可以取消操作。如需了解详情，请参阅取消长时间运行的架构更新操作。

列出长时间运行的架构更新操作

gcloud

gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

替换以下内容：

将 INSTANCE-NAME 替换为 Spanner 实例名称。
将 DATABASE-NAME 替换为数据库的名称。

输出类似于以下内容：

OPERATION-ID     STATEMENTS                                                                                          DONE   @TYPE
_auto_op_123456  CREATE INDEX SingersByFirstLastName ON Singers(FirstName, LastName)                                 False  UpdateDatabaseDdlMetadata
               CREATE INDEX SongsBySingerAlbumSongName ON Songs(SingerId, AlbumId, SongName), INTERLEAVE IN Albums
_auto_op_234567                                                                                                      True   CreateDatabaseMetadata

取消长时间运行的架构更新操作

gcloud

获取操作 ID：
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
替换以下内容：
- 将 INSTANCE-NAME 替换为 Spanner 实例名称。
- 将 DATABASE-NAME 替换为数据库的名称。
使用 gcloud operations cancel 取消长时间运行的架构更新操作。
```
gcloud operations cancel OPERATION-ID \
--instance=INSTANCE-NAME \
```
替换以下内容：
- OPERATION-ID：您要检查的操作的操作 ID。
- INSTANCE-NAME：Spanner 实例名称。

REST 版本 1

使用 projects.instances.databases.operations.cancel 可取消长时间运行的架构更新操作。

获取操作 ID：
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
替换以下内容：
- 将 INSTANCE-NAME 替换为 Spanner 实例名称。
- 将 DATABASE-NAME 替换为数据库的名称。
点击“projects.instances.databases.operations.cancel”。
对于名称，请输入长时间运行的架构更新操作的名称，如长时间运行的架构更新操作响应中所示。例如：

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/OPERATION-ID

替换以下内容：
- 将 PROJECT-ID 替换为项目 ID。
- 将 OPERATION-ID 替换为操作 ID。
您还可以列出长时间运行的实例操作，以检索架构更新操作的名称。
点击执行。操作停止运行。

备份和恢复操作

以下是长时间运行的备份操作。

查看长时间运行的备份或恢复操作的进度

控制台

备份

在 Spanner 导航菜单中，选择操作标签页。操作页面会显示当前正在运行的操作列表。
在列表中找到架构操作。如果操作仍在运行，结束时间列中的进度条会显示操作完成的百分比，如下图所示：

进度指示器显示 98% 的屏幕截图

恢复

如需检查恢复操作的进度，请查看恢复期间显示的进度指示器，如下图所示：

进度指示器显示 56% 的屏幕截图

如果操作花费的时间过长，您可以取消操作。如需了解详情，请参阅取消长时间运行的实例操作。

gcloud

使用 gcloud spanner operations describe 检查备份或恢复操作的进度。

获取操作 ID：
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
替换以下内容：
- 将 INSTANCE-NAME 替换为 Spanner 实例名称。
- 将 DATABASE-NAME 替换为数据库的名称。

运行 gcloud spanner operations describe：

gcloud spanner operations describe OPERATION-ID\
--instance=INSTANCE-NAME \
--database=DATABASE-NAME

替换以下内容：

OPERATION-ID：您要检查的操作的操作 ID。
INSTANCE-NAME：Spanner 实例名称。
DATABASE-NAME：Spanner 数据库名称。

输出中的 progress 部分显示操作完成百分比。输出类似于以下内容：

done: true
metadata:
...
  progress:
  - endTime: '2022-03-01T00:28:06.691403Z'
    progressPercent: 100
    startTime: '2022-03-01T00:28:04.221401Z'
  - endTime: '2022-03-01T00:28:17.624588Z'
    startTime: '2022-03-01T00:28:06.691403Z'
    progressPercent: 100
...

REST v1

获取操作 ID：

  gcloud spanner operations list --instance=INSTANCE-NAME 

  --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

替换以下内容：

将 INSTANCE-NAME 替换为 Spanner 实例名称。
将 DATABASE-NAME 替换为数据库的名称。

在使用任何请求数据之前，请先进行以下替换：

project-id：项目 ID。
instance-id：实例 ID。
database-id：数据库 ID。
operation-id：操作 ID。

HTTP 方法和网址：

GET https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

执行以下命令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id"

PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id" | Select-Object -Expand Content

您应该收到类似以下内容的 JSON 响应：

{
...
    "progress": [
      {
        "progressPercent": 100,
        "startTime": "2023-05-27T00:52:27.366688Z",
        "endTime": "2023-05-27T00:52:30.184845Z"
      },
      {
        "progressPercent": 100,
        "startTime": "2023-05-27T00:52:30.184845Z",
        "endTime": "2023-05-27T00:52:40.750959Z"
      }
    ],
...
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

如果操作花费的时间过长，您可以取消操作。如需了解详情，请参阅取消长时间运行的备份操作。

列出长时间运行的备份或恢复操作

使用 projects.instances.backups.operations.list 列出单个备份上的操作，或使用 projects.instances.backupOperations.list 列出实例中的所有备份操作。

点击 projects.instances.backups.operations.list。
对于 name，输入：

projects/project-id/instances/test-instance/backups/example-db-backup-4/operations
点击执行。响应包含长时间运行的操作列表。

取消长时间运行的备份操作

使用 projects.instances.backups.operations.cancel 可取消长时间运行的备份操作。

点击 projects.instances.backups.operations.cancel。
对于名称，请输入长时间运行的备份操作响应中显示的长时间运行的备份操作的名称。例如：

projects/project-id/instances/test-instance/backups/example-db-backup-4/operations/_auto_1492721321097206

将 _auto_1492721321097206 替换为您的操作 ID。

您可以通过列出长时间运行的备份操作来检索备份操作的名称。
点击执行。

实例操作

以下是长时间运行的实例操作。

查看长时间运行的实例操作的进度

使用 projects.instances.operations.get 检查长时间运行的实例操作的进度。

例如，这是来自 projects.instances.create 的响应：

  {
    "name": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance/operations/<VAR>OPERATION-ID</VAR>",
    "metadata": {
      "@type": "type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceMetadata",
      "instance": {
        "name": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance",
        "config": "projects/<VAR>PROJECT-ID</VAR>/instanceConfigs/regional-us-central1",
        "displayName": "Test Instance",
        "nodeCount": 1,
        "state": "READY"
      },
      "startTime": "2017-04-24T22:45:41.130854Z"
    }
  }

响应顶部的 name 值表明 Spanner 服务创建了名为 projects/PROJECT-ID/instances/test-instance/operations/<VAR>OPERATION-ID</VAR> 的长时间运行的实例操作。

如需检查长时间运行的实例操作的进度，请执行以下操作：

点击“projects.instances.operations.get”。
对于名称，请输入长时间运行的实例操作的名称，如 projects.instances.create 或 projects.instances.patch 的响应中所示。例如：

projects/PROJECT-ID/instances/test-instance/operations/OPERATION-ID

替换以下内容：
- 将 PROJECT-ID 替换为项目 ID。
- 将 OPERATION-ID 替换为操作 ID。
您可以通过列出长时间运行的实例操作来检索实例操作的名称。
点击执行。操作完成后，done 字段会设置为 true。

如需持续更新，请反复调用 projects.instances.databases.operations.get 方法，直到操作完成。在每个请求之间使用退避时间。例如，每 10 秒发出请求一次。

列出长时间运行的实例操作

使用 projects.instances.operations.list 可列出长时间运行的实例操作。

点击 projects.instances.operations.list。
对于 name，输入：

projects/PROJECT-ID/instances/test-instance/operations
点击执行。响应包含长时间运行的操作列表。

取消长时间运行的实例操作

使用 projects.instances.operations.cancel 可取消长时间运行的实例操作。

点击 projects.instances.operations.cancel。
对于名称，请输入长时间运行的实例操作的名称，如长时间运行的实例操作响应中所示。例如：

projects/PROJECT-ID/instances/test-instance/operations/OPERATION-ID

替换以下内容：
- 将 PROJECT-ID 替换为项目 ID。
- 将 OPERATION-ID 替换为操作 ID。
您可以通过列出长时间运行的实例操作来检索实例操作的名称。
点击执行。

删除长时间运行的实例操作

使用 projects.instances.operations.delete 可删除长时间运行的实例操作。

点击 projects.instances.operations.delete。
对于名称，请输入长时间运行的实例操作的名称，如长时间运行的实例操作响应中所示。例如：

projects/PROJECT-ID/instances/test-instance/operations/OPERATION-ID

替换以下内容：
- 将 PROJECT-ID 替换为项目 ID。
- 将 OPERATION-ID 替换为操作 ID。
您可以通过列出长时间运行的实例操作来检索实例操作的名称。
点击执行。该操作会被删除。