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 opérations de l'API REST.

Les opérations de longue durée sont des appels de méthodes dont l'exécution peut prendre un temps considérable. Spanner crée des opérations de longue durée pour plusieurs actions d'instance, de base de données et de sauvegarde. Considérez par exemple la méthode servant à restaurer une base de données, projects.instances.databases.restore.

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. Spanner fournit des API d'opérations 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

Gérer les opérations Spanner de longue durée avec l'API REST

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	Non compatible
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 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.

Voici un exemple de réponse renvoyée par projects.instances.databases.create :

  {
    "name": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance/databases/example-db/operations/_auto_1492721321097206",
    "metadata": {
      "@type": "type.googleapis.com/google.spanner.admin.database.v1.CreateDatabaseMetadata",
      "database": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance/databases/example-db"
    }
  }

La valeur name 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 nommée projects/PROJECT-ID/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. Cliquez sur 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. Exemple :

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

   Remplacez les éléments suivants :

   • PROJECT-ID par l'ID du projet.
   • OPERATION-ID par l'ID d'opération.

   Récupérez le nom de l'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 de façon répétée jusqu'à ce que l'opération soit terminée. Utilisez un intervalle entre chaque requête. Par exemple, vous pouvez envoyer 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. Cliquez sur projects.instances.databases.operations.list.

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

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

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

La méthode projects.instances.databases.operations.cancel permet d'annuler une opération de base de données de longue durée.

1. Cliquez sur 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. Exemple :

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

   (Remplacez cette valeur par le nom d'opération que vous avez reçu.) Pour extraire le nom de cette opération de base de données, vous pouvez également répertorier les opérations de base de données de longue durée.

3. Cliquez sur Exécuter.

Opérations de mise à jour du 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 l'opération est toujours en cours d'exécution, la barre de progression de la colonne Heure de fin indique le pourcentage d'achèvement de l'opération, 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 par le nom de l'instance Spanner.
   • DATABASE-NAME par le 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 de la sortie indique le pourcentage d'achèvement de l'opération. Le résultat 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 par le nom de l'instance Spanner.
• DATABASE-NAME par le 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 gcloud CLI avec votre compte utilisateur, via la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la gcloud CLI. 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 par le nom de l'instance Spanner.
• DATABASE-NAME par le nom de la base de données.

Le résultat ressemble à ceci :

OPERATION-ID     STATEMENTS                                                                                          DONE   @TYPE
_auto_op_123456  CREATE INDEX SingersByFirstLastName ON Singers(FirstName, LastName)                                 False  UpdateDatabaseDdlMetadata
               CREATE INDEX SongsBySingerAlbumSongName ON Songs(SingerId, AlbumId, SongName), INTERLEAVE IN Albums
_auto_op_234567                                                                                                      True   CreateDatabaseMetadata

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 par le nom de l'instance Spanner.
   • DATABASE-NAME par le nom de la base de données.

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

   gcloud 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

La méthode projects.instances.databases.operations.cancel vous permet d'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 par le nom de l'instance Spanner.
   • DATABASE-NAME par le nom de la base de données.

2. Cliquez sur 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. Exemple :

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

   Remplacez les éléments suivants :

   • PROJECT-ID par l'ID du projet.
   • OPERATION-ID par l'ID d'opération.

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

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 l'opération est toujours en cours d'exécution, la barre de progression de la colonne Heure de fin indique le pourcentage d'achèvement de l'opération, 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é ci-dessous:

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 par le nom de l'instance Spanner.
   • DATABASE-NAME par le 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 de la sortie indique le pourcentage d'achèvement de l'opération. Le résultat 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 par le nom de l'instance Spanner.
• DATABASE-NAME par le 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 gcloud CLI avec votre compte utilisateur, via la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la gcloud CLI. 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 associées à une même sauvegarde ou projects.instances.backupOperations.list pour répertorier toutes les opérations de sauvegarde de l'instance.

1. Cliquez sur projects.instances.backups.operations.list.

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

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

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

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

1. Cliquez sur 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. Exemple :

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

   Remplacez _auto_1492721321097206 par l'ID de votre opération.

   Pour récupérer le nom de l'opération de sauvegarde, répertoriez les opérations de sauvegarde de longue durée.

3. Cliquez sur Exécuter.

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/<VAR>PROJECT-ID</VAR>/instances/test-instance/operations/<VAR>OPERATION-ID</VAR>",
    "metadata": {
      "@type": "type.googleapis.com/google.spanner.admin.instance.v1.CreateInstanceMetadata",
      "instance": {
        "name": "projects/<VAR>PROJECT-ID</VAR>/instances/test-instance",
        "config": "projects/<VAR>PROJECT-ID</VAR>/instanceConfigs/regional-us-central1",
        "displayName": "Test Instance",
        "nodeCount": 1,
        "state": "READY"
      },
      "startTime": "2017-04-24T22:45:41.130854Z"
    }
  }

La valeur name 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/PROJECT-ID/instances/test-instance/operations/<VAR>OPERATION-ID</VAR>.

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

1. Cliquez sur 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/test-instance/operations/OPERATION-ID

   Remplacez les éléments suivants :

   • PROJECT-ID par l'ID du projet.
   • OPERATION-ID par l'ID d'opération.

   Pour récupérer le nom de cette opération d'instance, répertoriez 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 de façon répétée jusqu'à ce que l'opération soit terminée. Utilisez un intervalle entre chaque requête. Par exemple, vous pouvez envoyer 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. Cliquez sur projects.instances.operations.list.

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

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

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 permet d'annuler une opération d'instance de longue durée.

1. Cliquez sur 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. Exemple :

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

   Remplacez les éléments suivants :

   • PROJECT-ID par l'ID du projet.
   • OPERATION-ID par l'ID d'opération.

   Pour récupérer le nom de cette opération d'instance, répertoriez 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. Exemple :

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

   Remplacez les éléments suivants :

   • PROJECT-ID par l'ID du projet.
   • OPERATION-ID par l'ID d'opération.

   Pour récupérer le nom de l'opération d'instance, répertoriez les opérations d'instance de longue durée.

3. Cliquez sur Exécuter. L'opération est supprimée.