Gestisci e osserva le operazioni a lunga esecuzione

Questa pagina descrive come gestire il ciclo di vita di un'operazione a lunga esecuzione di Spanner utilizzando l'API REST operativa.

Le operazioni a lunga esecuzione sono chiamate di metodo il cui completamento può richiedere molto tempo. Spanner crea operazioni a lunga esecuzione per diverse azioni relative a istanza, database e backup. Un esempio è il metodo per ripristinare un database, projects.instances.databases.restore.

Quando ripristini un database, il servizio Spanner crea un'operazione a lunga esecuzione per monitorare l'avanzamento del ripristino. Spanner fornisce API operative che consentono di controllare l'avanzamento di operazioni a lunga esecuzione. Puoi anche elencare e annullare le operazioni a lunga esecuzione ed eliminare quelle a lunga esecuzione.

Puoi controllare e gestire le operazioni a lunga esecuzione con quanto segue:

• Librerie client di Spanner
• Lo strumento a riga di comando gcloud
• La console Google Cloud

Gestire le operazioni Spanner a lunga esecuzione con l'API REST

Gestisci le operazioni a lunga esecuzione di Spanner utilizzando i seguenti metodi REST:

Azione	Operazioni di database a lunga esecuzione	Operazioni dell'istanza a lunga esecuzione
Annulla un'operazione a lunga esecuzione	cancel	cancel
Elimina un'operazione a lunga esecuzione	Non supportato	Non supportato
Controllare l'avanzamento di un'operazione a lunga esecuzione	get	get
Elenca operazioni a lunga esecuzione	list	list

Per informazioni sull'utilizzo di REST con Spanner, consulta Introduzione a Spanner mediante REST.

Operazioni del database

Di seguito sono riportate le operazioni di database a lunga esecuzione.

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

Controlla l'avanzamento di un'operazione di database a lunga esecuzione

Utilizza projects.instances.databases.operations.get per verificare l'avanzamento di un'operazione di database a lunga esecuzione.

Ad esempio, questa è una risposta di 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"
    }
  }

Il valore name nella parte superiore della risposta indica che il servizio Spanner ha creato un'operazione di database a lunga esecuzione denominata projects/PROJECT-ID/instances/test-instance/databases/example-db/operations/_auto_1492721321097206.

Per verificare l'avanzamento dell'operazione del database a lunga esecuzione:

1. Fai clic su projects.instances.databases.operations.get.

2. Per name, inserisci il nome dell'operazione di database a lunga esecuzione come mostrato nella risposta a projects.instances.databases.create o projects.instances.databases.updateDdl. Ad esempio:

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

   Sostituisci quanto segue:

   • PROJECT-ID con l'ID progetto.
   • OPERATION-ID con l'ID operazioni.

   recupera il nome dell'operazione di database elencando le operazioni di database a lunga esecuzione.

3. Fai clic su Execute (Esegui). Al termine di un'operazione, il campo done è impostato su true.

Per ottenere aggiornamenti continui, richiama ripetutamente il metodo projects.instances.databases.operations.get fino al completamento dell'operazione. Utilizzare un backoff tra una richiesta e l'altra. Ad esempio, invia una richiesta ogni 10 secondi.

Elenca le operazioni di database a lunga esecuzione

Utilizza projects.instances.databases.operations.list per elencare le operazioni di database a lunga esecuzione.

1. Fai clic su projects.instances.databases.operations.list.

2. Per nome, inserisci:

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

3. Fai clic su Execute (Esegui). La risposta contiene un elenco di operazioni a lunga esecuzione.

Annulla un'operazione di database a lunga esecuzione

Utilizza projects.instances.databases.operations.cancel per annullare un'operazione di database a lunga esecuzione.

1. Fai clic su projects.instances.databases.operations.cancel.

2. In corrispondenza di name, inserisci il nome dell'operazione di database a lunga esecuzione come mostrato nella risposta dell'operazione di database a lunga esecuzione. Ad esempio:

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

   Utilizza il nome dell'operazione che hai ricevuto anziché questo valore. Puoi anche recuperare il nome dell'operazione di database elencando le operazioni di database a lunga esecuzione.

3. Fai clic su Execute (Esegui).

Operazioni di aggiornamento dello schema

Di seguito sono riportate operazioni di aggiornamento dello schema a lunga esecuzione.

• projects.instances.databases.updateDdl

Controllare l'avanzamento di un'operazione di aggiornamento dello schema a lunga esecuzione

Console

1. Nel menu di navigazione di Spanner, seleziona la scheda Operazioni. La pagina Operazioni mostra un elenco delle operazioni attualmente in esecuzione.

2. Trova l'operazione dello schema nell'elenco. Se è ancora in esecuzione, la barra di avanzamento nella colonna Ora di fine mostra la percentuale dell'operazione completata, come mostrato nell'immagine seguente:

gcloud

Utilizza gcloud spanner operations describe per verificare l'avanzamento di un'operazione.

1. Recupera l'ID operazione:

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

   Sostituisci quanto segue:

   • INSTANCE-NAME con il nome dell'istanza Spanner.
   • DATABASE-NAME con il nome del database.

2. Esecuzione gcloud spanner operations describe:

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

   Sostituisci quanto segue:

   • OPERATION-ID: l'ID dell'operazione che vuoi controllare.
   • INSTANCE-NAME: nome dell'istanza Spanner.
   • DATABASE-NAME: il nome del database Spanner.

   La sezione progress nell'output mostra la percentuale dell'operazione completata. L'output è simile al seguente:

   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

Recupera l'ID operazione:

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

Sostituisci quanto segue:

• INSTANCE-NAME con il nome dell'istanza Spanner.
• DATABASE-NAME con il nome del database.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

• project-id: l'ID progetto.
• instance-id: l'ID istanza.
• database-id: l'ID del database.
• operation-id: l'ID operazione.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando di gcloud. . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Dovresti ricevere una risposta JSON simile alla seguente:

{
...
    "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 l'operazione richiede troppo tempo, puoi annullarla. Per maggiori informazioni, consulta Annullare un'operazione di aggiornamento dello schema a lunga esecuzione.

Elenca le operazioni di aggiornamento dello schema a lunga esecuzione

gcloud

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

Sostituisci quanto segue:

• INSTANCE-NAME con il nome dell'istanza Spanner.
• DATABASE-NAME con il nome del database.

L'output è simile al seguente:

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

Annulla un'operazione di aggiornamento dello schema a lunga esecuzione

gcloud

1. Recupera l'ID operazione:

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

   Sostituisci quanto segue:

   • INSTANCE-NAME con il nome dell'istanza Spanner.
   • DATABASE-NAME con il nome del database.

2. Utilizza gcloud operations cancel per annullare un'operazione di aggiornamento dello schema a lunga esecuzione.

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

   Sostituisci quanto segue:

   • OPERATION-ID: l'ID dell'operazione che vuoi controllare.
   • INSTANCE-NAME: nome dell'istanza Spanner.

REST V1

Utilizza projects.instances.databases.operations.cancel per annullare un'operazione di aggiornamento dello schema a lunga esecuzione.

1. Recupera l'ID operazione:

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

   Sostituisci quanto segue:

   • INSTANCE-NAME con il nome dell'istanza Spanner.
   • DATABASE-NAME con il nome del database.

2. Fai clic su projects.instances.databases.operations.cancel.

3. In corrispondenza di nome, inserisci il nome dell'operazione di aggiornamento dello schema a lunga esecuzione come mostrato nella risposta dell'operazione di aggiornamento dello schema a lunga esecuzione. Ad esempio:

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

   Sostituisci quanto segue:

   • PROJECT-ID con l'ID progetto.
   • OPERATION-ID con l'ID operazioni.

   Puoi anche elencare le operazioni dell'istanza a lunga esecuzione per recuperare il nome dell'operazione di aggiornamento dello schema.

4. Fai clic su Execute (Esegui). L'operazione si interrompe.

Operazioni di backup e ripristino

Di seguito sono riportate le operazioni di backup a lunga esecuzione.

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

Controllare l'avanzamento di un'operazione di backup o ripristino a lunga esecuzione

Console

Riserva

1. Nel menu di navigazione di Spanner, seleziona la scheda Operazioni. La pagina Operazioni mostra un elenco delle operazioni attualmente in esecuzione.

2. Trova l'operazione dello schema nell'elenco. Se è ancora in esecuzione, la barra di avanzamento nella colonna Ora di fine mostra la percentuale dell'operazione completata, come mostrato nell'immagine seguente:

Ripristina

Per verificare l'avanzamento dell'operazione di ripristino, osserva l'indicatore di avanzamento visualizzato durante il ripristino, come nell'immagine seguente:

Se l'operazione richiede troppo tempo, puoi annullarla. Per maggiori informazioni, consulta Annullare un'operazione di istanza a lunga esecuzione.

gcloud

Utilizza gcloud spanner operations describe per controllare l'avanzamento di un'operazione di backup o ripristino.

1. Recupera l'ID operazione:

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

   Sostituisci quanto segue:

   • INSTANCE-NAME con il nome dell'istanza Spanner.
   • DATABASE-NAME con il nome del database.

2. Esecuzione gcloud spanner operations describe:

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

   Sostituisci quanto segue:

   • OPERATION-ID: l'ID dell'operazione che vuoi controllare.
   • INSTANCE-NAME: nome dell'istanza Spanner.
   • DATABASE-NAME: il nome del database Spanner.

   La sezione progress nell'output mostra la percentuale dell'operazione completata. L'output è simile al seguente:

   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

Recupera l'ID operazione:

  gcloud spanner operations list --instance=INSTANCE-NAME 

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

Sostituisci quanto segue:

• INSTANCE-NAME con il nome dell'istanza Spanner.
• DATABASE-NAME con il nome del database.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

• project-id: l'ID progetto.
• instance-id: l'ID istanza.
• database-id: l'ID del database.
• operation-id: l'ID operazione.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando di gcloud. . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Dovresti ricevere una risposta JSON simile alla seguente:

{
...
    "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 l'operazione richiede troppo tempo, puoi annullarla. Per maggiori informazioni, consulta Annullare un'operazione di backup a lunga esecuzione.

Elenca le operazioni di backup o ripristino a lunga esecuzione

Utilizza projects.instances.backups.operations.list per elencare le operazioni su un singolo backup oppure projects.instances.backupOperations.list per elencare tutte le operazioni di backup nell'istanza.

1. Fai clic su projects.instances.backups.operations.list.

2. Per nome, inserisci:

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

3. Fai clic su Execute (Esegui). La risposta contiene un elenco di operazioni a lunga esecuzione.

Annulla un'operazione di backup a lunga esecuzione

Utilizza projects.instances.backups.operations.cancel per annullare un'operazione di backup a lunga esecuzione.

1. Fai clic su projects.instances.backups.operations.cancel.

2. In corrispondenza di name, inserisci il nome dell'operazione di backup a lunga esecuzione come mostrato nella risposta dell'operazione di backup a lunga esecuzione. Ad esempio:

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

   Sostituisci _auto_1492721321097206 con il tuo ID operazione.

   Puoi recuperare il nome dell'operazione di backup elencando le operazioni di backup a lunga esecuzione.

3. Fai clic su Execute (Esegui).

Operazioni dell'istanza

Di seguito sono riportate le operazioni dell'istanza a lunga esecuzione.

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

Controllare l'avanzamento di un'operazione dell'istanza a lunga esecuzione

Utilizza projects.instances.operations.get per verificare l'avanzamento di un'operazione di istanza a lunga esecuzione.

Ad esempio, questa è una risposta di 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"
    }
  }

Il valore name nella parte superiore della risposta indica che il servizio Spanner ha creato un'operazione di istanza a lunga esecuzione denominata projects/PROJECT-ID/instances/test-instance/operations/<VAR>OPERATION-ID</VAR>.

Per verificare l'avanzamento dell'operazione dell'istanza a lunga esecuzione:

1. Fai clic su projects.instances.operations.get.

2. Per name, inserisci il nome dell'operazione di istanza a lunga esecuzione come mostrato nella risposta a projects.instances.create o projects.instances.patch. Ad esempio:

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

   Sostituisci quanto segue:

   • PROJECT-ID con l'ID progetto.
   • OPERATION-ID con l'ID operazioni.

   Puoi recuperare il nome dell'operazione dell'istanza elencando le operazioni dell'istanza a lunga esecuzione.

3. Fai clic su Execute (Esegui). Al termine di un'operazione, il campo done è impostato su true.

Per ottenere aggiornamenti continui, richiama ripetutamente il metodo projects.instances.databases.operations.get fino al completamento dell'operazione. Utilizzare un backoff tra una richiesta e l'altra. Ad esempio, invia una richiesta ogni 10 secondi.

Elenca operazioni di istanza a lunga esecuzione

Utilizza projects.instances.operations.list per elencare le operazioni dell'istanza a lunga esecuzione.

1. Fai clic su projects.instances.operations.list.

2. Per nome, inserisci:

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

3. Fai clic su Execute (Esegui). La risposta contiene un elenco di operazioni a lunga esecuzione.

Annulla un'operazione di istanza a lunga esecuzione

Utilizza projects.instances.operations.cancel per annullare un'operazione di istanza a lunga esecuzione.

1. Fai clic su projects.instances.operations.cancel.

2. In corrispondenza di name, inserisci il nome dell'operazione di istanza a lunga esecuzione come mostrato nella risposta dell'operazione di istanza a lunga esecuzione. Ad esempio:

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

   Sostituisci quanto segue:

   • PROJECT-ID con l'ID progetto.
   • OPERATION-ID con l'ID operazioni.

   Puoi recuperare il nome dell'operazione dell'istanza elencando le operazioni dell'istanza a lunga esecuzione.

3. Fai clic su Execute (Esegui).

Elimina un'operazione di istanza a lunga esecuzione

Utilizza projects.instances.operations.delete per eliminare un'operazione di istanza a lunga esecuzione.

1. Fai clic su projects.instances.operations.delete.

2. In corrispondenza di name, inserisci il nome dell'operazione di istanza a lunga esecuzione come mostrato nella risposta dell'operazione di istanza a lunga esecuzione. Ad esempio:

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

   Sostituisci quanto segue:

   • PROJECT-ID con l'ID progetto.
   • OPERATION-ID con l'ID operazioni.

   Puoi recuperare il nome dell'operazione dell'istanza elencando le operazioni dell'istanza a lunga esecuzione.

3. Fai clic su Execute (Esegui). L'operazione è stata eliminata.