Cette page a été traduite par l'API Cloud Translation.
Switch to English

Exporter et importer des données

Vous pouvez utiliser le service d'exportation et d'importation géré par Firestore 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 peuvent être importées dans une autre base de données Firestore. Vous pouvez également charger des exportations Firestore dans BigQuery.

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

Avant de commencer

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

  1. Activer 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. 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 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 : Owner, Cloud Datastore Owner ou Cloud Datastore Import Export Admin
    • Rôles Cloud Storage : Owner ou Storage Admin

Autorisations du 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 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, le compte de service par défaut y a accès par défaut.

Si le bucket Cloud Storage se trouve dans un autre projet, vous devez autoriser le compte de service par défaut à accéder 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 App Engine par défaut, votre application App Engine perdra l'accès à votre base de données Firestore. Si vous avez désactivé votre compte de service App Engine, vous pouvez le réactiver, comme décrit dans la section Activer un compte de service. Si vous avez supprimé votre compte de service App Engine au cours des 30 derniers jours, vous pouvez le restaurer, comme décrit dans la section 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 Google Cloud Console 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 :

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

Exporter tous les documents

Google Cloud Console

  1. Accédez à la page Importations/Exportations Firestore de Google Cloud Console.

    Accéder à la page "Importations/Exportations"

  2. Cliquez sur Exporter.

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

  4. Sous Sélectionner une destination, saisissez le nom d'un bucket Cloud Storage ou utilisez le bouton Parcourir pour sélectionner un bucket.

  5. 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]

Vous pouvez organiser 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.

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

Google Cloud Console

  1. Accédez à la page Importations/Exportations Firestore de Google Cloud Console.

    Accéder à la page "Importations/Exportations"

  2. Cliquez sur Exporter.

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

  4. Sous Sélectionner une destination, saisissez le nom d'un bucket Cloud Storage ou utilisez le bouton Parcourir pour sélectionner un bucket.

  5. 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 groupes de collections spécifiques, utilisez l'indicateur --collection-ids. L'opération n'exporte que les groupes de collections avec les ID de collection saisis. Le groupe de collections inclut toutes les collections et sous-collections (à n'importe quel chemin d'accès) avec cet ID de collection spécifique.

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

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.

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

Importer tous les documents d'une exportation

Google Cloud Console

  1. Accédez à la page Importations/Exportations Firestore de Google Cloud Console.

    Accéder à la page "Importations/Exportations"

  2. Cliquez sur Importer.

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

  4. 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]/

[BUCKET_NAME] et [EXPORT_PREFIX] pointent vers l'emplacement de vos fichiers d'exportation. Exemple :

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

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

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

Google Cloud Console

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

gcloud

Pour importer des groupes de collections spécifiques à partir d'un ensemble de fichiers d'exportation, utilisez l'indicateur --collection-ids. L'opération n'importe que les groupes de collections avec les ID de collection saisis. Le groupe de collections inclut toutes les collections et sous-collections (à n'importe quel chemin d'accès) avec cet ID de collection spécifique.

Seule l'exportation de groupes de collections spécifiques permet l'importation de groupes 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]

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

Une fois que vous avez lancé une opération d'exportation ou d'importation, Firestore 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/(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.

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

Google Cloud Console

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

Accéder à la page "Importations/Exportations"

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

Google Cloud Console

Vous pouvez afficher l'état d'une opération d'exportation ou d'importation récente depuis la page Importations/Exportations Firestore de Google Cloud Console.

Accéder à la page "Importations/Exportations"

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.

  • 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

Google Cloud Console

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

Accéder à la page "Importations/Exportations"

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 lectures et écritures de documents aux tarifs indiqués dans la section Tarifs de Firestore.

Les frais liés aux opérations d'exportation et d'importation ne sont pas comptabilisés dans votre plafond budgétaire. 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. De même, les opérations de lecture et d'écriture 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'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 :

Accéder au libellé "goog-firestoremanaged" depuis le menu des filtres

Journaux d'audit

Firestore écrit des journaux d'audit pour les activités d'administration dans les journaux d'audit Cloud. Les journaux d'audit pour les activités d'administration incluent les opérations d'exportation, d'importation et d'indexation. Pour afficher les journaux d'audit pour les activités d'administration de votre base de données Firestore, consultez la section Afficher les journaux d'audit.

Les journaux d'audit pour les activités d'administration Firestore apparaissent sous les types de ressources Cloud Datastore Database et Cloud Datastore Index. Bien que les types de ressources utilisent le nom Cloud Datastore, les entrées de journal individuelles contiennent un identifiant Firestore. Firestore consigne les opérations suivantes :

Catégorie de journal d'audit Opérations Firestore
Activité d'administration FirestoreAdmin.CreateIndex
FirestoreAdmin.DeleteIndex
FirestoreAdmin.ExportDocuments
FirestoreAdmin.GetField
FirestoreAdmin.GetIndex
FirestoreAdmin.ImportDocuments
FirestoreAdmin.ListFields
FirestoreAdmin.ListIndexes
FirestoreAdmin.UpdateField

Exporter vers BigQuery

Vous pouvez charger les données d'une exportation Firestore 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.

Limite des colonnes BigQuery

BigQuery impose une limite de 10 000 colonnes par table. Les opérations d'exportation 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 du schéma.

Si le schéma BigQuery d'un groupe de collections dépasse 10 000 colonnes, l'opération d'exportation Firestore 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 le groupe de collections et vous ne pouvez pas charger ses données dans BigQuery.