Administra y observa operaciones de larga duración

En esta página, se describe cómo administrar el ciclo de vida de una operación de larga duración de Spanner con los comandos de gcloud spanner operations y la API de REST de operaciones. Algunos procedimientos también se pueden realizar en la consola de Google Cloud.

Las operaciones de larga duración son llamadas de método que pueden tardar una gran cantidad de tiempo en completarse. Spanner crea operaciones de larga duración para varias acciones de instancia, base de datos y copia de seguridad. Un ejemplo es el método para restablecer una base de datos, projects.instances.databases.restore. Cuando restableces una base de datos, el servicio de Spanner crea una operación de larga duración para realizar un seguimiento del progreso del restablecimiento. Si la operación tarda más de lo esperado, puedes usar gcloud para verificar su progreso. Si la operación no responde, puedes usar gcloud para cancelarla.

Spanner proporciona APIs de operación que te permiten verificar el progreso de las operaciones de larga duración. También puedes enumerar y cancelar las operaciones de larga duración y borrar las operaciones de instancia de larga duración.

Puedes verificar y administrar operaciones de larga duración con los siguientes elementos:

• Bibliotecas cliente de Spanner
• La herramienta de línea de comandos de gcloud
• La consola de Google Cloud

Comandos de la API de REST para la administración de operaciones

Administra tus operaciones de larga duración de Spanner con los siguientes métodos de REST:

Acción	Operaciones de base de datos de larga duración	Operaciones de instancia de larga duración
Cancelar una operación de larga duración	cancel	cancel
Borrar una operación de larga duración	No compatible	delete
Verifica el progreso de una operación de larga duración	get	get
Enumerar las operaciones de larga duración	list	list

Para obtener información sobre el uso de REST con Spanner, consulta Comienza a usar Spanner con REST.

Operaciones de instancias

Las siguientes son operaciones de instancia de larga duración.

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

Verifica el progreso de una operación de instancia de larga duración

Usa projects.instances.operations.get para verificar el progreso de una operación de instancia de larga duración.

A modo de ejemplo, esta es una respuesta 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"
    }
  }

El valor name en la parte superior de la respuesta muestra que el servicio de Spanner creó una operación de instancia de larga duración llamada projects/test01/instances/test-instance/operations/_auto_1492721321097206.

Para verificar el progreso de la operación de instancia de larga duración, sigue estos pasos:

1. Navega a projects.instances.operations.get.

2. En nombre, ingresa el nombre de la operación de instancia de larga duración como se muestra en la respuesta a projects.instances.create o projects.instances.patch. Por ejemplo:

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

   Puedes recuperar el nombre de la operación de la instancia si enumeras las operaciones de instancia de larga duración.

3. Haz clic en Ejecutar. Cuando se completa una operación, el campo done se establece como true.

Para obtener actualizaciones continuas, invoca de forma repetida el método projects.instances.databases.operations.get hasta que se complete la operación. Usa una retirada entre cada solicitud. Por ejemplo, realiza una solicitud cada 10 segundos.

Enumerar las operaciones de instancia de larga duración

Usa projects.instances.operations.list para enumerar las operaciones de instancia de larga duración.

1. Navega a projects.instances.operations.list.

2. En nombre, ingresa lo siguiente:

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

3. Haz clic en Ejecutar. La respuesta contiene una lista de operaciones de larga duración.

Cancelar una operación de instancia de larga duración

Usa projects.instances.operations.cancel para cancelar una operación de instancia de larga duración.

1. Navega a projects.instances.operations.cancel.

2. En nombre, ingresa el nombre de la operación de instancia de larga duración como se muestra en la respuesta de esa operación.

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

   También puedes recuperar el nombre de la operación de la instancia si enumeras las operaciones de instancia de larga duración.

3. Haz clic en Ejecutar.

Borrar una operación de instancia de larga duración

Usa projects.instances.operations.delete para borrar una operación de instancia de larga duración.

1. Haz clic en projects.instances.operations.delete.

2. En nombre, ingresa el nombre de la operación de instancia de larga duración como se muestra en la respuesta de esa operación.

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

   También puedes recuperar el nombre de la operación de la instancia si enumeras las operaciones de instancia de larga duración.

3. Ve a Ejecutar. Se borra la operación.

Operaciones de bases de datos

Las siguientes son operaciones de base de datos de larga duración.

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

Verifica el progreso de una operación de base de datos de larga duración

Usa projects.instances.databases.operations.get para verificar el progreso de una operación de base de datos de larga duración.

Por ejemplo, la siguiente es una respuesta de 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"
  }
}

El valor name en la parte superior de la respuesta muestra que el servicio de Spanner creó una operación de base de datos de larga duración llamada projects/test01/instances/test-instance/databases/example-db/operations/_auto_1492721321097206.

Para verificar el progreso de la operación de base de datos de larga duración, sigue estos pasos:

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

2. En nombre, ingresa el nombre de la operación de base de datos de larga duración como se muestra en la respuesta a projects.instances.databases.create o projects.instances.databases.updateDdl.

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

   También puedes recuperar el nombre de la operación de base de datos si enumeras las operaciones de base de datos de larga duración.

3. Haz clic en Ejecutar. Cuando se completa una operación, el campo done se establece como true.

Para obtener actualizaciones continuas, invoca de forma repetida el método projects.instances.databases.operations.get hasta que se complete la operación. Usa una retirada entre cada solicitud. Por ejemplo, realiza una solicitud cada 10 segundos.

Enumerar operaciones de base de datos de larga duración

Usa projects.instances.databases.operations.list para enumerar las operaciones de base de datos de larga duración.

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

2. En nombre, ingresa lo siguiente:

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

3. Haz clic en Ejecutar. La respuesta contiene una lista de operaciones de larga duración.

Cancelar una operación de base de datos de larga duración

Usa projects.instances.databases.operations.cancel para cancelar una operación de base de datos de larga duración.

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

2. En nombre, ingresa el nombre de la operación de base de datos de larga duración como se muestra en la respuesta de esa operación.

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

   También puedes recuperar el nombre de la operación de base de datos si enumeras las operaciones de base de datos de larga duración.

3. Haz clic en Ejecutar.

Operaciones de actualización del esquema

Las siguientes son operaciones de actualización de esquema de larga duración.

• projects.instances.databases.updateDdl

Verifica el progreso de una operación de actualización de esquema de larga duración

Console

1. En el menú de navegación de Spanner, selecciona la pestaña Operaciones. En la página Operaciones, se muestra una lista de las operaciones en ejecución.

2. Busca la operación de esquema en la lista. Si todavía se está ejecutando, la barra de progreso de la columna Hora de finalización muestra el porcentaje de la operación que se completó, como se muestra en la siguiente imagen:

gcloud

Usa gcloud spanner operations describe para verificar el progreso de una operación.

1. Obtén el ID de operación:

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

   Reemplaza lo siguiente:

   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.
   • DATABASE-NAME: el nombre de la instancia.
   • DATABASE-NAME: Es el nombre de la base de datos.

2. Ejecuta gcloud spanner operations describe:

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

   Reemplaza lo siguiente:

   • OPERATION-ID: El ID de operación de la operación que deseas verificar.
   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.
   • DATABASE-NAME: Es el nombre de la base de datos de Spanner.

   En la sección progress del resultado, se muestra el porcentaje de la operación que se completó. El resultado es similar al siguiente:

   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

Obtén el ID de operación:

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

Reemplaza lo siguiente:

• INSTANCE-NAME: Es el nombre de la instancia de Spanner.
• DATABASE-NAME: Es el nombre de la base de datos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT-ID: El ID del proyecto.
• INSTANCE-ID: El ID de la instancia.
• DATABASE-ID: Es el ID de la base de datos.
• OPERATION-ID: Es el ID de la operación.

Método HTTP y URL:

GET https://spanner.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID/databases/DATABASE-ID/operations/OPERATION-ID

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Si la operación tarda demasiado, puedes cancelarla. Para obtener más información, consulta Cancela una operación de actualización de esquema de larga duración.

Enumera las operaciones de actualización de esquema de larga duración

gcloud

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

Reemplaza lo siguiente:

• INSTANCE-NAME: Es el nombre de la instancia de Spanner.
• DATABASE-NAME: Es el nombre de la base de datos.

El resultado es similar al siguiente:

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

Cancela una operación de actualización de esquema de larga duración

gcloud

1. Obtén el ID de operación:

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

   Reemplaza lo siguiente:

   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.
   • DATABASE-NAME: Es el nombre de la base de datos.

2. Usa gcloud spanner operations cancel para cancelar una operación de actualización de esquema de larga duración.

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

   Reemplaza lo siguiente:

   • OPERATION-ID: El ID de operación de la operación que deseas verificar.
   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.

REST V1

Usa projects.instances.databases.operations.cancel para cancelar una operación de actualización de esquema de larga duración.

1. Obtén el ID de operación:

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

   Reemplaza lo siguiente:

   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.
   • DATABASE-NAME: Es el nombre de la base de datos.

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

3. En nombre, ingresa el nombre de la operación de actualización del esquema de larga duración como se muestra en la respuesta.

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • OPERATION-ID: Es el ID de las operaciones.

   También puedes recuperar el nombre de la operación de actualización del esquema si enumeras las operaciones de instancia de larga duración.

4. Haz clic en Ejecutar. Se detuvo la operación.

Operaciones de copia de seguridad y restablecimiento

Las siguientes son operaciones de instancia de larga duración.

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

Cómo verificar el progreso de una operación de copia de seguridad o restablecimiento de larga duración

Console

Copia de seguridad

1. En el menú de navegación de Spanner, selecciona la pestaña Operaciones. En la página Operaciones, se muestra una lista de las operaciones que se están ejecutando actualmente.

2. Busca la operación de esquema en la lista. Si todavía se está ejecutando, la barra de progreso de la columna Hora de finalización muestra el porcentaje de la operación que se completó, como se muestra en la siguiente imagen:

Restablecer

Para verificar el progreso de la operación de restablecimiento, consulta el indicador de progreso que se muestra durante el restablecimiento, como se muestra en la siguiente imagen:

Si la operación tarda demasiado, puedes cancelarla. Para obtener más información, consulta Cancela una operación de instancia de larga duración.

gcloud

Usa gcloud spanner operations describe para verificar el progreso de una operación de copia de seguridad o restablecimiento.

1. Obtén el ID de operación:

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

   Reemplaza lo siguiente:

   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.
   • DATABASE-NAME: Es el nombre de la base de datos.

2. Ejecuta gcloud spanner operations describe:

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

   Reemplaza lo siguiente:

   • OPERATION-ID: El ID de la operación que deseas verificar.
   • INSTANCE-NAME: Es el nombre de la instancia de Spanner.
   • DATABASE-NAME: Es el nombre de la base de datos de Spanner.

   En la sección progress del resultado, se muestra el porcentaje de la operación que se completó. El resultado es similar al siguiente:

   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

Obtén el ID de operación:

 gcloud spanner operations list 

   --instance=INSTANCE-NAME 

   --database=DATABASE-NAME 

   --type=DATABASE_UPDATE_DDL
 

Reemplaza lo siguiente:

• INSTANCE-NAME: Es el nombre de la instancia de Spanner.
• DATABASE-NAME: Es el nombre de la base de datos.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• PROJECT-ID: El ID del proyecto.
• INSTANCE-ID: El ID de la instancia.
• DATABASE-ID: Es el ID de la base de datos.
• OPERATION-ID: Es el ID de la operación.

Método HTTP y URL:

GET https://spanner.googleapis.com/v1/projects/PROJECT-ID/instances/INSTANCE-ID/databases/DATABASE-ID/operations/OPERATION-ID

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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: El siguiente comando supone que accediste a la CLI de gcloud con tu cuenta de usuario mediante la ejecución de gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Si la operación tarda demasiado, puedes cancelarla. Para obtener más información, consulta Cómo cancelar una operación de copia de seguridad de larga duración.

Enumera las operaciones de copia de seguridad o restablecimiento de larga duración

Usa projects.instances.backups.operations.list para enumerar las operaciones en una sola copia de seguridad o projects.instances.backupOperations.list para generar una lista de todas las operaciones de copia de seguridad de la instancia.

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

2. En nombre, ingresa lo siguiente:

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • BACKUP-NAME: Es el nombre de la copia de seguridad.
   • OPERATION-ID: Es el ID de las operaciones.

3. Haz clic en Ejecutar. La respuesta contiene una lista de operaciones de larga duración.

Cancela una operación de copia de seguridad de larga duración

Usa projects.instances.backups.operations.cancel para cancelar una operación de copia de seguridad de larga duración.

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

2. En nombre, ingresa el nombre de la operación de copia de seguridad de larga duración como se muestra en la respuesta de esa operación.

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

   Reemplaza lo siguiente:

   • PROJECT-ID: El ID del proyecto.
   • INSTANCE-NAME: el nombre de la instancia.
   • BACKUP-NAME: Es el nombre de la copia de seguridad.
   • OPERATION-ID: Es el ID de las operaciones.

   También puedes recuperar el nombre de la operación de copia de seguridad si enumeras las operaciones de copia de seguridad de larga duración.

3. Haz clic en Ejecutar.