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 d'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éthode dont l'exécution peut prendre un temps considérable. Spanner crée des opérations de longue durée pour différentes actions liées aux instances, aux bases de données et aux sauvegardes. 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. Si l'opération prend plus de temps que prévu, vous pouvez utiliser gcloud pour vérifier sa progression. Si l'opération ne répond pas, vous pouvez utiliser gcloud pour l'annuler.

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 des opérations de longue durée, ainsi que supprimer les opérations de longue durée portant sur des instances.

Vous pouvez vérifier et gérer les opérations de longue durée avec les éléments suivants:

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

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 l'avancement 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 section 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 l'avancement d'une opération d'instance de longue durée

La méthode projects.instances.operations.get permet de 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 au début 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 d'instance de longue durée:

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 extraire 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 de façon répétée jusqu'à ce que l'opération soit terminée. Observez 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 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.

   Pour extraire le nom de cette opération d'instance, vous pouvez également répertorier 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.

   Pour extraire le nom de cette opération d'instance, vous pouvez également répertorier 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

La méthode projects.instances.databases.operations.get permet de vérifier la progression d'une opération de base de données de longue durée.

Voici un exemple de 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 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.

   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. 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. Observez 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

La méthode projects.instances.databases.operations.cancel permet d'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.

   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 de schéma

Les opérations de mise à jour de schéma de longue durée sont les suivantes :

• 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 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, la barre de progression de la colonne Heure de fin indique 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 de l'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 de la sortie indique le pourcentage de l'opération terminée. 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 de l'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 ci-dessous, 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 de l'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

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 de l'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 de l'opération de mise à jour de schéma de longue durée.

   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.

   Pour extraire le nom de cette opération de mise à jour du schéma, vous pouvez également répertorier 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 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, la barre de progression de la colonne Heure de fin indique 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 de l'opération:

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

   Remplacez les éléments suivants :

   • INSTANCE-NAME: nom de l'instance Spanner.
   • DATABASE-NAME: nom de la base de données.
   • TYPE: type de l'opération. Les valeurs possibles sont BACKUP et DATABASE_RESTORE.

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 de l'opération terminée. 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 de l'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 ci-dessous, 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 associées à une même 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

La méthode projects.instances.backups.operations.cancel permet d'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 extraire le nom de cette opération de sauvegarde en répertoriant les opérations de sauvegarde de longue durée.

3. Cliquez sur Exécuter.