Administrar y observar 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 mediante 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 instancias, bases de datos y copias 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 operaciones de larga duración y borrar operaciones de instancia de larga duración.

Puedes verificar y administrar operaciones de larga duración con las siguientes opciones:

• 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
Comprueba 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.

   Para recuperar el nombre de la operación de instancia, puedes enumerar las operaciones de instancia de larga duración.

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

Para obtener actualizaciones continuas, invoca el método projects.instances.databases.operations.get de forma repetida hasta que la operación finalice. 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 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 instancia si enumeras las operaciones de instancia de larga duración.

3. Navega a Ejecutar. Se borró 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

Comprueba 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, haz lo siguiente:

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 realiza una operación, el campo done se establece en true.

Para obtener actualizaciones continuas, invoca el método projects.instances.databases.operations.get de forma repetida hasta que la operación finalice. 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 de 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 del 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 del esquema en la lista. Si aún está en ejecución, la barra de progreso de la columna Hora de finalización muestra el porcentaje de finalización de la operación, como se observa 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: Es 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 Cancela una operación de actualización del esquema de larga duración.

Enumera las operaciones de actualización del 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 del 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 del esquema de larga duración.

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

   Reemplaza lo siguiente:

   • OPERATION-ID: Es el ID 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 del 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 de la operación de actualización del esquema de larga duración.

   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 detiene 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 comprobar 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 en ejecución.

2. Busca la operación del esquema en la lista. Si aún está en ejecución, la barra de progreso de la columna Hora de finalización muestra el porcentaje de finalización de la operación, como se observa 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: Es 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 Cancela 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 de una sola copia de seguridad o projects.instances.backupOperations.list para enumerar todas las operaciones de copia de seguridad en 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 enumerando las operaciones de copia de seguridad de larga duración.

3. Haz clic en Ejecutar.