長時間実行オペレーションを管理し監視する

このページでは、gcloud spanner 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

Spanner で REST を使用する方法については、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 値は、Cloud 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. [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. [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 のナビゲーション メニューで [オペレーション] タブをクリックします。[オペレーション] ページに、現在実行中のオペレーションのリストが表示されます。

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 メソッドと URL:

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=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 メソッドと URL:

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. [Execute] をクリックします。