Gérer et observer les opérations de longue durée

Cette page explique comment gérer le cycle de vie d'une opération de longue durée Spanner à l'aide des commandes gcloud spanner operations et de l'API REST des opérations. Certaines procédures peuvent également être effectuées dans la console Google Cloud.

Les opérations de longue durée sont des appels de méthodes dont l'exécution peut prendre beaucoup de temps. Spanner crée des opérations de longue durée pour plusieurs actions d'instance, de base de données et de sauvegarde. La méthode permettant de restaurer une base de données, projects.instances.databases.restore, en est un exemple. Lorsque vous restaurez une base de données, le service Spanner crée une opération de longue durée pour suivre la progression de la restauration. Si l'opération prend plus de temps que prévu, vous pouvez en vérifier la progression à l'aide de gcloud. Si l'opération ne répond pas, vous pouvez l'annuler à l'aide de gcloud.

Spanner fournit des API d'opération qui vous permettent de vérifier la progression des opérations de longue durée. Vous pouvez également répertorier et annuler les opérations de longue durée, et supprimer les opérations d'instance de longue durée.

Vous pouvez vérifier et gérer les opérations de longue durée à l'aide des éléments suivants:

• Bibliothèques clientes Spanner
• Outil de ligne de commande gcloud
• La console Google Cloud

Commandes de l'API REST pour la gestion des opérations

Gérez vos opérations de longue durée Spanner à l'aide des méthodes REST suivantes:

Action	Opérations de base de données de longue durée	Opérations d'instance de longue durée
Annuler une opération de longue durée	cancel	cancel
Supprimer une opération de longue durée	Non compatible	delete
Vérifier la progression d'une opération de longue durée	get	get
Répertorier les opérations de longue durée	list	list

Pour en savoir plus sur l'utilisation de REST avec Spanner, consultez la page Premiers pas avec Spanner à l'aide de REST.

Opérations d'instance :

Les opérations de longue durée relatives aux instances sont les suivantes :

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

Vérifier la progression d'une opération d'instance de longue durée

Utilisez projects.instances.operations.get pour vérifier la progression d'une opération d'instance de longue durée.

Voici un exemple de réponse renvoyée par 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"
    }
  }

La valeur name située en haut de la réponse indique que le service Spanner a créé une opération d'instance de longue durée nommée projects/test01/instances/test-instance/operations/_auto_1492721321097206.

Pour vérifier la progression de l'opération de longue durée de l'instance:

1. Accédez à projects.instances.operations.get.

2. Pour le champ name, saisissez le nom de l'opération d'instance de longue durée, comme indiqué dans la réponse à la commande projects.instances.create ou projects.instances.patch. Exemple :

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

   Pour récupérer le nom de cette opération d'instance, vous pouvez répertorier les opérations d'instance de longue durée.

3. Cliquez sur Exécuter. Lorsqu'une opération est terminée, le champ done est défini sur true.

Pour obtenir des mises à jour continues, appelez la méthode projects.instances.databases.operations.get à plusieurs reprises jusqu'à ce que l'opération soit terminée. Utilisez un intervalle entre chaque requête. Par exemple, envoyez une requête toutes les 10 secondes.

Répertorier les opérations d'instance de longue durée

La méthode projects.instances.operations.list vous permet de répertorier les opérations d'instance de longue durée.

1. Accédez à projects.instances.operations.list.

2. Pour le champ name, saisissez la valeur suivante :

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

3. Cliquez sur Exécuter. La réponse contient une liste d'opérations de longue durée.

Annuler une opération d'instance de longue durée

La méthode projects.instances.operations.cancel vous permet d'annuler une opération d'instance de longue durée.

1. Accédez à projects.instances.operations.cancel.

2. Pour le champ name, saisissez le nom de l'opération d'instance de longue durée, comme indiqué dans la réponse à cette opération.

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

   Vous pouvez également récupérer le nom de cette opération d'instance en répertoriant les opérations d'instance de longue durée.

3. Cliquez sur Exécuter.

Supprimer une opération d'instance de longue durée

La méthode projects.instances.operations.delete vous permet de supprimer une opération d'instance de longue durée.

1. Cliquez sur projects.instances.operations.delete.

2. Pour le champ name, saisissez le nom de l'opération d'instance de longue durée, comme indiqué dans la réponse à cette opération.

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

   Vous pouvez également récupérer le nom de cette opération d'instance en répertoriant les opérations d'instance de longue durée.

3. Accédez à Execute (Exécuter). L'opération est supprimée.

Opérations de base de données

Les opérations de longue durée relatives aux bases de données sont les suivantes :

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

Vérifier la progression d'une opération de base de données de longue durée

Utilisez projects.instances.databases.operations.get pour vérifier la progression d'une opération de base de données de longue durée.

Par exemple, voici une réponse 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"
  }
}

La valeur name figurant en haut de la réponse indique que le service Spanner a créé une opération de base de données de longue durée appelée projects/test01/instances/test-instance/databases/example-db/operations/_auto_1492721321097206.

Pour vérifier la progression de l'opération de base de données de longue durée:

1. Accédez à projects.instances.databases.operations.get.

2. Pour le champ name, saisissez le nom de l'opération de base de données de longue durée, comme indiqué dans la réponse à la commande projects.instances.databases.create ou projects.instances.databases.updateDdl.

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

   Vous pouvez également récupérer le nom de cette opération de base de données en répertoriant les opérations de base de données de longue durée.

3. Cliquez sur Exécuter. Lorsqu'une opération est terminée, le champ done est défini sur true.

Pour obtenir des mises à jour continues, appelez la méthode projects.instances.databases.operations.get à plusieurs reprises jusqu'à ce que l'opération soit terminée. Utilisez un intervalle entre chaque requête. Par exemple, envoyez une requête toutes les 10 secondes.

Répertorier les opérations de base de données de longue durée

La méthode projects.instances.databases.operations.list vous permet de répertorier les opérations de base de données de longue durée.

1. Accédez à projects.instances.databases.operations.list.

2. Pour le champ name, saisissez la valeur suivante :

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

3. Cliquez sur Exécuter. La réponse contient une liste d'opérations de longue durée.

Annuler une opération de base de données de longue durée

Utilisez projects.instances.databases.operations.cancel pour annuler une opération de base de données de longue durée.

1. Accédez à projects.instances.databases.operations.cancel.

2. Pour le champ name, saisissez le nom de l'opération de base de données de longue durée, comme indiqué dans la réponse à cette opération.

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

   Vous pouvez également récupérer le nom de cette opération de base de données en répertoriant les opérations de base de données de longue durée.

3. Cliquez sur Exécuter.

Opérations de mise à jour de schéma

Voici les opérations de mise à jour de schéma de longue durée.

• projects.instances.databases.updateDdl

Vérifier la progression d'une opération de mise à jour de schéma de longue durée

Console

1. Dans le menu de navigation de Spanner, sélectionnez l'onglet Opérations. La page Opérations affiche la liste des opérations en cours d'exécution.

2. Recherchez l'opération de schéma dans la liste. Si elle est toujours en cours d'exécution, la barre de progression de la colonne End time (Heure de fin) affiche le pourcentage de l'opération terminée, comme illustré dans l'image suivante:

gcloud

Utilisez gcloud spanner operations describe pour vérifier la progression d'une opération.

1. Obtenez l'ID d'opération:

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

   Remplacez les éléments suivants :

   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME : nom de l'instance.
   • DATABASE-NAME: nom de la base de données.

2. Exécutez gcloud spanner operations describe :

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

   Remplacez les éléments suivants :

   • OPERATION-ID: ID de l'opération que vous souhaitez vérifier.
   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME: nom de la base de données Spanner.

   La section progress du résultat indique le pourcentage d'achèvement de l'opération. La sortie ressemble à ceci :

   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

Obtenez l'ID d'opération:

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

Remplacez les éléments suivants :

• INSTANCE-NAME: nom de l'instance Spanner.
• DATABASE-NAME: nom de la base de données.

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

• PROJECT-ID : ID du projet.
• INSTANCE-ID : ID de l'instance.
• DATABASE-ID: ID de la base de données.
• OPERATION-ID: ID de l'opération.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

{
...
    "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 l'opération prend trop de temps, vous pouvez l'annuler. Pour en savoir plus, consultez la section Annuler une opération de mise à jour de schéma de longue durée.

Répertorier les opérations de mise à jour de schéma de longue durée

gcloud

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

Remplacez les éléments suivants :

• INSTANCE-NAME: nom de l'instance Spanner.
• DATABASE-NAME: nom de la base de données.

La sortie ressemble à ceci :

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

Annuler une opération de mise à jour de schéma de longue durée

gcloud

1. Obtenez l'ID d'opération:

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

   Remplacez les éléments suivants :

   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME: nom de la base de données.

2. Utilisez gcloud spanner operations cancel pour annuler une opération de mise à jour de schéma de longue durée.

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

   Remplacez les éléments suivants :

   • OPERATION-ID: ID de l'opération que vous souhaitez vérifier.
   • INSTANCE-NAME: nom de l'instance Spanner.

REST V1

Utilisez projects.instances.databases.operations.cancel pour annuler une opération de mise à jour de schéma de longue durée.

1. Obtenez l'ID d'opération:

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

   Remplacez les éléments suivants :

   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME: nom de la base de données.

2. Accédez à projects.instances.databases.operations.cancel.

3. Pour le champ name, saisissez le nom de l'opération de mise à jour de schéma de longue durée, comme indiqué dans la réponse à cette opération.

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • OPERATION-ID: ID des opérations.

   Vous pouvez également récupérer le nom de l'opération de mise à jour du schéma en répertoriant les opérations d'instance de longue durée.

4. Cliquez sur Exécuter. L'opération s'arrête.

Opérations de sauvegarde et de restauration

Les opérations de sauvegarde de longue durée sont les suivantes :

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

Vérifier la progression d'une opération de sauvegarde ou de restauration de longue durée

Console

Sauvegarde

1. Dans le menu de navigation de Spanner, sélectionnez l'onglet Opérations. La page Opérations affiche la liste des opérations en cours d'exécution.

2. Recherchez l'opération de schéma dans la liste. Si elle est toujours en cours d'exécution, la barre de progression de la colonne End time (Heure de fin) affiche le pourcentage de l'opération terminée, comme illustré dans l'image suivante:

Restaurer

Pour vérifier la progression de l'opération de restauration, consultez l'indicateur de progression qui s'affiche pendant la restauration, comme illustré dans l'image suivante:

Si l'opération prend trop de temps, vous pouvez l'annuler. Pour en savoir plus, consultez la section Annuler une opération d'instance de longue durée.

gcloud

Utilisez gcloud spanner operations describe pour vérifier la progression d'une opération de sauvegarde ou de restauration.

1. Obtenez l'ID d'opération:

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

   Remplacez les éléments suivants :

   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME: nom de la base de données.

2. Exécutez gcloud spanner operations describe :

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

   Remplacez les éléments suivants :

   • OPERATION-ID: ID de l'opération que vous souhaitez vérifier.
   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME: nom de la base de données Spanner.

   La section progress du résultat indique le pourcentage d'achèvement de l'opération. La sortie ressemble à ceci :

   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

Obtenez l'ID d'opération:

 gcloud spanner operations list 

   --instance=INSTANCE-NAME 

   --database=DATABASE-NAME 

   --type=DATABASE_UPDATE_DDL
 

Remplacez les éléments suivants :

• INSTANCE-NAME: nom de l'instance Spanner.
• DATABASE-NAME: nom de la base de données.

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

• PROJECT-ID : ID du projet.
• INSTANCE-ID : ID de l'instance.
• DATABASE-ID: ID de la base de données.
• OPERATION-ID: ID de l'opération.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

{
...
    "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 l'opération prend trop de temps, vous pouvez l'annuler. Pour en savoir plus, consultez la section Annuler une opération de sauvegarde de longue durée.

Répertorier les opérations de sauvegarde ou de restauration de longue durée

Utilisez projects.instances.backups.operations.list pour répertorier les opérations d'une seule sauvegarde ou projects.instances.backupOperations.list pour répertorier toutes les opérations de sauvegarde de l'instance.

1. Accédez à projects.instances.backups.operations.list.

2. Pour le champ name, saisissez la valeur suivante :

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • BACKUP-NAME: nom de la sauvegarde.
   • OPERATION-ID: ID des opérations.

3. Cliquez sur Exécuter. La réponse contient une liste d'opérations de longue durée.

Annuler une opération de sauvegarde de longue durée

Utilisez projects.instances.backups.operations.cancel pour annuler une opération de sauvegarde de longue durée.

1. Accédez à projects.instances.backups.operations.cancel.

2. Pour le champ name, saisissez le nom de l'opération de sauvegarde de longue durée, comme indiqué dans la réponse de l'opération de sauvegarde de longue durée.

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

   Remplacez les éléments suivants :

   • PROJECT-ID : ID du projet.
   • INSTANCE-NAME : nom de l'instance.
   • BACKUP-NAME: nom de la sauvegarde.
   • OPERATION-ID: ID des opérations.

   Vous pouvez également récupérer le nom de l'opération de sauvegarde en répertoriant les opérations de sauvegarde de longue durée.

3. Cliquez sur Exécuter.