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

このページでは、オペレーション REST API を使用して Spanner の長時間実行オペレーションのライフサイクルを管理する方法について説明します。

長時間実行オペレーションとは、完了までに膨大な時間がかかる可能性があるメソッドの呼び出しです。Spanner はデータベース、インスタンス、バックアップの複数のアクションについて長時間実行オペレーションを作成します。その一例は、データベースを復元するメソッド projects.instances.databases.restoreです。

データベースを復元すると、Spanner サービスは復元の進行状況を追跡するための長時間実行オペレーションを作成します。Spanner では、長時間実行オペレーションの進行状況を確認できるオペレーション API が提供されます。長時間実行オペレーションの一覧表示やキャンセル、長時間実行インスタンスオペレーションの削除を行うこともできます。

以下を使用して、長時間実行オペレーションの確認と管理を行うことができます。

REST API を使用して長時間実行 Spanner オペレーションを管理する

次の REST メソッドを使用して、Spanner の長時間実行オペレーションを管理します。

操作	長時間実行データベースオペレーション	長時間実行インスタンスオペレーション
長時間実行オペレーションをキャンセルする	`cancel`	`cancel`
長時間実行オペレーションを削除する	未対応	サポート対象外
長時間実行オペレーションの進行状況を確認する	`get`	`get`
長時間実行オペレーションを一覧表示する	`list`	`list`

Spanner で REST を使用する方法については、REST で Spanner を使ってみるをご覧ください。

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

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

長時間実行データベースオペレーションの進行状況を確認する

projects.instances.databases.operations.get を使用して長時間実行データベースオペレーションの進行状況を確認する

たとえば、projects.instances.databases.create からのレスポンスは次のようになります。

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

レスポンスの一番上にある name 値は、Spanner サービスが projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/_auto_1492721321097206 という名前の長時間実行データベースオペレーションを作成したことを表します。

長時間実行データベースオペレーションの進行状況を確認するには:

[projects.instances.databases.operations.get] をクリックします。
[name] で、projects.instances.databases.create または projects.instances.databases.updateDdl へのレスポンスに表示されるとおりの長時間実行データベースオペレーション名を入力します。次に例を示します。

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/OPERATION-ID

以下を置き換えます。
- PROJECT-ID: プロジェクト ID。
- OPERATION-ID: オペレーション ID。
長時間実行データベースオペレーションを一覧表示して、データベースオペレーション名を取得します。
[実行] をクリックします。オペレーションが完了すると、done フィールドが true に設定されます。

継続的な更新を行うには、オペレーションが完了するまで繰り返し projects.instances.databases.operations.get メソッドを呼び出します。各リクエスト間でバックオフを使用します。たとえば、10 秒ごとにリクエストを発行します。

長時間実行データベースオペレーションを一覧表示する

projects.instances.databases.operations.list を使用すると、長時間実行データベースオペレーションを一覧表示できます。

projects.instances.databases.operations.list をクリックします。
[name] に以下のように入力します。

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations
[実行] をクリックします。レスポンスには、長時間実行オペレーションのリストが含まれます。

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

projects.instances.databases.operations.cancel を使用すると、長時間実行データベースオペレーションをキャンセルできます。

projects.instances.databases.operations.cancel をクリックします。
[name] で、長時間実行データベースオペレーションのレスポンスに表示されるとおりの長時間実行データベースオペレーション名を入力します。次に例を示します。

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/_auto_1492721321097206

（この値の代わりに、取得したオペレーション名を使用します）データベースオペレーション名は長時間実行データベースオペレーションの一覧表示で取得することもできます。
[Execute] をクリックします。

スキーマ更新オペレーション

長時間実行スキーマ更新オペレーションは次のとおりです。

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 は、データベースの名前に置き換えます。
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次のコマンドを実行して、ユーザーアカウントで CLI を使用します。gcloud init または gcloud auth login 。 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
               CREATE INDEX SongsBySingerAlbumSongName ON Songs(SingerId, AlbumId, SongName), INTERLEAVE IN Albums
_auto_op_234567                                                                                                      True   CreateDatabaseMetadata

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

gcloud

オペレーション ID を取得します。
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
以下を置き換えます。
- INSTANCE-NAME は、Spanner インスタンス名に置き換えます。
- DATABASE-NAME は、データベースの名前に置き換えます。
gcloud operations cancel を使用して、長時間実行スキーマ更新オペレーションをキャンセルします。
```
gcloud 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] をクリックします。
[name] で、長時間実行スキーマ更新オペレーションのレスポンスに表示されるとおりの長時間実行スキーマ更新オペレーション名を入力します。次に例を示します。

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/OPERATION-ID

以下を置き換えます。
- PROJECT-ID: プロジェクト ID。
- OPERATION-ID: オペレーション ID。
また、長時間実行インスタンスオペレーションを一覧表示して、スキーマ更新オペレーション名を取得することもできます。
[実行] をクリックします。オペレーションが停止します。

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

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

長時間実行バックアップまたは復元オペレーションの進行状況を確認する

コンソール

バックアップ

Spanner のナビゲーションメニューで、[オペレーション] タブを選択します。[オペレーション] ページに、現在実行中のオペレーションのリストが表示されます。
リストでスキーマオペレーションを見つけます。実行中の場合、[終了時間] 列の進行状況バーには、次の図に示すように、完了したオペレーションの割合が表示されます。

98% を示す進行状況インジケーターのスクリーンショット

復元

復元オペレーションの進行状況を確認するには、次の図に示すように、復元中に表示される進行状況インジケーターを確認します。

56% を示す進行状況インジケーターのスクリーンショット

オペレーションに時間がかかりすぎる場合は、キャンセルできます。詳細については、長時間実行インスタンスオペレーションをキャンセルするをご覧ください。

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 は、データベースの名前に置き換えます。
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）

次のコマンドを実行します。

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）

次のコマンドを実行します。

$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/test-instance/backups/example-db-backup-4/operations
[実行] をクリックします。レスポンスには、長時間実行オペレーションのリストが含まれます。

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

projects.instances.backups.operations.cancel を使用すると長時間実行バックアップオペレーションをキャンセルできます。

projects.instances.backups.operations.cancel をクリックします。
[name] で、長時間実行バックアップオペレーションのレスポンスに表示されるとおりの長時間実行バックアップオペレーション名を入力します。次に例を示します。

projects/project-id/instances/test-instance/backups/example-db-backup-4/operations/_auto_1492721321097206

_auto_1492721321097206 は、オペレーション ID に置き換えます。

長時間実行バックアップオペレーションを一覧表示して、バックアップオペレーション名を取得することもできます。
[Execute] をクリックします。

インスタンスオペレーション

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

長時間実行インスタンスオペレーションの進行状況を確認する

projects.instances.operations.get を使用すると、長時間実行インスタンスオペレーションの進行状況を確認できます。

たとえば、projects.instances.create からのレスポンスは次のようになります。

  {
    "name": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance/operations/<VAR>OPERATION-ID</VAR>",
    "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/PROJECT-ID/instances/test-instance/operations/<VAR>OPERATION-ID</VAR> という名前の長時間実行インスタンスオペレーションを作成したことを表します。

長時間実行インスタンスオペレーションの進行状況を確認するには:

[projects.instances.operations.get] をクリックします。
[name] で、projects.instances.create または projects.instances.patch へのレスポンスに表示されるとおりの長時間実行インスタンスオペレーション名を入力します。次に例を示します。

projects/PROJECT-ID/instances/test-instance/operations/OPERATION-ID

以下を置き換えます。
- PROJECT-ID: プロジェクト ID。
- OPERATION-ID: オペレーション ID。
インスタンスオペレーション名は長時間実行インスタンスオペレーションを一覧表示して取得することもできます。
[実行] をクリックします。オペレーションが完了すると、done フィールドが true に設定されます。

長時間実行インスタンスオペレーションの一覧表示

projects.instances.operations.list を使用すると、長時間実行インスタンスオペレーションを一覧表示できます。

projects.instances.operations.list をクリックします。
[name] に以下のように入力します。

プロジェクト/PROJECT-ID/instances/test-instance/operations
[実行] をクリックします。レスポンスには、長時間実行オペレーションのリストが含まれます。

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

projects.instances.operations.cancel を使用すると、長時間実行インスタンスオペレーションをキャンセルできます。

projects.instances.operations.cancel をクリックします。
[name] で、長時間実行インスタンスオペレーションのレスポンスに表示されるとおりの長時間実行インスタンスオペレーション名を入力します。次に例を示します。

projects/PROJECT-ID/instances/test-instance/operations/OPERATION-ID

以下を置き換えます。
- PROJECT-ID: プロジェクト ID。
- OPERATION-ID: オペレーション ID。
インスタンスオペレーション名は長時間実行インスタンスオペレーションを一覧表示して取得することもできます。
[Execute] をクリックします。

長時間実行インスタンスオペレーションを削除する

projects.instances.operations.delete を使用すると、長時間実行インスタンスオペレーションを削除できます。

projects.instances.operations.delete をクリックします。
[name] で、長時間実行インスタンスオペレーションのレスポンスに表示されるとおりの長時間実行インスタンスオペレーション名を入力します。次に例を示します。

projects/PROJECT-ID/instances/test-instance/operations/OPERATION-ID

以下を置き換えます。
- PROJECT-ID: プロジェクト ID。
- OPERATION-ID: オペレーション ID。
インスタンスオペレーション名は長時間実行インスタンスオペレーションを一覧表示して取得することもできます。
[実行] をクリックします。オペレーションが削除されます。

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

REST API を使用して長時間実行 Spanner オペレーションを管理する

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

長時間実行データベース オペレーションの進行状況を確認する

長時間実行データベース オペレーションを一覧表示する

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

スキーマ更新オペレーション

長時間実行スキーマ更新オペレーションの進行状況を確認する

コンソール

gcloud

REST v1

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

長時間実行スキーマ更新オペレーションを一覧表示する

gcloud

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

gcloud

REST V1

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

長時間実行バックアップまたは復元オペレーションの進行状況を確認する

コンソール

gcloud

REST v1

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

長時間実行バックアップまたは復元オペレーションを一覧表示する

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

インスタンス オペレーション

長時間実行インスタンス オペレーションの進行状況を確認する

長時間実行インスタンス オペレーションの一覧表示

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

長時間実行インスタンス オペレーションを削除する

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

長時間実行データベースオペレーションの進行状況を確認する

長時間実行データベースオペレーションを一覧表示する

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

インスタンスオペレーション

長時間実行インスタンスオペレーションの進行状況を確認する

長時間実行インスタンスオペレーションの一覧表示

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

長時間実行インスタンスオペレーションを削除する