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

Nesta página, descrevemos como gerenciar o ciclo de vida de um Spanner operação de longa duração usando comandos gcloud spanner operations e a API REST de operações. Alguns procedimentos também podem no console do Google Cloud.

Operações de longa duração são chamadas de métodos que podem demorar tempo para conclusão. O Spanner cria operações de longa duração instâncias, bancos de dados e ações de 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 um uma operação de longa duração para acompanhar o progresso da restauração. Se a operação levar mais tempo do que o esperado, use gcloud para verificar o progresso do operação Se a operação não estiver respondendo, use gcloud para cancelar o operação

O Spanner fornece APIs de operação que permitem verificar o progresso das operações de longa duração. Também é possível listar e cancelar operações e excluir operações de instância 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
• O Console do Google Cloud

Comandos da API REST para gerenciamento de operações

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	Sem suporte	delete
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 REST com o Spanner, consulte Primeiros passos no Spanner usando REST.

Operações de instância

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

• projects.instances.create
• projects.instances.patch

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

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

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

O valor name na parte de cima da resposta mostra a política do Spanner serviço criou uma operação de instância de longa duração chamada projects/test01/instances/test-instance/operations/_auto_1492721321097206.

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

1. Acesse projects.instances.operations.get.

2. 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/INSTANCE-NAME/operations/OPERATION-ID
   

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

   Para recuperar o nome da operação de instância, liste operações de instância de longa duração.

3. Clique em Executar. Quando uma operação é concluída, o campo done é definido como true.

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

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

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

1. Acesse projects.instances.operations.list.

2. Para o nome, insira:

   projects/PROJECT-ID/instances/INSTANCE-NAME/operationsOPERATION-ID
   

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

3. 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

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

1. Acesse projects.instances.operations.cancel.

2. 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.

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

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

   Você também pode recuperar o nome da operação de instância listando as operações de instância de longa duração.

3. Clique em Executar.

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

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

1. Clique em projects.instances.operations.delete.

2. 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.

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

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

   Você também pode recuperar o nome da operação de instância listando as operações de instância de longa duração.

3. Navegue até Execute. A operação foi excluída.

Operações de banco de dados

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

• projects.instances.databases.create
• projects.instances.databases.restore
• projects.instances.databases.updateDdl
• projects.instances.databaseOperations.list

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

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

Por exemplo, a seguir é uma resposta 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"
  }
}

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

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

1. Acesse projects.instances.databases.operations.get.

2. 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.

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/operations/OPERATION-ID
   

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

   Também é possível recuperar o nome da operação do banco de dados listando operações de banco de dados de longa duração.

3. Clique em Executar. Quando uma operação é concluída, o campo done é definido como true.

Para receber atualizações contínuas, invoque repetidamente o projects.instances.databases.operations.get até que a operação seja feito. Use um backoff 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

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

1. Acesse projects.instances.databases.operations.list.

2. Para o nome, insira:

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/OPERATION-ID
   

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

3. 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

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

1. Acesse projects.instances.databases.operations.cancel.

2. 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.

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/OPERATION-ID
   

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

   Também é possível recuperar o nome da operação do banco de dados listando operações de banco de dados de longa duração.

3. Clique em Executar.

Operações de atualização de esquema

Veja a seguir 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

1. No menu de navegação do Spanner, selecione a guia Operações. O A página Operações mostra uma lista de operações em execução.

2. Encontre a operação de esquema na lista. Se ainda estiver em execução, o progresso na coluna Horário de término mostra a porcentagem da operação que está concluída, conforme mostrado na imagem a seguir:

gcloud

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

1. Consiga o ID da operação:

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

   Substitua:

   • INSTANCE-NAME: o nome da instância do Spanner.
   • DATABASE-NAME: o nome da instância.
   • DATABASE-NAME: o nome do banco de dados.

2. 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 para 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 que está completa. A saída será assim:

   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: o nome da instância do Spanner.
• DATABASE-NAME: o nome do banco de dados.

Antes de usar os dados da solicitação abaixo, 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 Cancele 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: o nome da instância do Spanner.
• DATABASE-NAME: o nome do banco de dados.

A saída será assim:

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

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

gcloud

1. Consiga o ID da operação:

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

   Substitua:

   • INSTANCE-NAME: o nome da instância do Spanner.
   • DATABASE-NAME: o nome do banco de dados.

2. Usar o gcloud spanner operations cancel para cancelar uma operação de atualização de esquema de longa duração.

   gcloud spanner operations cancel OPERATION-ID \
    --instance=INSTANCE-NAME
   

   Substitua:

   • OPERATION-ID: o ID da operação que você quer para verificar.
   • INSTANCE-NAME: o nome da instância do Spanner.

REST V1

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

1. Consiga o ID da operação:

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

   Substitua:

   • INSTANCE-NAME: o nome da instância do Spanner.
   • DATABASE-NAME: o nome do banco de dados.

2. Acesse projects.instances.databases.operations.cancel.

3. Em nome, insira o nome da operação de atualização do esquema de longa duração como: como mostrado na resposta da operação de atualização de esquema de longa duração.

   projects/PROJECT-ID/instances/INSTANCE-NAME/databases/example-db/operations/OPERATION-ID
   

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • OPERATION-ID: o ID de operações.

   Também é possível recuperar o nome da operação de atualização de esquema listando operações de instância de longa duração.

4. Clique em Executar. A operação é interrompida.

Operações de backup e restauração

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

• projects.instances.backups.create
• projects.instances.databases.restore

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

Console

Backup

1. No menu de navegação do Spanner, selecione a guia Operações. O A página Operações mostra uma lista das operações em execução no momento.

2. Encontre a operação de esquema na lista. Se ainda estiver em execução, o progresso na coluna Horário de término mostra a porcentagem da operação que está concluída, conforme mostrado na imagem a seguir:

Restaurar

Para verificar o progresso da operação de restauração, consulte o indicador de progresso que aparece durante a restauração, conforme mostrado na imagem abaixo:

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

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

1. Consiga o ID da operação:

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

   Substitua:

   • INSTANCE-NAME: o nome da instância do Spanner.
   • DATABASE-NAME: o nome do banco de dados.

2. 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ê que quiser 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 que está completa. A saída será assim:

   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: o nome da instância do Spanner.
• DATABASE-NAME: o nome do banco de dados.

Antes de usar os dados da solicitação abaixo, 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 backup de longa duração.

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

Usar 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.

1. Acesse projects.instances.backups.operations.list.

2. Para o nome, insira:

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

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • BACKUP-NAME: o nome do backup.
   • OPERATION-ID: o ID de operações.

3. 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

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

1. Acesse projects.instances.backups.operations.cancel.

2. Em name, insira o nome da operação de backup de longa duração, conforme mostrado na resposta dessa operação.

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

   Substitua:

   • PROJECT-ID: o ID do projeto;
   • INSTANCE-NAME: o nome da instância.
   • BACKUP-NAME: o nome do backup.
   • OPERATION-ID: o ID de operações.

   Também é possível recuperar o nome da operação de backup listando operações de backup de longa duração.

3. Clique em Executar.