Exporter et importer des données

Vous pouvez utiliser le service d'exportation et d'importation géré par Cloud Firestore pour récupérer après une suppression accidentelle de données et exporter des données pour un traitement hors ligne. Vous pouvez exporter tous les documents ou uniquement des collections spécifiques. De même, vous pouvez importer toutes les données d'un export 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é par 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 bucket Requester Pay 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 des agents de service

Les opérations d'exportation et d'importation utilisent un agent de service Cloud Firestore pour autoriser les opérations Cloud Storage. L'agent de service Cloud Firestore utilise la convention de dénomination suivante :

Agent de service Cloud Firestore

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

Pour en savoir plus sur les agents de service, consultez Agents de service .

L'agent de service Cloud Firestore nécessite un 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, l'agent de service Cloud Firestore peut accéder au bucket par défaut .

Si le bucket Cloud Storage se trouve dans un autre projet, vous devez accorder à l'agent de service Cloud Firestore l'accès au bucket Cloud Storage.

Attribuer des rôles à l'agent de service

Vous pouvez utiliser l'outil de ligne de commande gsutil pour attribuer l'un des rôles ci-dessous. Par exemple, pour attribuer le rôle d'administrateur de stockage à l'agent de service Cloud Firestore, exécutez la commande suivante :

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Remplacez PROJECT_NUMBER par votre numéro de projet, qui est utilisé pour nommer votre agent de service Cloud Firestore. Pour afficher le nom de l'agent de service, voir Afficher le nom de l'agent de service .

Vous pouvez également attribuer ce rôle à l'aide de la console GCP .

Afficher le nom de l'agent de service

Vous pouvez afficher le compte que vos opérations d'importation et d'exportation utilisent pour autoriser les demandes à partir de la page Import/Export de la console Google Cloud Platform. Vous pouvez également voir si votre base de données utilise l'agent de service Cloud Firestore ou l'ancien compte de service App Engine.

1. Affichez le compte d'autorisation à côté des tâches d'importation/exportation exécutées en tant qu'étiquette.

L'agent 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.

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é exact de la base de données pris au moment du début de l'exportation. Une exportation peut inclure les modifications apportées pendant l'exécution de l'opération.

Exporter tous les documents

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Exporter des collections spécifiques

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

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Importer des données

Une fois que vous avez exporté des fichiers dans Cloud Storage, vous pouvez réimporter les documents contenus 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 identifiants capturés au moment de l'exportation. Lors de l'importation d'un document, son ID est réservé pour éviter les collisions d'ID. Si un document portant 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 concerné 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és 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'un export

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Importer des collections spécifiques

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

Gestion des opérations d'export et d'import

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érations sont préfixés par 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 commandes 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 à la fois en nombre d'octets et en nombre d'entités :

• workEstimated indique 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 affiche le nombre total d'octets et de documents réellement traités, qui peut être supérieur à la valeur de workEstimated .

Divisez workCompleted par workEstimated pour une estimation approximative des progrès. Cette estimation pourrait être inexacte, car elle dépend d’un retard dans la collecte 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’export et d’import

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 opérations d'exportation impliquent une opération de lecture par document exporté. Les opérations d'importation nécessitent une opération d'écriture par document importé.

Les fichiers de sortie stockés dans Cloud Storage sont pris en compte dans vos coûts de stockage de données Cloud Storage .

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 budgétaires 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 affichée dans la section 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 d'une exportation Cloud Firestore dans BigQuery, mais uniquement si vous avez spécifié un filtre collection-ids . Consultez Chargement de données à partir d'exportations Cloud Firestore .

Limite de colonnes 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 collecte dépasse 10 000 colonnes, l'opération d'exportation Cloud Firestore tente de rester en dessous de la limite de colonnes en traitant les champs de carte comme des octets. Si cette conversion ramè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 des 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.

Exporter les fichiers de format et 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 collecte 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

Cloud Firestore utilise un agent de service Cloud Firestore pour autoriser les opérations d'importation et d'exportation au lieu d'utiliser le 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

Cloud Firestore utilisait auparavant le compte de service par défaut App Engine au lieu de l'agent de service Cloud Firestore. Si votre base de données utilise toujours le compte de service App Engine pour importer ou exporter des données, nous vous recommandons de suivre les instructions de cette section pour migrer vers l'utilisation de l'agent de service Cloud Firestore.

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 demandes à partir de la page Import/Export 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. Dans la console Google Cloud Platform, accédez à la page Bases de données .

   Aller aux bases de données

2. Sélectionnez la base de données requise dans la liste des bases de données.

3. Dans le menu de navigation, cliquez sur Importer/Exporter .

4. Affichez le compte d'autorisation à côté des tâches d'importation/exportation exécutées en tant qu'étiquette.

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 existantes du bucket Cloud Storage. Il offre cependant une conformité en matière de sécurité au niveau de l’organisation.

Migrez 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 du compartiment de l'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 les autorisations pour ce bucket. Par exemple, les opérations qui déplacent des données vers un autre projet doivent accéder à un compartiment de 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 par défaut aux buckets du même projet.

Mettez à jour les autorisations pour les buckets Cloud Storage d'autres projets pour donner accès à l'agent de service service- PROJECT_NUMBER @gcp-sa-firestore.iam.gserviceaccount.com . Accordez à 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 de lecture ou d'écriture, 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 Firestore Service Agent

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 plus être annulée.

1. Dans la console Google Cloud Platform, accédez à la page Bases de données .

   Aller aux bases de données

2. Sélectionnez la base de données requise dans la liste des bases de données.

3. Dans le menu de navigation, cliquez sur Importer/Exporter .

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

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

   Un menu apparaît avec l'option permettant de terminer votre migration et une liste des buckets Cloud Storage. Le chargement de la liste peut prendre quelques minutes.

   Cette liste comprend les compartiments 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.

5. Prenez note du 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.

6. Pour tout compartiment de la liste que vous utiliserez pour de 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 principaux , saisissez le nom de votre agent de service Cloud Firestore.
   4. Dans le champ Sélectionner un rôle , sélectionnez Agents de service > Firestore Service Agent .
   5. Cliquez sur Enregistrer .
   6. Revenez à l'onglet avec la page d'importation/exportation Cloud Firestore.
   7. Répétez ces étapes pour les autres compartiments de la liste. Assurez-vous de consulter toutes les pages de la liste.

7. Cliquez sur Migrer vers Firestore Service Agent . Si vous disposez toujours de 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 le statut de migration

Pour vérifier le statut de migration de votre projet :

1. Dans la console Google Cloud Platform, accédez à la page Bases de données .

   Aller aux bases de données

2. Sélectionnez la base de données requise dans la liste des bases de données.

3. Dans le menu de navigation, cliquez sur Importer/Exporter .

4. Recherchez le principal à côté des tâches d'importation/exportation exécutées en tant qu'étiquette.

   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 compartiment . 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 que les opérations d'importation et d'exportation utilisent l'agent de service Cloud Firestore pour autoriser les requêtes. Pour définir cette contrainte, consultez Création et gestion des stratégies d'organisation .

L'application de cette contrainte de stratégie d'organisation 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 les 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.