管理及觀察長時間執行的作業

本頁說明如何使用 gcloud spanner operations 指令和 operations REST API，管理 Spanner 長時間執行作業的生命週期。部分程序也可以在 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. 在「name」(名稱) 中，輸入 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. 在「name」(名稱) 中，輸入長時間執行的執行個體作業回應中所顯示長時間執行的執行個體作業名稱。

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

   更改下列內容：

   • PROJECT-ID：專案 ID。
   • INSTANCE-NAME：執行個體名稱。
   • OPERATION-ID：作業 ID。

   您也可以列出長時間執行的執行個體作業，以擷取執行個體作業名稱。

3. 按一下 [Execute] (執行)。

刪除長時間執行的執行個體作業

使用 projects.instances.operations.delete 刪除長時間執行的執行個體作業。

1. 按一下 [projects.instances.operations.delete]。

2. 在「name」(名稱) 中，輸入長時間執行的執行個體作業回應中所顯示長時間執行的執行個體作業名稱。

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

   更改下列內容：

   • PROJECT-ID：專案 ID。
   • INSTANCE-NAME：執行個體名稱。
   • OPERATION-ID：作業 ID。

   您也可以列出長時間執行的執行個體作業，以擷取執行個體作業名稱。

3. 前往「執行」。作業已刪除。

資料庫作業

下列作業屬於長時間執行的資料庫作業。

• 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. 在「name」中，輸入 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. 在「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.updateDdl

查看長時間執行的結構定義更新作業進度

控制台

1. 在 Spanner 導覽選單中，選取「作業」分頁標籤。「Operations」(作業) 頁面會顯示正在執行的作業清單。

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. 在「name」中，輸入長時間執行的結構定義更新作業回應中顯示的長時間執行結構定義更新作業名稱。

   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 導覽選單中，選取「作業」分頁標籤。「Operations」(作業) 頁面會顯示目前正在執行的作業清單。

2. 在清單中找出結構定義作業。如果作業仍在執行中，「結束時間」欄中的進度列會顯示作業完成百分比，如下圖所示：

還原

如要查看還原作業的進度，請參閱還原期間顯示的進度指標，如下圖所示：

如果作業時間過長，可以取消作業。詳情請參閱「取消長時間執行的執行個體作業」。

gcloud

使用 gcloud spanner operations describe 檢查備份或還原作業的進度。

1. 取得作業 ID：

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

   更改下列內容：

   • INSTANCE-NAME：Spanner 執行個體名稱。
   • DATABASE-NAME：資料庫名稱。
   • TYPE：作業類型。可能的值為 BACKUP 和 DATABASE_RESTORE。

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. 在「name」中，輸入長時間執行備份作業回應中顯示的長時間執行備份作業名稱。

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

   更改下列內容：

   • PROJECT-ID：專案 ID。
   • INSTANCE-NAME：執行個體名稱。
   • BACKUP-NAME：備份名稱。
   • OPERATION-ID：作業 ID。

   您也可以列出長時間執行的備份作業，以擷取備份作業名稱。

3. 按一下 [Execute] (執行)。