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

このページでは、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 値は、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. [実行] をクリックします。オペレーションが完了すると、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. [実行] をクリックします。レスポンスには、長時間実行オペレーションのリストが含まれます。

長時間実行インスタンス オペレーションをキャンセルする

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. [実行] に移動します。そのオペレーションは削除されます。

データベース オペレーション

長時間実行データベース オペレーションには次のものがあります。

• 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. [実行] をクリックします。オペレーションが完了すると、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. [実行] をクリックします。レスポンスには、長時間実行オペレーションのリストが含まれます。

長時間実行データベース オペレーションをキャンセルする

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 メソッドと 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. [実行] をクリックします。オペレーションが停止します。

バックアップと復元オペレーション

長時間実行バックアップ オペレーションには次のものがあります。

• 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 メソッドと 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. [実行] をクリックします。レスポンスには、長時間実行オペレーションのリストが含まれます。

長時間実行バックアップオペレーションのキャンセル

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