Gestire e osservare le operazioni a lunga esecuzione

Questa pagina descrive come gestire il ciclo di vita di un'operazione di lunga durata di Spanner utilizzando i comandi gcloud spanner operations e l'API REST operations. Alcune procedure possono essere eseguite anche nella console Google Cloud .

Le operazioni a lunga esecuzione sono chiamate di metodi il cui completamento potrebbe richiedere molto tempo. Spanner crea operazioni a lunga esecuzione per diverse azioni di 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. Se l'operazione richiede più tempo del previsto, puoi utilizzare gcloud per controllare lo stato di avanzamento dell'operazione. Se l'operazione non risponde, puoi utilizzare gcloud per annullarla.

Spanner fornisce API di operazioni che consentono di controllare lo stato di avanzamento delle operazioni a lunga esecuzione. Puoi anche elencare e annullare operazioni a lunga esecuzione ed eliminare operazioni a lunga esecuzione sulle istanze.

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

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

Comandi API REST per la gestione delle operazioni

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

Azione	Operazioni di database a lunga esecuzione	Operazioni a lunga esecuzione sulle istanze
Annulla un'operazione a lunga esecuzione	cancel	cancel
Elimina un'operazione a lunga esecuzione	Non supportato	delete
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, vedi Iniziare a utilizzare Spanner con REST.

Operazioni istanza

Di seguito sono riportate le operazioni a lunga esecuzione sulle istanze.

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

Controllare l'avanzamento di un'operazione di istanza a esecuzione prolungata

Utilizza projects.instances.operations.get per controllare lo stato di avanzamento di un'operazione a lunga esecuzione dell'istanza.

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

Il valore name nella parte superiore della risposta mostra che il servizio Spanner ha creato un'operazione di istanza a lunga esecuzione denominata projects/test01/instances/test-instance/operations/_auto_1492721321097206.

Per controllare l'avanzamento dell'operazione dell'istanza a esecuzione prolungata:

1. Vai a projects.instances.operations.get.

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

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

3. Fai clic su Esegui. Quando un'operazione viene completata, il campo done viene impostato su true.

Per ricevere aggiornamenti continui, richiama ripetutamente il metodo projects.instances.databases.operations.get finché l'operazione non è terminata. Utilizza un backoff tra una richiesta e l'altra. Ad esempio, invia una richiesta ogni 10 secondi.

Elenca operazioni a lunga esecuzione dell'istanza

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

1. Vai a projects.instances.operations.list.

2. Come nome, inserisci:

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

Annullamento di un'operazione di istanza a lunga esecuzione

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

1. Vai a projects.instances.operations.cancel.

2. Per name, inserisci il nome dell'operazione a lunga esecuzione dell'istanza come mostrato nella risposta dell'operazione a lunga esecuzione dell'istanza.

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

3. Fai clic su 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. Per name, inserisci il nome dell'operazione a lunga esecuzione dell'istanza come mostrato nella risposta dell'operazione a lunga esecuzione dell'istanza.

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

3. Vai a Esegui. L'operazione è stata eliminata.

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

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

Utilizza projects.instances.databases.operations.get per controllare lo stato di avanzamento di un'operazione di database a lunga esecuzione.

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

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

Per controllare lo stato di avanzamento dell'operazione di database a esecuzione prolungata:

1. Vai a projects.instances.databases.operations.get.

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

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

3. Fai clic su Esegui. Quando un'operazione viene completata, il campo done viene impostato su true.

Per ricevere aggiornamenti continui, richiama ripetutamente il metodo projects.instances.databases.operations.get finché l'operazione non è terminata. Utilizza un backoff tra una richiesta e l'altra. Ad esempio, invia una richiesta ogni 10 secondi.

Elenco delle operazioni di database a lunga esecuzione

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

1. Vai a projects.instances.databases.operations.list.

2. Come nome, inserisci:

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

Annullamento di un'operazione di database a lunga esecuzione

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

1. Vai a projects.instances.databases.operations.cancel.

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

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

3. Fai clic su Esegui.

Operazioni di aggiornamento dello schema

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

• projects.instances.databases.updateDdl

Controllare lo stato di avanzamento di un'operazione di aggiornamento dello schema a esecuzione prolungata

Console

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

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

gcloud

Utilizza gcloud spanner operations describe per controllare lo stato di 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: il nome dell'istanza Spanner.
   • DATABASE-NAME: il nome dell'istanza
   • DATABASE-NAME: il nome del database.

2. Corsa gcloud spanner operations describe:

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

   Sostituisci quanto segue:

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

   La sezione progress nell'output mostra la percentuale di completamento dell'operazione. 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: il nome dell'istanza Spanner.
• DATABASE-NAME: il nome del database.

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

• PROJECT-ID: l'ID progetto
• INSTANCE-ID: l'ID istanza
• DATABASE-ID: l'ID 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 seguente comando 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 consente di accedere automaticamente all'interfaccia a riga di comando 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 ulteriori informazioni, vedi Annullare un'operazione di aggiornamento dello schema a esecuzione prolungata.

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: il nome dell'istanza Spanner.
• DATABASE-NAME: 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
_auto_op_234567  CREATE INDEX SongsBySingerAlbumSongName ON Songs(SingerId, AlbumId, SongName), INTERLEAVE IN Albums  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: il nome dell'istanza Spanner.
   • DATABASE-NAME: il nome del database.

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

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

   Sostituisci quanto segue:

   • OPERATION-ID: l'ID operazione dell'operazione che vuoi controllare.
   • INSTANCE-NAME: il 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: il nome dell'istanza Spanner.
   • DATABASE-NAME: il nome del database.

2. Vai a projects.instances.databases.operations.cancel.

3. Per name, 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.

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • OPERATION-ID: l'ID operazioni.

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

4. Fai clic su Esegui. L'operazione viene interrotta.

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 di lunga durata

Console

Backup

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 sullo schema nell'elenco. Se è ancora in esecuzione, la barra di avanzamento nella colonna Ora di fine mostra la percentuale di completamento dell'operazione, come mostrato nell'immagine seguente:

Ripristina

Per controllare l'avanzamento dell'operazione di ripristino, consulta l'indicatore di avanzamento visualizzato durante il ripristino, come mostrato nell'immagine seguente:

Se l'operazione richiede troppo tempo, puoi annullarla. Per ulteriori informazioni, vedi Annullare un'operazione di lunga durata per un'istanza.

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=TYPE

   Sostituisci quanto segue:

   • INSTANCE-NAME: il nome dell'istanza Spanner.
   • DATABASE-NAME: il nome del database.
   • TYPE: il tipo di operazione. I valori possibili sono BACKUP e DATABASE_RESTORE.

2. Corsa gcloud spanner operations describe:

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

   Sostituisci quanto segue:

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

   La sezione progress nell'output mostra la percentuale di completamento dell'operazione. 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: il nome dell'istanza Spanner.
• DATABASE-NAME: il nome del database.

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

• PROJECT-ID: l'ID progetto
• INSTANCE-ID: l'ID istanza
• DATABASE-ID: l'ID 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 seguente comando 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 consente di accedere automaticamente all'interfaccia a riga di comando 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 ulteriori informazioni, vedi Annullare un'operazione di backup a lunga esecuzione.

Elenco delle operazioni di backup o ripristino a lunga esecuzione

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

1. Vai a projects.instances.backups.operations.list.

2. Come nome, inserisci:

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • BACKUP-NAME: il nome del backup.
   • OPERATION-ID: l'ID operazioni.

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

Annullamento di un'operazione di backup a lunga esecuzione

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

1. Vai a projects.instances.backups.operations.cancel.

2. Per name, inserisci il nome dell'operazione di backup a lunga esecuzione come mostrato nella risposta dell'operazione di backup a lunga esecuzione.

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

   Sostituisci quanto segue:

   • PROJECT-ID: l'ID progetto
   • INSTANCE-NAME: il nome dell'istanza
   • BACKUP-NAME: il nome del backup.
   • OPERATION-ID: l'ID operazioni.

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

3. Fai clic su Esegui.