Gerenciar e observar operações de longa duração

Nesta página, descrevemos como gerenciar o ciclo de vida de uma operação de longa duração do Spanner usando a API REST de operações.

Operações de longa duração são chamadas de método que podem demorar para serem concluídas. O Spanner cria operações de longa duração para várias ações de instância, banco de dados e backup. Um exemplo é o método para restaurar um banco de dados, projects.instances.databases.restore.

Quando você restaura um banco de dados, o serviço Spanner cria uma operação de longa duração para acompanhar o progresso da restauração. O Spanner fornece APIs de operações que permitem verificar o progresso de operações de longa duração. Também é possível listar e cancelar operações de longa duração e excluir operações de instâncias de longa duração.

É possível verificar e gerenciar operações de longa duração com o seguinte:

Bibliotecas de cliente do Spanner
A ferramenta de linha de comando gcloud
no console do Google Cloud;

Gerenciar operações de longa duração do Spanner com a API REST

Gerencie suas operações de longa duração do Spanner usando os seguintes métodos REST:

Ação	Operações de banco de dados de longa duração	Operações de instância de longa duração
Cancelar uma operação de longa duração	`cancel`	`cancel`
Excluir uma operação de longa duração	Não compatível	Sem suporte
Verificar o progresso de uma operação de longa duração	`get`	`get`
Listar operações de longa duração	`list`	`list`

Para informações sobre como usar o REST com o Spanner, consulte Primeiros passos com o Spanner usando REST.

Operações de banco de dados

Veja abaixo as operações de banco de dados de longa duração.

Verificar o progresso de uma operação de banco de dados de longa duração

Use projects.instances.databases.operations.get para verificar o progresso de uma operação de banco de dados de longa duração.

Como exemplo, esta é uma resposta de 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"
    }
  }

O valor name na parte superior da resposta mostra que o serviço do Spanner criou uma operação de banco de dados de longa duração chamada projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/_auto_1492721321097206.

Para verificar o progresso da operação do banco de dados de longa duração:

Clique em projects.instances.databases.operations.get.
Para name, insira o nome da operação de banco de dados de longa duração, conforme mostrado na resposta para projects.instances.databases.create ou projects.instances.databases.updateDdl. Exemplo:

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

Substitua:
- PROJECT-ID pelo ID do projeto.
- OPERATION-ID pelo ID de operações.
recupere o nome da operação do banco de dados listando operações de banco de dados de longa duração.
Clique em Executar. Quando uma operação é concluída, o campo done é definido como true.

Para receber atualizações contínuas, invoque repetidamente o método projects.instances.databases.operations.get até que a operação seja concluída. Use uma espera entre cada solicitação. Por exemplo, faça uma solicitação a cada 10 segundos.

Listar operações de banco de dados de longa duração

Use projects.instances.databases.operations.list para listar operações de banco de dados de longa duração.

Clique em projects.instances.databases.operations.list.
Para o nome, insira:

projects/PROJECT-ID/instances/test-instance/databases/example-db/operations
Clique em Executar. A resposta contém uma lista de operações de longa duração.

Cancelar uma operação de banco de dados de longa duração

Use projects.instances.databases.operations.cancel para cancelar uma operação de banco de dados de longa duração.

Clique em projects.instances.databases.operations.cancel.
Para name, insira o nome da operação do banco de dados de longa duração, como mostrado na resposta de operação do banco de dados de longa duração. Exemplo:

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

Use o nome da operação que você recebeu em vez desse valor. Também é possível recuperar o nome da operação do banco de dados listando as operações de banco de dados de longa execução.
Clique em Executar.

Operações de atualização de esquema

Veja a seguir as operações de atualização de esquema de longa duração.

projects.instances.databases.updateDdl

Verificar o progresso de uma operação de atualização de esquema de longa duração

Console

No menu de navegação do Spanner, selecione a guia Operações. A página Operações mostra uma lista das operações em execução no momento.
Encontre a operação do esquema na lista. Se ela ainda estiver em execução, a barra de progresso na coluna Horário de término vai mostrar a porcentagem da operação concluída, conforme mostrado na imagem a seguir:

Captura de tela do indicador de progresso mostrando 98%

gcloud

Use gcloud spanner operations describe para verificar o progresso de uma operação.

Consiga o ID da operação:
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
Substitua:
- INSTANCE-NAME pelo nome da instância do Spanner.
- DATABASE-NAME pelo nome do banco de dados.

Execute gcloud spanner operations describe:

gcloud spanner operations describe OPERATION-ID\
--instance=INSTANCE-NAME \
--database=DATABASE-NAME

Substitua:

OPERATION-ID: o ID da operação que você quer verificar.
INSTANCE-NAME: o nome da instância do Spanner.
DATABASE-NAME: o nome do banco de dados do Spanner.

A seção progress na saída mostra a porcentagem da operação concluída. A resposta será semelhante a:

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

Consiga o ID da operação:

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

Substitua:

INSTANCE-NAME pelo nome da instância do Spanner.
DATABASE-NAME pelo nome do banco de dados.

Antes de usar os dados da solicitação, faça as substituições a seguir:

project-id: o ID do projeto.
instance-id: o ID da instância
database-id: o ID do banco de dados.
operation-id: o ID da operação.

Método HTTP e URL:

GET https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

{
...
    "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"
  }
}

Se a operação demorar muito, será possível cancelá-la. Para mais informações, consulte Cancelar uma operação de atualização de esquema de longa duração.

Listar operações de atualização de esquema de longa duração

gcloud

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

Substitua:

INSTANCE-NAME pelo nome da instância do Spanner.
DATABASE-NAME pelo nome do banco de dados.

A resposta será semelhante a:

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

Cancelar uma operação de atualização de esquema de longa duração

gcloud

Consiga o ID da operação:
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
Substitua:
- INSTANCE-NAME pelo nome da instância do Spanner.
- DATABASE-NAME pelo nome do banco de dados.
Use o gcloud operations cancel para cancelar uma operação de atualização de esquema de longa duração.
```
gcloud operations cancel OPERATION-ID \
--instance=INSTANCE-NAME \
```
Substitua:
- OPERATION-ID: o ID da operação que você quer verificar.
- INSTANCE-NAME: o nome da instância do Spanner.

REST V1

Use projects.instances.databases.operations.cancel para cancelar uma operação de atualização de esquema de longa duração.

Consiga o ID da operação:
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
Substitua:
- INSTANCE-NAME pelo nome da instância do Spanner.
- DATABASE-NAME pelo nome do banco de dados.
Clique em projects.instances.databases.operations.cancel.
Em name, insira o nome da operação de atualização de esquema de longa duração, conforme mostrado na resposta correspondente. Exemplo:

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

Substitua:
- PROJECT-ID pelo ID do projeto.
- OPERATION-ID pelo ID de operações.
Também é possível listar operações de instância de longa duração para recuperar o nome da operação de atualização do esquema.
Clique em Executar. A operação será interrompida.

Operações de backup e restauração

Veja a seguir as operações de backup de longa duração.

Verificar o progresso de uma operação de backup ou restauração de longa duração

Console

Backup

No menu de navegação do Spanner, selecione a guia Operações. A página Operações mostra uma lista das operações em execução no momento.
Encontre a operação do esquema na lista. Se ela ainda estiver em execução, a barra de progresso na coluna Horário de término vai mostrar a porcentagem da operação concluída, conforme mostrado na imagem a seguir:

Captura de tela do indicador de progresso mostrando 98%

Restaurar

Para verificar o andamento da operação de restauração, consulte o indicador de progresso exibido durante o processo, conforme mostrado na imagem a seguir:

Captura de tela do indicador de progresso mostrando 56%

Se a operação demorar muito, será possível cancelá-la. Para mais informações, consulte Cancelar uma operação de instância de longa duração.

gcloud

Use gcloud spanner operations describe para verificar o progresso de uma operação de backup ou restauração.

Consiga o ID da operação:
```
gcloud spanner operations list --instance=INSTANCE-NAME \
--database=DATABASE-NAME --type=DATABASE_UPDATE_DDL
```
Substitua:
- INSTANCE-NAME pelo nome da instância do Spanner.
- DATABASE-NAME pelo nome do banco de dados.

Execute gcloud spanner operations describe:

gcloud spanner operations describe OPERATION-ID\
--instance=INSTANCE-NAME \
--database=DATABASE-NAME

Substitua:

OPERATION-ID: o ID da operação que você quer verificar.
INSTANCE-NAME: o nome da instância do Spanner.
DATABASE-NAME: o nome do banco de dados do Spanner.

A seção progress na saída mostra a porcentagem da operação concluída. A resposta será semelhante a:

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

Consiga o ID da operação:

  gcloud spanner operations list --instance=INSTANCE-NAME 

  --database=DATABASE-NAME --type=DATABASE_UPDATE_DDL

Substitua:

INSTANCE-NAME pelo nome da instância do Spanner.
DATABASE-NAME pelo nome do banco de dados.

Antes de usar os dados da solicitação, faça as substituições a seguir:

project-id: o ID do projeto.
instance-id: o ID da instância
database-id: o ID do banco de dados.
operation-id: o ID da operação.

Método HTTP e URL:

GET https://spanner.googleapis.com/v1/projects/project-id/instances/instance-id/databases/database-id/operations/operation-id

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

execute o seguinte comando:

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)

execute o seguinte comando:

$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

Você receberá uma resposta JSON semelhante a esta:

{
...
    "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"
  }
}

Se a operação demorar muito, será possível cancelá-la. Para mais informações, consulte Cancelar uma operação de backup de longa duração.

Listar operações de backup ou restauração de longa duração

Use projects.instances.backups.operations.list para listar as operações em um único backup ou projects.instances.backupOperations.list para listar todas as operações de backup na instância.

Clique em projects.instances.backups.operations.list.
Para o nome, insira:

projects/project-id/instances/test-instance/backups/example-db-backup-4/operations
Clique em Executar. A resposta contém uma lista de operações de longa duração.

Cancelar uma operação de backup de longa duração

Use projects.instances.backups.operations.cancel para cancelar uma operação de backup de longa duração.

Clique em projects.instances.backups.operations.cancel.
Em name, insira o nome da operação de backup de longa duração, conforme mostrado na resposta dessa operação. Exemplo:

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

Substitua _auto_1492721321097206 pelo ID da operação.

É possível recuperar o nome da operação de backup listando operações de backup de longa duração.
Clique em Executar.

Operações de instância

Veja a seguir as operações de instâncias de longa duração.

Verificar o progresso de uma operação de instância de longa duração

Use projects.instances.operations.get para verificar o andamento de uma operação de instância de longa duração.

Como exemplo, esta é uma resposta de 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"
    }
  }

O valor name na parte superior da resposta mostra que o serviço do Spanner criou uma operação de instância de longa duração chamada projects/PROJECT-ID/instances/test-instance/operations/<VAR>OPERATION-ID</VAR>.

Para verificar o andamento da operação de instância de longa duração:

Clique em projects.instances.operations.get.
Para name, insira o nome da operação de instância de longa duração, conforme mostrado na resposta para projects.instances.create ou projects.instances.patch. Exemplo:

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

Substitua:
- PROJECT-ID pelo ID do projeto.
- OPERATION-ID pelo ID de operações.
É possível recuperar o nome da operação de instância listando operações de instância de longa duração.
Clique em Executar. Quando uma operação é concluída, o campo done é definido como true.

Listar operações de instância de longa duração

Use projects.instances.operations.list para listar operações de instância de longa duração.

Clique em projects.instances.operations.list.
Para o nome, insira:

projects/PROJECT-ID/instances/test-instance/operations
Clique em Executar. A resposta contém uma lista de operações de longa duração.

Cancelar uma operação de instância de longa duração

Use projects.instances.operations.cancel para cancelar uma operação de instância de longa duração.

Clique em projects.instances.operations.cancel.
Para name, insira o nome da operação de instância de longa duração, como mostrado na resposta da operação de instância de longa duração. Exemplo:

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

Substitua:
- PROJECT-ID pelo ID do projeto.
- OPERATION-ID pelo ID de operações.
É possível recuperar o nome da operação de instância listando operações de instância de longa duração.
Clique em Executar.

Excluir uma operação de instância de longa duração

Use projects.instances.operations.delete para excluir uma operação de instância de longa duração.

Clique em projects.instances.operations.delete.
Para name, insira o nome da operação de instância de longa duração, como mostrado na resposta da operação de instância de longa duração. Exemplo:

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

Substitua:
- PROJECT-ID pelo ID do projeto.
- OPERATION-ID pelo ID de operações.
É possível recuperar o nome da operação de instância listando operações de instância de longa duração.
Clique em Executar. A operação foi excluída.