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

本页面介绍了如何管理 Spanner 的生命周期 长时间运行的操作（使用 gcloud spanner operations 命令）和 操作 REST API。有些手术 可在 Google Cloud 控制台中完成。

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

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

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

• Spanner 客户端库
• gcloud 命令行工具
• Google Cloud 控制台

用于操作管理的 REST API 命令

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

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

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

实例操作

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

• projects.instances.create
• projects.instances.patch

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

使用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。

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

1. 前往 projects.instances.operations.get。

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

   projects/PROJECT-ID/instances/INSTANCE-NAME/operations/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

   您可以通过列出长时间运行的实例操作来检索实例操作的名称。

3. 点击 Execute。操作完成后，done 字段会设置为 true。

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

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

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

1. 前往 projects.instances.operations.list。

2. 对于 name，输入：

   projects/PROJECT-ID/instances/INSTANCE-NAME/operationsOPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

3. 点击 Execute。响应包含长时间运行的操作的列表。

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

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

1. 前往 projects.instances.operations.cancel。

2. 对于名称，请输入长时间运行的实例操作的名称，如 对长时间运行的实例操作的响应。

   projects/PROJECT-ID/instances/INSTANCE-NAME/operations/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

   您还可以通过列出长时间运行的实例操作来检索实例操作的名称。

3. 点击执行。

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

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

1. 点击“projects.instances.operations.delete”。

2. 对于名称，请输入长时间运行的实例操作的名称，如 对长时间运行的实例操作的响应。

   projects/<VAR>PROJECT-ID</VAR>/instances/<VAR>INSTANCE-NAME</VAR>/operations/<VAR>OPERATION-ID</VAR>
   

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

   您还可以通过列出长时间运行的实例操作来检索实例操作的名称。

3. 前往 Execute。操作已删除。

数据库操作

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

• projects.instances.databases.create
• projects.instances.databases.restore
• projects.instances.databases.updateDdl
• projects.instances.databaseOperations.list

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

使用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。

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

1. 前往 projects.instances.databases.operations.get。

2. 对于名称，请输入长时间运行的数据库操作的名称，如 对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。

   您还可以通过列出长时间运行的数据库操作来检索数据库操作的名称。

3. 点击 Execute。操作完成后，done 字段会设置为 true。

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

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

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

1. 前往 projects.instances.databases.operations.list。

2. 对于 name，输入：

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

3. 点击 Execute。响应包含长时间运行的操作的列表。

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

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

1. 前往 projects.instances.databases.operations.cancel。

2. 对于名称，请输入长时间运行的数据库操作的名称，如 对长时间运行的数据库操作的响应。

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

   您还可以通过列出长时间运行的数据库操作来检索数据库操作的名称。

3. 点击执行。

架构更新操作

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

• projects.instances.databases.updateDdl

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

控制台

1. 在 Spanner 导航菜单中，选择操作标签页。通过 操作页面会显示正在运行的操作的列表。

2. 在列表中找到架构操作。如果它仍在运行 结束时间列中的一个长条显示了符合以下条件的操作所占的百分比： 完成，如下图所示：

gcloud

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

1. 获取操作 ID：

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

   替换以下内容：

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

2. 运行 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

1. 获取操作 ID：

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

   替换以下内容：

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

2. 使用 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 可取消长时间运行的架构更新操作。

1. 获取操作 ID：

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

   替换以下内容：

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

2. 前往 projects.instances.databases.operations.cancel。

3. 对于名称，请输入长时间运行的架构更新操作的名称，如长时间运行的架构更新操作响应中所示。

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/operations/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • OPERATION-ID：操作 ID。

   您还可以通过列出长时间运行的实例操作来检索架构更新操作的名称。

4. 点击 Execute。操作停止运行。

备份和恢复操作

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

• projects.instances.backups.create
• projects.instances.databases.restore

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

控制台

备份

1. 在 Spanner 导航菜单中，选择操作标签页。通过 操作页面显示了当前正在运行的操作的列表。

2. 在列表中找到架构操作。如果仍在运行，结束时间列中的进度条会显示操作完成百分比，如下图所示：

恢复

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

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

gcloud

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

1. 获取操作 ID：

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

   替换以下内容：

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

2. 运行 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"
  }
}

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

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

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

1. 前往 projects.instances.backups.operations.list。

2. 对于 name，输入：

   projects/PROJECT-ID/instances/INSTANCE-NAME/backups/BACKUP-NAME/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • BACKUP-NAME：备份的名称。
   • OPERATION-ID：操作 ID。

3. 点击 Execute。响应包含长时间运行的操作的列表。

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

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

1. 前往 projects.instances.backups.operations.cancel。

2. 对于名称，请输入长时间运行的备份操作的名称，如 长时间运行的备份操作响应。

   projects/PROJECT-ID/instances/INSTANCE-NAME/backups/BACKUP-NAME/operations/OPERATION-ID

   替换以下内容：

   • PROJECT-ID：项目 ID。
   • INSTANCE-NAME：实例名称。
   • BACKUP-NAME：备份的名称。
   • OPERATION-ID：操作 ID。

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

3. 点击执行。