Importer et exporter des données

Importer et exporter des données

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

Cette page explique comment exporter et importer des documents Firestore avec compatibilité MongoDB à 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 Firestore compatible avec MongoDB est disponible via l'outil de ligne de commande gcloud et l'API Firestore compatible avec MongoDB (REST, RPC).

Attention : L'exportation de données depuis Firestore compatible avec MongoDB entraîne une opération de lecture par document exporté. Toutefois, ces opérations ne s'affichent pas dans la section "Utilisation" de la console. Assurez-vous de bien comprendre ce processus avant de configurer des exportations récurrentes afin d'éviter des frais inattendus.

Avant de commencer

Pour pouvoir utiliser le service d'exportation et d'importation géré, vous devez effectuer les tâches ci-dessous :

1. Activez la facturation pour votre projet Google Cloud . Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser les fonctionnalités d'exportation et d'importation.
2. Créez un bucket Cloud Storage pour votre projet à proximité de l'emplacement de votre base de données Firestore avec compatibilité MongoDB. Vous ne pouvez pas utiliser de bucket "Paiements du demandeur" pour les opérations d'exportation et d'importation.

3. Assurez-vous que votre compte dispose des autorisations nécessaires pour Firestore avec la compatibilité MongoDB 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, ainsi que pour l'accès à Cloud Storage :

   • Rôles Firestore compatible avec MongoDB : Owner, Cloud Datastore Owner ou Cloud Datastore Import Export Admin
     Remarque : Ces rôles Datastore accordent également des autorisations dans Firestore compatible avec MongoDB.

   • Rôles Cloud Storage : Owner ou Storage Admin

Autorisations de l'agent de service

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

Agent de service Firestore

[e-mail]

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

Remarque : Auparavant, Firestore utilisait le compte de service App Engine par défaut au lieu de l'agent de service 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 migrer vers l'agent de service Firestore spécifique au service. Vous pouvez voir le compte utilisé par vos opérations d'importation et d'exportation dans la console Google Cloud .

Si vous utilisez VPC Service Controls, vous devez utiliser l'agent de service Firestore spécifique au service pour protéger entièrement les opérations d'importation et d'exportation. VPC Service Controls n'est pas compatible avec le compte de service App Engine.

L'agent de service 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 Firestore, l'agent de service Firestore peut y accéder par défaut.

Si le bucket Cloud Storage se trouve dans un autre projet, vous devez autoriser l'agent de service Firestore à y accéder.

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 "Administrateur de l'espace de stockage" à l'agent de service Firestore, exécutez la commande suivante :

gsutil iam ch serviceAccount:[e-mail]:roles/storage.admin \
    gs://[BUCKET_NAME]

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

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

Afficher le nom de l'agent de service

Vous pouvez afficher le compte utilisé par vos opérations d'importation et d'exportation pour autoriser les requêtes depuis la page Importations/Exportations de la console Google Cloud . Vous pouvez également vérifier si votre base de données utilise l'agent de service Firestore ou l'ancien compte de service App Engine.

1. Consultez le compte d'autorisation à côté du libellé Les tâches d'importation/exportation s'exécutent avec le compte.

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

Importer des données

Une fois que vous avez exporté des fichiers dans Cloud Storage, vous pouvez les réimporter 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. Lors de l'importation d'un document, son ID est réservé pour éviter les conflits 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 affecté par une importation, il restera dans votre base de données une fois l'importation terminée.

• Le nom de 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 les mêmes noms de fichiers pour PARENT_FOLDER_NAME et .overall_export_metadata.

• L'importation dans une base de données Firestore compatible avec MongoDB à partir d'une exportation avec des sous-collections échoue, car les sous-collections ne sont pas prises en charge dans Firestore compatible avec MongoDB.

• L'importation dans une base de données Firestore édition Standard à partir d'une exportation avec des types BSON échoue, car les types BSON ne sont pas compatibles avec Firestore édition Standard.

• Une importation dans une base de données Firestore compatible avec MongoDB ne peut pas importer de données provenant d'espaces de noms non par défaut (API Datastore).

  L'importation dans une base de données Firestore avec compatibilité MongoDB à partir de fichiers de données contenant des espaces de noms non définis par défaut n'est autorisée que si l'opération d'exportation incluait un filtre --namespace-ids avec l'espace de noms par défaut. Seules les données de l'espace de noms par défaut sont importées.

Importer tous les documents d'une exportation

Console Google Cloud

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

   Accéder à la page "Bases de données"

2. Sélectionnez une base de données dans la liste.

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

4. Cliquez sur Importer.

5. Dans le champ Nom de fichier, saisissez le nom du fichier .overall_export_metadata à partir d'une opération d'exportation terminée. Vous pouvez vous servir du bouton Parcourir pour vous aider à sélectionner le fichier.

6. Cliquez sur Importer.

La console revient à la page Importations/Exportations. Si l'opération démarre correctement, la page ajoute une entrée à la page des importations et exportations récentes. En cas d'échec, la page affiche un message d'erreur.

gcloud

Utilisez la commande firestore import pour importer des documents d'une exportation précédente.

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

Remplacez les éléments suivants :

• BUCKET_NAME/EXPORT_PREFIX : emplacement de vos fichiers d'exportation.

• DATABASE : nom de la base de données.

Exemple :

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

Vous pouvez vérifier l'emplacement de vos fichiers d'exportation dans le navigateur Cloud Storage de la console Google Cloud  :

Ouvrir le navigateur Cloud Storage

Lorsque vous lancez une importation, la fermeture du terminal n'annule pas l'opération. Pour en savoir plus, consultez la section Annuler une opération.

Importer des collections spécifiques

Remarque : Pour importer des collections spécifiques, vous devez utiliser le résultat d'une opération d'exportation au cours de laquelle vous avez exporté des collections spécifiques.

Google Cloud Console

Vous ne pouvez pas sélectionner de collections spécifiques dans la console. Utilisez plutôt gcloud.

gcloud

Pour importer des collections spécifiques à partir d'un ensemble de fichiers d'exportation, utilisez l'indicateur --collection-ids. L'opération n'importe que les collections avec les ID de collection saisis. Spécifiez le nom de la base de données à l'aide de l'option --database.

Seule l'exportation de collections spécifiques permet l'importation de collections spécifiques. Vous ne pouvez pas importer des collections spécifiques à partir d'une exportation de tous les documents.

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

Importer à partir d'une exportation avec des données PITR

Suivez les mêmes étapes que dans Importer tous les documents ou Importer des collections spécifiques pour importer les données PITR. Si des documents existent déjà dans votre base de données, ils seront écrasés.

Exporter les 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 effectuées pendant l'exécution de l'opération.

Remarque : Vous devez exporter des collections spécifiques si vous prévoyez les opérations suivantes :

• Importer seulement des collections spécifiques
• Charger des données Firestore compatible avec MongoDB dans BigQuery

Exporter tous les documents

Console Google Cloud

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

   Accéder à la page "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. Cliquez sur Exporter.

5. Cliquez sur l'option Exporter la base de données complète.

6. Sélectionnez Exporter l'état actuel de la base de données pour exporter les données actuelles.

7. Dans la section Destination, saisissez le nom d'un bucket Cloud Storage ou utilisez le bouton Parcourir pour sélectionner un bucket.

8. Cliquez sur Exporter.

La console revient à la page Importations/Exportations. Si l'opération démarre correctement, la page ajoute une entrée à la page des importations et exportations récentes. En cas d'échec, la page affiche un message d'erreur.

gcloud

Utilisez la commande firestore export pour exporter tous les documents de votre base de données, en remplaçant [BUCKET_NAME] par le nom de votre bucket Cloud Storage. Ajoutez l'indicateur --async pour empêcher l'outil gcloud d'attendre la fin de l'opération.

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

Remplacez les éléments suivants :

• BUCKET_NAME : organisez vos exportations en ajoutant un préfixe de fichier après le nom du bucket, par exemple, BUCKET_NAME/my-exports-folder/export-name. Si vous ne fournissez pas de préfixe de fichier, le service d'exportation géré en crée un en fonction de l'horodatage actuel.

• DATABASE : nom de la base de données à partir de laquelle vous souhaitez exporter les documents.

Lorsque vous lancez une exportation, la fermeture du terminal n'annule pas l'opération. Pour en savoir plus, consultez la section Annuler une opération.

Exporter des collections spécifiques

Console Google Cloud

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

   Accéder à la page "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. Cliquez sur Exporter.

5. Cliquez sur l'option Exporter un ou plusieurs groupes de collections. Dans le menu déroulant, sélectionnez une ou plusieurs collections.

6. Sélectionnez Exporter l'état actuel de la base de données pour exporter les données actuelles.

7. Dans la section Destination, saisissez le nom d'un bucket Cloud Storage ou utilisez le bouton Parcourir pour sélectionner un bucket.

8. Cliquez sur Exporter.

La console revient à la page Importations/Exportations. Si l'opération démarre correctement, la page ajoute une entrée à la page des importations et exportations récentes. En cas d'échec, la page affiche un message d'erreur.

gcloud

Pour exporter des collections spécifiques, utilisez l'indicateur --collection-ids. L'opération n'exporte que les collections avec les ID de collection saisis.

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

Par exemple, vous pouvez concevoir une collection restaurants dans la base de données foo pour inclure des collections supplémentaires, telles que ratings, reviews ou outlets. Pour exporter des restaurants et reviews de collection spécifiques, votre commande se présente comme suit :

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

Exporter à partir d'un code temporel PITR

Vous pouvez exporter votre base de données vers Cloud Storage à partir des données PITR. Vous pouvez exporter des données PITR dont le code temporel correspond à une minute entière au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données n'existent plus à l'horodatage spécifié, l'opération d'exportation échoue.

L'opération d'exportation PITR est compatible avec tous les filtres, y compris l'exportation de tous les documents et de collections spécifiques.

Avant d'exporter des données PITR, tenez compte des points suivants :

• Spécifiez l'horodatage au format RFC 3339. Exemple :2020-09-01T23:59:30.234233Z
• Assurez-vous que l'horodatage que vous spécifiez est un horodatage d'une minute entière au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données n'existent plus à l'horodatage spécifié, une erreur est générée.
• Les exportations PITR ayant échoué ne vous sont pas facturées.

Console

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

   Accéder à la page "Bases de données"
2. Sélectionnez une base de données dans la liste.
3. Dans le menu de navigation, cliquez sur Importer/Exporter.
4. Cliquez sur Exporter.
5. Configurez la source d'exportation pour exporter l'intégralité de la base de données ou uniquement des collections spécifiques.

6. Dans la section Choisissez l'état de la base de données à exporter, sélectionnez Exporter à partir d'un moment antérieur.

   Sélectionnez un instantané à utiliser pour l'exportation.

7. Dans la section Destination, saisissez le nom d'un bucket Cloud Storage ou utilisez le bouton Parcourir pour sélectionner un bucket.

8. Cliquez sur Exporter.

   La console revient à la page Importations/Exportations. Si l'opération démarre correctement, la page ajoute une entrée à la page des importations et exportations récentes. En cas d'échec, la page affiche un message d'erreur.

gcloud

Vous pouvez exporter votre base de données vers Cloud Storage à partir des données PITR à l'aide de la commande gcloud firestore export.

Exportez la base de données en spécifiant le paramètre snapshot-time vers un horodatage de récupération. Exécutez la commande suivante pour exporter la base de données vers votre bucket.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Où PITR_TIMESTAMP est un code temporel PITR avec une précision à la minute, par exemple 2023-05-26T10:20:00.00Z.

Ajoutez l'indicateur --collection-ids pour exporter des collections spécifiques.

Gérer les opérations d'exportation et d'importation

Une fois que vous avez lancé une opération d'exportation ou d'importation, Firestore compatible avec MongoDB attribue un nom unique à l'opération. Vous pouvez utiliser le nom de l'opération pour supprimer, annuler ou vérifier l'état de l'opération.

Les noms des opérations sont précédés du préfixe projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, par exemple :

projects/my-project/databases/my-database/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.

Répertorier toutes les opérations d'exportation et d'importation

Console Google Cloud

Vous pouvez afficher la liste des opérations d'exportation et d'importation récentes sur la page Importations/Exportations de la console Google Cloud .

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

   Accéder à la page "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.

gcloud

Utilisez la commande operations list pour afficher toutes les opérations d'exportation et d'importation en cours et terminées :

gcloud firestore operations list

Vérifier l'état de l'opération

Console Google Cloud

Vous pouvez consulter l'état d'une opération d'exportation ou d'importation récente sur la page Importations/Exportations de la console Google Cloud .

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

   Accéder à la page "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.

gcloud

Utilisez la commande operations describe pour afficher l'état d'une opération d'exportation ou d'importation.

gcloud firestore operations describe [OPERATION_NAME]

Estimer le délai d'exécution

Une requête permettant d'obtenir l'état 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 va traiter. Firestore compatible avec MongoDB peut omettre cette métrique s'il ne peut pas faire d'estimation.

• workCompleted indique 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.

Divisez workCompleted par workEstimated pour obtenir une estimation approximative de la progression. Cette estimation peut être inexacte, car elle dépend de la collecte de statistiques retardée.

Annuler une opération

Console Google Cloud

Vous pouvez annuler une opération d'exportation ou d'importation en cours d'exécution sur la page Importations/Exportations de la console Google Cloud .

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

   Accéder à la page "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.

Dans le tableau Recent imports and exports (Importations et exportations récentes), les opérations en cours d'exécution incluent un bouton Cancel (Annuler) dans la colonne Completed (Terminé). Cliquez sur le bouton Cancel (Annuler) pour arrêter l'opération. Le bouton affiche un message Annulation, puis passe à l'état Annulé lorsque l'opération s'arrête complètement.

gcloud

Utilisez la commande operations cancel pour arrêter une opération en cours :

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 laisse des documents déjà exportés dans Cloud Storage, et une opération d'importation annulée conserve les mises à jour déjà effectuées dans 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 supprime pas les fichiers d'exportation de Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

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

Vous devez activer la facturation pour votre projet Google Cloud pour pouvoir utiliser le service d'exportation et d'importation géré.

Les opérations d'exportation et d'importation sont facturées pour les unités de lecture et d'écriture aux tarifs indiqués dans la section Tarifs de Firestore compatible avec MongoDB.

Les fichiers de sortie stockés dans Cloud Storage sont comptabilisés dans les coûts de stockage des données de Cloud Storage.

Les opérations d'exportation ou d'importation ne déclencheront pas vos alertes budgétaires Google Cloud avant la fin de leur exécution. Les opérations d'exportation et d'importation n'ont aucune incidence sur l'utilisation affichée dans la section "Utilisation" de la console.

Afficher les 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 Rapports Cloud Billing, vous pouvez utiliser ce libellé pour afficher les coûts liés aux opérations d'importation et d'exportation :

Remarque : Les opérations d'exportation et d'importation exécutées avant le 8 septembre 2020 n'appliquent pas le libellé goog-firestoremanaged.

Exporter vers BigQuery

Vous pouvez charger les données d'une exportation Firestore avec compatibilité MongoDB vers BigQuery, mais uniquement si vous avez spécifié un filtre collection-ids. Pour en savoir plus, consultez la section Charger des données à partir d'exportations Firestore compatible avec MongoDB.

Lorsque vous chargez des données Firestore avec compatibilité MongoDB dans BigQuery, les types de données BSON sont représentés par le type de données STRING.

Limite des colonnes BigQuery

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

Si le schéma BigQuery d'une collection dépasse 10 000 colonnes, l'opération d'exportation Firestore avec compatibilité MongoDB tente de rester sous la limite des colonnes en traitant les champs de mappage comme des octets. Si avec cette conversion le nombre de colonnes est inférieur à 10 000, vous pouvez charger les données dans BigQuery, mais vous ne pouvez pas interroger les sous-champs dans les champs de mappage. 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 la collection et vous ne pouvez pas charger ses données dans BigQuery.

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

Le résultat 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 collection 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. Il est possible de les décoder avec le compilateur de protocole protoc. Par exemple, vous pouvez décoder un fichier de métadonnées afin de déterminer les collections que les fichiers d'exportation contiennent :

protoc --decode_raw < export0.export_metadata