Importer des fichiers Avro Spanner

Cette page explique comment importer des bases de données Spanner dans Spanner à l'aide de la console Google Cloud. Pour importer des fichiers Avro depuis une autre source, consultez Importez des données à partir de bases de données autres que Spanner.

Ce processus fait appel à Dataflow. Il consiste à importer des données à partir d'un dossier de bucket Cloud Storage contenant un ensemble de fichiers Avro et de fichiers manifestes JSON. Processus d'importation n'accepte que les fichiers Avro exportés à partir de Spanner.

Pour importer une base de données Spanner à l'aide de l'API REST ou de gcloud CLI, procédez comme suit : suivez les étapes de la section Avant de commencer , puis consultez les instructions détaillées de la section Cloud Storage Avro vers Spanner.

Avant de commencer

Pour importer une base de données Spanner, vous devez d'abord activer Spanner, Cloud Storage, API Compute Engine et Dataflow:

Activer les API

Vous devez également disposer d'un quota suffisant, ainsi que des autorisations IAM requises.

Exigences en matière de quota

Voici les conditions de quota requises pour les jobs d'importation:

• Spanner: vous devez disposer d'une capacité de calcul suffisante pour prendre en charge la quantité de données que vous importez. Aucune capacité de calcul supplémentaire n'est requise pour importer une base de données, mais il peut s'avérer nécessaire d'ajouter de la capacité de calcul pour que la tâche se termine dans un délai raisonnable. Pour en savoir plus, consultez Optimiser les missions.
• Cloud Storage : pour effectuer des importations, vous devez disposer d'un bucket contenant les fichiers que vous avez exportés auparavant. Il n'est pas nécessaire de spécifier une taille pour ce bucket.
• Dataflow : les tâches d'importation sont soumises aux mêmes exigences que les autres tâches Dataflow en ce qui concerne les quotas Compute Engine, aussi bien pour l'utilisation de processeurs et d'espace disque que pour le nombre d'adresses IP.

• Compute Engine : avant d'exécuter une tâche d'importation, vous devez définir les quotas initiaux Compute Engine utilisés par Dataflow. Ces quotas représentent les quantités maximales de ressources que Dataflow pourra utiliser pour votre tâche. Les valeurs de départ recommandées sont les suivantes :

  • Processeurs : 200
  • Adresses IP en cours d'utilisation : 200
  • Disque persistant standard : 50 To

  En règle générale, vous n'avez aucun autre ajustement à effectuer. Dataflow assure un autoscaling qui vous permet de ne payer que pour les ressources réellement utilisées lors de l'importation. S'il apparaît que votre tâche pourrait utiliser davantage de ressources, l'interface utilisateur de Dataflow affiche une icône d'avertissement, mais cela n'empêche normalement pas la tâche d'aboutir.

Exigences IAM

Pour importer une base de données, vous devez également disposer de rôles IAM accordant des autorisations suffisantes pour utiliser tous les services impliqués dans une tâche d'importation. Pour en savoir plus sur l'attribution de rôles et d'autorisations, consultez la page Appliquez des rôles IAM.

Pour importer une base de données, vous avez besoin des rôles suivants :

• Au niveau du projet Google Cloud :
  • Lecteur Spanner (roles/spanner.viewer)
  • Administrateur Dataflow (roles/dataflow.admin)
  • Administrateur de l'espace de stockage (roles/storage.admin)
• Au niveau de l'instance ou de la base de données Spanner, ou au niveau Au niveau du projet Google Cloud: <ph type="x-smartling-placeholder">
  </ph>
  • Lecteur de bases de données Spanner (roles/spanner.databaseReader)
  • Administrateur de bases de données Spanner (roles/spanner.databaseAdmin)

Remarque :Le rôle d'administrateur de bases de données Spanner n'est requis que pour les jobs d'importation.

Facultatif: Rechercher le dossier de votre base de données dans Cloud Storage

Pour trouver le dossier contenant votre base de données exportée dans le fichier dans la console Google Cloud, accédez au navigateur Cloud Storage, puis cliquez sur sur le bucket contenant le dossier exporté.

Accéder au navigateur Cloud Storage

Le nom du dossier contenant vos données exportées commence par l'ID de votre instance, suivi du nom de la base de données et de l'horodatage de la tâche d'exportation. Ce dossier contient :

• Un fichier spanner-export.json.
• Un fichier TableName-manifest.json pour chaque table de la base de données que vous avez exportée.

• Un ou plusieurs fichiers TableName.avro-#####-of-#####. Le premier nombre figurant dans l'extension .avro-#####-of-##### représente l'index du fichier Avro compté à partir de zéro, tandis que le second correspond au nombre de fichiers Avro générés pour chaque table.

  Par exemple, Songs.avro-00001-of-00002 est le deuxième des deux fichiers contenant les données de la table Songs.

• Un fichier ChangeStreamName-manifest.json pour chaque flux de modifications dans la base de données que vous exportées.

• A ChangeStreamName.avro-00000-of-00001 pour chaque flux de modifications. Ce fichier contient des données vides avec uniquement le schéma Avro du flux de modifications.

Importer une base de données

Pour importer votre base de données Spanner de Cloud Storage dans votre procédez comme suit.

1. Accédez à la page Instances de Spanner.

   Accéder à la page Instances

2. Cliquez sur le nom de l'instance qui contiendra la base de données importée.

3. Cliquez sur l'élément de menu Importer/Exporter dans le volet de gauche, puis sur le bouton Importer.

4. Sous Sélectionner un dossier source, cliquez sur Parcourir.

5. Recherchez le bucket contenant votre exportation dans la liste initiale, ou cliquez sur Rechercher  pour le retrouver en filtrant la liste. Double-cliquez sur le bucket pour afficher les dossiers qu'il contient.

6. Recherchez le dossier contenant vos fichiers exportés et cliquez dessus pour le sélectionner.

   Remarque : Veillez à sélectionner le dossier créé par la tâche d'exportation et non un dossier de niveau supérieur contenant le dossier exporté.

7. Cliquez sur Sélectionner.

8. Saisissez un nom pour la nouvelle base de données, créée par Spanner lors de la processus d'importation. Vous ne pouvez pas spécifier un nom de base de données existant déjà dans votre instance.

9. Choisissez le dialecte de la nouvelle base de données (GoogleSQL ou PostgreSQL).

10. (Facultatif) Pour protéger la nouvelle base de données à l'aide d'une clé de chiffrement gérée par le client, cliquez surAfficher les options de chiffrement et sélectionnez Utiliser une clé de chiffrement gérée par le client (CMEK). Sélectionnez ensuite une clé dans la liste déroulante.

11. Sélectionnez une région dans le menu déroulant Sélectionner une région pour la tâche d'importation.

    Remarque :Pour éviter des frais de transfert de données sortants, choisissez une région qui chevauche l'emplacement de votre bucket Cloud Storage. Voir Pour en savoir plus, sélectionnez une région ci-dessous.

12. (Facultatif) Pour chiffrer l'état du pipeline Dataflow avec une clé de chiffrement gérée par le client, cliquez sur Afficher les options de chiffrement puis sélectionnez Utiliser une clé de chiffrement gérée par le client (CMEK). Sélectionnez ensuite une clé dans la liste déroulante.

13. Cochez la case sous Confirmer les débits pour confirmer en plus de ceux liés à votre instance Spanner existante.

14. Cliquez sur Importer.

    La console Google Cloud affiche la page Détails de la base de données, qui affiche désormais une zone décrivant votre job d'importation et indiquant le temps écoulé temps:

    

Une fois le job terminé ou terminé, la console Google Cloud affiche un sur la page Détails de la base de données. Si la tâche a abouti, un message tel que celui-ci apparaît :

Remarque :Une fois le job d'importation Dataflow terminé, Spanner crée des index et des clés étrangères pour votre base de données importée. Pendant la création de l'index, la console Google Cloud affiche un icône de progression pour indiquer qu'une opération de longue durée est en cours. Cette icône apparaît à côté du nom de l'index dans la hiérarchie de la base de données, à gauche sur la page Détails de la base de données. Le remplacement de l'icône de tâche en cours par l'icône d'index  indique que la création de l'index est terminée. Vous pouvez interroger SPANNER_STATE la vue INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS pour voir la progression de la création de clés étrangères.

Si la tâche n'a pas abouti, un message d'échec apparaît :

Si votre job échoue, recherchez l'erreur dans les journaux Dataflow de ce job. et consultez Résoudre les problèmes d'échec des jobs d'importation.

Remarque sur l'importation des colonnes générées et des flux de modifications

Spanner utilise la définition de chaque colonne générée. dans le schéma Avro pour recréer cette colonne. Spanner calcule automatiquement les valeurs de colonne générées lors de l'importation.

De même, Spanner utilise la définition de chaque changement stream dans le schéma Avro pour le recréer lors de l'importation. Modifier les données de flux ne sont ni exportées, ni importées via Avro. Par conséquent, les flux de modifications associés à une base de données récemment importée auront aucun enregistrement de données modifiées.

Remarque sur l'importation de séquences

Chaque séquence (GoogleSQL, PostgreSQL) que Spanner exporte utilise la fonction GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) pour capturer son état actuel. Spanner ajoute un tampon de 1 000 au compteur et écrit les nouvelles valeurs une valeur compteur aux propriétés du champ d'enregistrement. Notez qu'il ne s'agit que d'une pour éviter les erreurs de valeur en double qui peuvent se produire après l'importation. Ajustez le compteur de séquence réel s'il y a plus d'écritures sur la la base de données source lors de l'exportation des données.

Lors de l'importation, la séquence commence à partir de ce nouveau compteur et non du compteur. qui se trouvent dans le schéma. Si nécessaire, vous pouvez utiliser la commande ALTER SEQUENCE (GoogleSQL, PostgreSQL) pour passer à un nouveau compteur.

Choisissez une région pour votre job d'importation

Vous pouvez choisir une autre région en fonction de l'emplacement bucket Cloud Storage. Pour éviter frais de transfert de données sortantes, choisissez une région correspond à l'emplacement de votre bucket Cloud Storage.

• Si l'emplacement de votre bucket Cloud Storage est une région, vous peuvent profiter de l'utilisation gratuite du réseau en choisissant la même région pour votre job d'importation, en supposant que cette région est disponible.

• Si l'emplacement de votre bucket Cloud Storage est birégional, vous pouvez profiter de l'utilisation gratuite du réseau en choisissant l'une des deux régions qui composent l'emplacement birégional de votre job d'importation, en supposant que l'une des régions est disponible.

• Si une région située dans la même zone géographique n'est pas disponible pour votre job d'importation ou si votre L'emplacement du bucket Cloud Storage est multirégional, des frais de transfert de données sortantes s'appliquent. Consulter Cloud Storage de transfert de données pour choisir une région qui entraîne le les frais de transfert de données les plus bas.

Afficher ou dépanner des jobs dans l'interface utilisateur de Dataflow

Après avoir démarré un job d'importation, vous pouvez en afficher les détails, y compris dans la section "Dataflow" de la console Google Cloud.

Afficher les détails d'un job Dataflow

Pour afficher les détails des tâches d'importation/exportation exécutées au cours de la dernière semaine, y compris les tâches en cours d'exécution :

1. Accédez à la page Présentation de la base de données correspondant à la base de données.
2. Cliquez sur l'élément de menu du volet Importations/Exportations à gauche. La page Importations/Exportations de la base de données affiche la liste des tâches récentes.

3. Sur la page Importations/Exportations de la base de données, cliquez sur le nom de la tâche dans la colonne Nom de la tâche Dataflow :

   

   La console Google Cloud affiche les détails de Dataflow d'un projet.

Pour afficher une tâche que vous avez exécutée il y a plus d'une semaine :

1. Accédez à la page des jobs Dataflow dans la console Google Cloud.

   Accéder à la page Tâches

2. Recherchez votre tâche dans la liste, puis cliquez sur son nom.

   La console Google Cloud affiche les détails de Dataflow d'un projet.

Remarque : Les tâches de même type relatives à une même base de données portent toutes le même nom. Vous pouvez les distinguer les unes des autres d'après les valeurs spécifiées dans les colonnes Heure de début ou Heure de fin.

Afficher les journaux Dataflow associés à votre job

Pour afficher les journaux d'une tâche Dataflow, accédez à la page des détails de la tâche comme décrit ci-dessus, puis cliquez sur Journaux à droite du nom de la tâche.

Si une tâche échoue, recherchez les erreurs dans les journaux. Si des erreurs ont été enregistrées, leur nombre s'affiche à côté du bouton Logs (Journaux) :

Pour afficher les erreurs relatives à une tâche :

1. Cliquez sur le nombre d'erreurs affiché à côté du bouton Logs (Journaux).

   La console Google Cloud affiche les journaux du job. Vous devrez éventuellement faire défiler l'affichage pour voir les erreurs.

2. Repérez les entrées signalées par l'icône d'erreur .

3. Cliquez sur une entrée de journal pour développer son contenu.

Pour en savoir plus sur la résolution des problèmes liés aux jobs Dataflow, consultez la page Résolvez les problèmes liés à votre pipeline.

Résoudre les problèmes d'échec des jobs d'importation

Si les erreurs suivantes s'affichent dans les journaux de vos tâches :

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Consultez le Latence d'écriture de 99% dans les l'onglet Surveillance de votre base de données Spanner dans console Google Cloud. Si elle affiche des valeurs élevées (plusieurs secondes), cela signifie que l'instance est surchargée, ce qui entraîne l'expiration et l'échec de l'écriture.

L'une des causes de latence élevée est que le job Dataflow s'exécute sur un nombre trop important ce qui entraîne une charge excessive sur l'instance Spanner.

Pour spécifier une limite sur le nombre de nœuds de calcul Dataflow, au lieu d'utiliser la Onglet "Importer/Exporter" de la page "Détails de l'instance" de Spanner dans la console Google Cloud, vous devez démarrer à l'aide de l'API Dataflow Modèle Cloud Storage Avro vers Cloud Spanner et spécifiez le nombre maximal de nœuds de calcul comme décrit ci-dessous: <ph type="x-smartling-placeholder">

</ph>

• Si vous utilisez la console Dataflow, le paramètre Nombre maximal de nœuds de calcul se trouve dans la section Paramètres facultatifs de la page Créer une tâche à partir d'un modèle.

• Si vous utilisez gcloud, spécifiez l'argument max-workers. Exemple :

  gcloud dataflow jobs run my-import-job \
  --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
  --region=us-central1 \
  --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
  --max-workers=10
  

Optimiser les tâches d'importation lentes

Si vous avez adopté les paramètres initiaux suggérés plus haut, vous n'avez en principe aucun autre réglage à effectuer. Voici toutefois quelques possibilités d'optimisation supplémentaires à envisager si l'exécution de votre tâche est lente :

• Optimisez le job et l'emplacement des données: exécutez votre job Dataflow. dans la même région que celle où votre instance Spanner et bucket Cloud Storage.

• Assurez-vous de disposer de ressources Dataflow suffisantes: si le quotas Compute Engine pertinents limiter les ressources de votre job Dataflow, Page Dataflow dans la console Google Cloud affiche une icône d'avertissement et journal messages:

  

  Dans ce cas, l'augmentation des quotas en termes de processeurs, d'adresses IP en cours d'utilisation et de disques persistants standards peut accélérer l'exécution de votre tâche, mais également augmenter les frais facturés pour Compute Engine.

• Vérifiez l'utilisation du processeur Spanner: si vous constatez que le processeur de l'instance est supérieure à 65%, vous pouvez augmentez la capacité de calcul de cette instance. La capacité augmente Spanner et le job devrait s'accélérer, mais les frais engendrés Spanner.

Facteurs affectant les performances des tâches d'importation

Plusieurs facteurs influent sur le temps nécessaire pour mener à bien une tâche d'importation.

• Taille de la base de données Spanner: le traitement de davantage de données prend plus de temps et des ressources.

• Schéma de base de données Spanner, y compris:

  • Le nombre de tables
  • Taille des lignes
  • Le nombre d'index secondaires
  • Le nombre de clés étrangères
  • Nombre de flux de modifications

Notez que l'index et la clé étrangère création continue après le job d'importation Dataflow terminé. Les flux de modifications sont créés avant la fin du job d'importation. mais une fois toutes les données importées.

• Emplacement des données: les données sont transférées entre Spanner et Cloud Storage avec Dataflow. Dans l'idéal, ces trois composants doivent se trouver dans la même région. Dans le cas contraire, le déplacement des données entre les régions ralentit l'exécution de la tâche.

• Nombre de nœuds de calcul Dataflow : les nœuds de calcul Dataflow optimaux sont nécessaires pour de bonnes performances. En utilisant l'autoscaling, Dataflow choisit le nombre de nœuds de calcul pour la tâche en fonction de la quantité de travail à effectuer. Le nombre de nœuds de calcul sera toutefois limité par les quotas en matière de processeurs, d'adresses IP en cours d'utilisation et de disques persistants standards. L'interface utilisateur de Dataflow affiche une icône d'avertissement lorsque des limites de quota sont atteintes. Dans ce cas, la progression est ralentie, mais la tâche doit néanmoins aboutir. L'autoscaling peut surcharger Spanner et entraîner des erreurs en cas d' une grande quantité de données à importer.

• Charge existante sur Spanner: une tâche d'importation ajoute une charge importante du processeur sur une instance Spanner. Si cette instance présentait déjà une charge importante, l'exécution de la tâche est ralentie.

• Quantité de capacité de calcul Spanner: si l'utilisation du processeur pour l'instance est supérieure à 65%, le job s'exécute plus lentement.

Régler les nœuds de calcul pour obtenir de bonnes performances d'importation

Lors du démarrage d'un job d'importation Spanner, Dataflow les nœuds de calcul doivent être définis sur une valeur optimale pour obtenir de bonnes performances. Trop de nœuds de calcul sur Spanner et un nombre insuffisant de nœuds de calcul entraîne les performances d'importation.

Le nombre maximal de nœuds de calcul dépend fortement de la taille des données, Idéalement, l'utilisation totale du processeur Spanner doit être comprise entre de 70% à 90%. Cela offre un bon équilibre entre Spanner l'efficacité et une exécution sans erreur des tâches.

Pour atteindre cet objectif d'utilisation dans la majorité des schémas et des scénarios, nous devons recommandent un nombre maximal de vCPU de nœud de calcul compris entre 4 et 6 fois le nombre de Nœuds Spanner.

Par exemple, pour une instance Spanner à 10 nœuds, avec n1-standard-2 vous devez définir le nombre maximal de nœuds de calcul sur 25, soit 50 vCPU.