Exporter et importer des données

Vous pouvez utiliser le service d'exportation et d'importation géré Cloud Firestore pour récupérer d'une suppression accidentelle de données et exporter des données pour un traitement hors ligne. Vous pouvez exporter tous les documents ou seulement des collections spécifiques. De même, vous pouvez importer toutes les données d'une exportation ou uniquement des collections spécifiques. Les données exportées depuis une base de données Cloud Firestore peuvent être importées dans une autre base de données Cloud Firestore. Vous pouvez également charger des exportations Cloud Firestore dans BigQuery .

Cette page décrit comment exporter et importer des documents Cloud Firestore à l'aide du service d'exportation et d'importation géré et de Cloud Storage . Le service d'exportation et d'importation géré Cloud Firestore est disponible via l'outil de ligne de commande gcloud et l'API Cloud Firestore ( REST , RPC ).

Avant que tu commences

Avant de pouvoir utiliser le service d'exportation et d'importation géré, vous devez effectuer les tâches suivantes :

1. Activez la facturation pour votre projet Google Cloud. Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser la fonctionnalité d'exportation et d'importation.
2. Créez un bucket Cloud Storage pour votre projet dans un emplacement proche de l'emplacement de votre base de données Cloud Firestore . Vous ne pouvez pas utiliser un compartiment Demandeur paie pour les opérations d'exportation et d'importation.

3. Assurez-vous que votre compte dispose des autorisations nécessaires pour Cloud Firestore et Cloud Storage. Si vous êtes le propriétaire du projet, votre compte dispose des autorisations requises. Sinon, les rôles suivants accordent les autorisations nécessaires pour les opérations d'exportation et d'importation et pour l'accès à Cloud Storage :

   • Rôles Cloud Firestore : Owner , Cloud Datastore Owner ou Cloud Datastore Import Export Admin

   • Rôles Cloud Storage : Owner ou Storage Admin

Autorisations de compte de service par défaut

Chaque projet Google Cloud crée automatiquement un compte de service par défaut nommé PROJECT_ID @appspot.gserviceaccount.com . Les opérations d'exportation et d'importation utilisent ce compte de service pour autoriser les opérations Cloud Storage.

Le compte de service par défaut de votre projet nécessite l'accès au bucket Cloud Storage utilisé dans une opération d'exportation ou d'importation. Si votre bucket Cloud Storage se trouve dans le même projet que votre base de données Cloud Firestore, le compte de service par défaut a accès au bucket par défaut .

Si le bucket Cloud Storage se trouve dans un autre projet, vous devez accorder au compte de service par défaut l'accès au bucket Cloud Storage.

Le compte de service a besoin du rôle Storage Admin pour que le bucket Cloud Storage soit utilisé pour l'opération d'exportation ou d'importation.

Si vous désactivez ou supprimez votre compte de service par défaut App Engine, votre application App Engine perdra l'accès à votre base de données Cloud Firestore. Si vous avez désactivé votre compte de service App Engine, vous pouvez le réactiver. Consultez l' article Activation d'un compte de service . Si vous avez supprimé votre compte de service App Engine au cours des 30 derniers jours, vous pouvez restaurer votre compte de service, voir annuler la suppression d'un compte de service .

Configurer gcloud pour votre projet

Vous pouvez lancer des opérations d'importation et d'exportation via la console Google Cloud Platform ou l'outil de ligne de commande gcloud . Pour utiliser gcloud , configurez l'outil de ligne de commande et connectez-vous à votre projet de l'une des manières suivantes :

• Accédez gcloud depuis la console Google Cloud Platform à l'aide de Cloud Shell .

  Démarrer Cloud Shell

  Assurez-vous que gcloud est configuré pour le bon projet :

  gcloud config set project [PROJECT_ID]
  

• Installez et initialisez le SDK Google Cloud.

Exporter des données

Une opération d'exportation copie les documents de votre base de données vers un ensemble de fichiers dans un bucket Cloud Storage. Notez qu'une exportation n'est pas un instantané de base de données exact pris à l'heure de début de l'exportation. Une exportation peut inclure des modifications apportées pendant l'exécution de l'opération.

Exporter tous les documents

gcloud firestore export gs://[BUCKET_NAME]

Exporter des collections spécifiques

gcloud firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1]

Importer des données

Une fois que vous avez exporté des fichiers dans Cloud Storage, vous pouvez réimporter des documents dans ces fichiers dans votre projet ou dans un autre projet. Notez les points suivants concernant les opérations d'importation :

• Lorsque vous importez des données, les index requis sont mis à jour à l'aide des définitions d'index actuelles de votre base de données. Une exportation ne contient pas de définitions d'index.

• Les importations n'attribuent pas de nouveaux ID de document. Les importations utilisent les ID capturés au moment de l'exportation. Lorsqu'un document est importé, son ID est réservé pour éviter les collisions d'ID. Si un document avec le même ID existe déjà, l'importation écrase le document existant.

• Si un document de votre base de données n'est pas affecté par une importation, il restera dans votre base de données après l'importation.

• Les opérations d'importation ne déclenchent pas Cloud Functions. Les écouteurs d'instantané reçoivent des mises à jour liées aux opérations d'importation.

• Le nom du fichier .overall_export_metadata doit correspondre au nom de son dossier parent :

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/ PARENT_FOLDER_NAME / PARENT_FOLDER_NAME .overall_export_metadata

  Si vous déplacez ou copiez les fichiers de sortie d'une exportation, conservez le même nom de fichier PARENT_FOLDER_NAME et .overall_export_metadata .

Importer tous les documents d'une exportation

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

gcloud firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

Importer des collections spécifiques

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2],[SUBCOLLECTION_ID_1]

Gestion des opérations d'exportation et d'importation

Après avoir démarré une opération d'exportation ou d'importation, Cloud Firestore attribue à l'opération un nom unique. Vous pouvez utiliser le nom de l'opération pour supprimer, annuler ou vérifier l'état de l'opération.

Les noms d'opération sont précédés de projects/[PROJECT_ID]/databases/(default)/operations/ , par exemple :

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Cependant, vous pouvez omettre le préfixe lorsque vous spécifiez un nom d'opération pour les describe , cancel et delete .

Lister toutes les opérations d'exportation et d'importation

gcloud firestore operations list

Vérifier l'état de fonctionnement

gcloud firestore operations describe [OPERATION_NAME]

Estimer le temps de réalisation

Une demande de statut d'une opération de longue durée renvoie les métriques workEstimated et workCompleted . Chacune de ces métriques est renvoyée en nombre d'octets et en nombre d'entités :

• workEstimated affiche le nombre total estimé d'octets et de documents qu'une opération traitera. Cloud Firestore peut omettre cette métrique s'il ne peut pas faire d'estimation.

• workCompleted affiche le nombre d'octets et de documents traités jusqu'à présent. Une fois l'opération terminée, la valeur indique le nombre total d'octets et de documents réellement traités, qui peut être supérieur à la valeur de workEstimated .

Diviser workCompleted par workEstimated pour une estimation approximative de l'avancement. Cette estimation peut être inexacte, car elle dépend de la collecte tardive des statistiques.

Annuler une opération

gcloud firestore operations cancel [OPERATION_NAME]

L'annulation d'une opération en cours n'annule pas l'opération. Une opération d'exportation annulée laissera les documents déjà exportés dans Cloud Storage, et une opération d'importation annulée laissera en place les mises à jour déjà apportées à votre base de données. Vous ne pouvez pas importer une exportation partiellement terminée.

Supprimer une opération

Utilisez la commande gcloud firestore operations delete pour supprimer une opération de la liste des opérations récentes. Cette commande ne supprimera pas les fichiers d'exportation de Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Facturation et tarification des opérations d'exportation et d'importation

Vous devez activer la facturation pour votre projet Google Cloud avant d'utiliser le service d'exportation et d'importation géré. Les opérations d'exportation et d'importation sont facturées pour les lectures et écritures de documents aux tarifs indiqués dans la tarification Cloud Firestore .

Les coûts des opérations d'exportation et d'importation ne sont pas pris en compte dans votre plafond de dépenses . Les opérations d'exportation ou d'importation ne déclencheront vos alertes de budget Google Cloud qu'une fois terminées. De même, les lectures et écritures effectuées lors d'une opération d'exportation ou d'importation sont appliquées à votre quota quotidien une fois l'opération terminée. Les opérations d'exportation et d'importation n'affecteront pas l'utilisation indiquée dans la section d'utilisation de la console.

Affichage des coûts d'exportation et d'importation

Les opérations d'exportation et d'importation appliquent le libellé goog-firestoremanaged:exportimport aux opérations facturées. Sur la page des rapports Cloud Billing , vous pouvez utiliser ce libellé pour afficher les coûts liés aux opérations d'importation et d'exportation :

Exporter vers BigQuery

Vous pouvez charger des données à partir d'une exportation Cloud Firestore dans BigQuery, mais uniquement si vous avez spécifié un filtre collection-ids . Consultez Charger des données à partir d'exportations Cloud Firestore .

Limite de colonne BigQuery

BigQuery impose une limite de 10 000 colonnes par table. Les opérations d'exportation Cloud Firestore génèrent un schéma de table BigQuery pour chaque groupe de collections. Dans ce schéma, chaque nom de champ unique au sein d'un groupe de collections devient une colonne de schéma.

Si le schéma BigQuery d'un groupe de collections dépasse 10 000 colonnes, l'opération d'exportation Cloud Firestore tente de rester sous la limite de colonnes en traitant les champs de la carte comme des octets. Si cette conversion amène le nombre de colonnes en dessous de 10 000, vous pouvez charger les données dans BigQuery, mais vous ne pouvez pas interroger les sous-champs dans les champs de la carte. Si le nombre de colonnes dépasse toujours 10 000, l'opération d'exportation ne génère pas de schéma BigQuery pour le groupe de collecte et vous ne pouvez pas charger ses données dans BigQuery.

Format d'exportation et fichiers de métadonnées

La sortie d'une exportation gérée utilise le format de journal LevelDB .

Fichiers de métadonnées

Une opération d'exportation crée un fichier de métadonnées pour chaque groupe de collections que vous spécifiez. Les fichiers de métadonnées sont généralement nommés ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata .

Les fichiers de métadonnées sont des tampons de protocole et vous pouvez les décoder avec le compilateur de protocole protoc . Par exemple, vous pouvez décoder un fichier de métadonnées pour déterminer les groupes de collections que contiennent les fichiers d'exportation :

protoc --decode_raw < export0.export_metadata

Migration des agents de service

Vous pouvez désormais utiliser un agent de service Cloud Firestore pour autoriser les opérations d'importation et d'exportation au lieu du compte de service App Engine. L'agent de service et le compte de service utilisent les conventions de dénomination suivantes :

Agent de service Cloud Firestore

service- project_number @gcp-sa-firestore.iam.gserviceaccount.com

Compte de service App Engine

project_id @appspot.gserviceaccount.com

L'agent de service Cloud Firestore est préférable car il est spécifique à Cloud Firestore. Le compte de service App Engine est partagé par plusieurs services.

Afficher le compte d'autorisation

Vous pouvez voir quel compte vos opérations d'importation et d'exportation utilisent pour autoriser les requêtes à partir de la page Importer/Exporter de la console Google Cloud Platform. Vous pouvez également voir si votre base de données utilise déjà l'agent de service Cloud Firestore.

1. Accédez à la page d'importation/exportation Cloud Firestore dans la console Google Cloud Platform.

   Allez dans Importer/Exporter

2. Affichez le compte d'autorisation à côté de l'étiquette Import/Export jobs run as .

Si votre projet n'utilise pas l'agent de service Cloud Firestore, vous pouvez migrer vers l'agent de service Cloud Firestore à l'aide de l'une de ces techniques :

• Migrez un projet en vérifiant et en mettant à jour les autorisations du bucket Cloud Storage (recommandé) .
• Ajoutez une contrainte de stratégie à l'échelle de l'organisation qui affecte tous les projets au sein de l'organisation.

La première de ces techniques est préférable car elle localise la portée de l'effet sur un seul projet Cloud Firestore. La deuxième technique n'est pas recommandée, car elle ne migre pas les autorisations de bucket Cloud Storage existantes. Cependant, il offre une conformité de sécurité au niveau de l'organisation.

Migrer en vérifiant et en mettant à jour les autorisations du bucket Cloud Storage

Le processus de migration comporte deux étapes :

1. Mettez à jour les autorisations du bucket Cloud Storage. Voir la section suivante pour plus de détails.
2. Confirmez la migration vers l'agent de service Cloud Firestore.

Autorisations de compartiment d'agent de service

Pour toute opération d'exportation ou d'importation qui utilise un bucket Cloud Storage dans un autre projet, vous devez accorder à l'agent de service Cloud Firestore des autorisations pour ce bucket. Par exemple, les opérations qui déplacent des données vers un autre projet doivent accéder à un bucket dans cet autre projet. Sinon, ces opérations échouent après la migration vers l'agent de service Cloud Firestore.

Les workflows d'importation et d'exportation qui restent dans le même projet ne nécessitent pas de modification des autorisations. L'agent de service Cloud Firestore peut accéder aux buckets du même projet par défaut.

Mettez à jour les autorisations pour les buckets Cloud Storage d'autres projets afin d'accorder l'accès à l'agent de service service- project_number @gcp-sa-firestore.iam.gserviceaccount.com . Attribuez à l'agent de service le rôle Firestore Service Agent .

Le rôle Firestore Service Agent accorde des autorisations de lecture et d'écriture pour un bucket Cloud Storage. Si vous devez accorder uniquement des autorisations en lecture ou en écriture uniquement, utilisez un rôle personnalisé .

Le processus de migration décrit dans la section suivante vous aide à identifier les buckets Cloud Storage susceptibles de nécessiter des mises à jour des autorisations.

Migrer un projet vers l'agent de service Firestore

Effectuez les étapes suivantes pour migrer du compte de service App Engine vers l'agent de service Cloud Firestore. Une fois terminée, la migration ne peut pas être annulée.

1. Accédez à la page d'importation/exportation Cloud Firestore dans la console Google Cloud Platform.

   Allez dans Importer/Exporter

2. Si votre projet n'a pas encore migré vers l'agent de service Cloud Firestore, une bannière décrivant la migration et un bouton Vérifier l'état du bucket s'affichent. L'étape suivante vous aide à identifier et à corriger les erreurs d'autorisation potentielles.

   Cliquez sur Vérifier l'état du compartiment .

   Un menu s'affiche avec l'option de terminer votre migration et une liste de buckets Cloud Storage. Le chargement de la liste peut prendre quelques minutes.

   Cette liste inclut les buckets qui ont été récemment utilisés dans les opérations d'importation et d'exportation, mais qui n'accordent actuellement pas d'autorisations de lecture et d'écriture à l'agent de service Cloud Firestore.

3. Notez le nom principal de l'agent de service Cloud Firestore de votre projet. Le nom de l'agent de service apparaît sous l' agent de service pour donner accès à l'étiquette.

4. Pour tout bucket de la liste que vous utiliserez pour les futures opérations d'importation ou d'exportation, procédez comme suit :

   1. Dans la ligne du tableau de ce bucket, cliquez sur Corriger . Cela ouvre la page des autorisations de ce compartiment dans un nouvel onglet.

   2. Cliquez sur Ajouter .
   3. Dans le champ Nouveaux mandataires , saisissez le nom de votre agent de service Cloud Firestore.
   4. Dans le champ Sélectionner un rôle , sélectionnez Agents de service > Agent de service Firestore .
   5. Cliquez sur Enregistrer .
   6. Revenez à l'onglet avec la page Cloud Firestore Import/Export.
   7. Répétez ces étapes pour les autres buckets de la liste. Assurez-vous de visualiser toutes les pages de la liste.

5. Cliquez sur Migrer vers Firestore Service Agent . Si vous avez encore des compartiments dont les vérifications d'autorisation ont échoué, vous devez confirmer votre migration en cliquant sur Migrer .

   Une alerte vous informe lorsque votre migration est terminée. La migration ne peut pas être annulée.

Afficher l'état de la migration

1. Pour vérifier l'état de migration de votre projet, accédez à la page Importer/Exporter de la console Google Cloud Platform :

   Allez dans Importer/Exporter

2. Recherchez le principal à côté de l'étiquette Import/Export jobs run as .

   Si le principal est service- project_number @gcp-sa-firestore.iam.gserviceaccount.com , votre projet a déjà migré vers l'agent de service Cloud Firestore. La migration ne peut pas être annulée.

   Si le projet n'a pas été migré, une bannière apparaît en haut de la page avec un bouton Vérifier l'état du bucket . Consultez Migrer vers l'agent de service Firestore pour terminer la migration.

Ajouter une contrainte de stratégie à l'échelle de l'organisation

• Définissez la contrainte suivante dans la stratégie de votre organisation :

  Exiger l'agent de service Firestore pour l'importation/exportation ( firestore.requireP4SAforImportExport ).

  Cette contrainte nécessite des opérations d'importation et d'exportation pour utiliser l'agent de service Cloud Firestore afin d'autoriser les requêtes. Pour définir cette contrainte, voir Création et gestion des règles d'administration .

L'application de cette contrainte de stratégie organisationnelle n'accorde pas automatiquement les autorisations de bucket Cloud Storage appropriées pour l'agent de service Cloud Firestore.

Si la contrainte crée des erreurs d'autorisation pour des workflows d'importation ou d'exportation, vous pouvez la désactiver pour revenir à l'utilisation du compte de service par défaut. Après avoir vérifié et mis à jour les autorisations du bucket Cloud Storage , vous pouvez réactiver la contrainte.