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

本页介绍了如何使用 gcloud spanner operations 命令和操作 REST API 来管理 Spanner 长时间运行的操作的生命周期。您也可以在 Google Cloud 控制台中执行某些程序。

长时间运行的操作是可能需要大量时间才能完成的方法调用。Spanner 会为多个实例、数据库和备份操作创建长时间运行的操作。用于恢复数据库的方法 projects.instances.databases.restore 就是这样一个例子。恢复数据库时，Spanner 服务会创建长时间运行的操作来跟踪恢复进度。如果操作耗时超出预期，您可以使用 gcloud 检查操作进度。如果操作没有响应，您可以使用 gcloud 取消该操作。

Spanner 提供了一些操作 API，您可利用它们检查长时间运行的操作的进度。您还可以列出并取消长时间运行的操作，以及删除长时间运行的实例操作。

您可以使用以下工具检查和管理长时间运行的操作：

用于操作管理的 REST API 命令

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

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

如需了解如何将 REST 与 Spanner 搭配使用，请参阅 Spanner 使用入门（使用 REST）。

实例操作

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

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

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

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

  {
    "name": "projects/test01/instances/test-instance/operations/_auto_1492721321097206",
    "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/test01/instances/test-instance/operations/_auto_1492721321097206 的长时间运行的实例操作。

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

前往 projects.instances.operations.get。
对于名称，请输入长时间运行的实例操作的名称，如 projects.instances.create 或 projects.instances.patch 的响应中所示。例如：
```
projects/PROJECT-ID/instances/INSTANCE-NAME/operations/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
您可以通过列出长时间运行的实例操作来检索实例操作的名称。
点击 Execute。操作完成后，done 字段将设置为 true。

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

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

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

前往 projects.instances.operations.list。
对于 name，输入：
```
projects/PROJECT-ID/instances/INSTANCE-NAME/operationsOPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
点击 Execute。响应包含长时间运行的操作的列表。

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

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

前往 projects.instances.operations.cancel。
对于名称，请输入长时间运行的实例操作的名称，如长时间运行的实例操作响应中所示。
```
projects/PROJECT-ID/instances/INSTANCE-NAME/operations/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
您还可以通过列出长时间运行的实例操作来检索实例操作的名称。
点击执行。

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

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

点击 projects.instances.operations.delete。
对于名称，请输入长时间运行的实例操作的名称，如长时间运行的实例操作响应中所示。
```
projects/<VAR>PROJECT-ID</VAR>/instances/<VAR>INSTANCE-NAME</VAR>/operations/<VAR>OPERATION-ID</VAR>
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
您还可以通过列出长时间运行的实例操作来检索实例操作的名称。
前往执行。相应操作已删除。

数据库操作

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

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

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

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

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

响应最上方的 name 表明 Spanner 服务创建了一个名为 projects/test01/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/INSTANCE-NAME/databases/example-db/operations/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
您还可以通过列出长时间运行的数据库操作来检索数据库操作的名称。
点击 Execute。操作完成后，done 字段将设置为 true。

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

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

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

前往 projects.instances.databases.operations.list。
对于 name，输入：
```
projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
点击 Execute。响应包含长时间运行的操作的列表。

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

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

前往 projects.instances.databases.operations.cancel。
对于名称，请输入长时间运行的数据库操作的名称，如长时间运行的数据库操作响应中所示。
```
projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
您还可以通过列出长时间运行的数据库操作来检索数据库操作的名称。
点击执行。

架构更新操作

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

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：实例名称。
- 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
_auto_op_234567  CREATE INDEX SongsBySingerAlbumSongName ON Songs(SingerId, AlbumId, SongName), INTERLEAVE IN Albums  True   CreateDatabaseMetadata

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

gcloud

获取操作 ID：

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

替换以下内容：

INSTANCE-NAME：Spanner 实例名称。
DATABASE-NAME：数据库的名称。

使用 gcloud spanner operations cancel 可取消长时间运行的架构更新操作。
```
gcloud spanner operations cancel OPERATION-ID \
 --instance=INSTANCE-NAME
```
替换以下内容：
- OPERATION-ID：要检查的操作的 ID。
- INSTANCE-NAME：Spanner 实例名称。

REST V1

使用 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/INSTANCE-NAME/databases/example-db/operations/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- OPERATION-ID：操作 ID。
您还可以通过列出长时间运行的实例操作来检索架构更新操作的名称。
点击 Execute。操作停止运行。

备份和恢复操作

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

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

控制台

备份

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

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

恢复

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

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

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

gcloud

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

获取操作 ID：
```
gcloud spanner operations list \
--instance=INSTANCE-NAME \
--database=DATABASE-NAME \
--type=TYPE
```
替换以下内容：
- INSTANCE-NAME：Spanner 实例名称。
- DATABASE-NAME：数据库的名称。
- TYPE：操作的类型。可能的值有 BACKUP 和 DATABASE_RESTORE。

运行 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/INSTANCE-NAME/backups/BACKUP-NAME/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- BACKUP-NAME：备份的名称。
- OPERATION-ID：操作 ID。
点击 Execute。响应包含长时间运行的操作的列表。

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

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

前往 projects.instances.backups.operations.cancel。
对于名称，请输入长时间运行的备份操作响应中显示的长时间运行的备份操作的名称。
```
projects/PROJECT-ID/instances/INSTANCE-NAME/backups/BACKUP-NAME/operations/OPERATION-ID
```
替换以下内容：
- PROJECT-ID：项目 ID。
- INSTANCE-NAME：实例名称。
- BACKUP-NAME：备份的名称。
- OPERATION-ID：操作 ID。
您还可以通过列出长时间运行的备份操作来检索备份操作的名称。
点击执行。