Exporter et importer des données

Vous pouvez utiliser le service d'exportation et d'importation géré Cloud Firestore pour : récupérer des données en cas de suppression accidentelle et les exporter pour les utiliser hors connexion. en cours de traitement. 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. Données exportées à partir d'une base de données Cloud Firestore peuvent être importées dans une autre Cloud Firestore. Vous pouvez également charger Exportations Cloud Firestore vers BigQuery

Cette page explique 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 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 de votre projet Google Cloud. Google Cloud uniquement Les projets 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 Cloud 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 Cloud Firestore et Cloud Storage. Si vous êtes le propriétaire du projet, votre compte dispose des autorisations requises. Dans le cas contraire : accordent les autorisations nécessaires pour les opérations d'exportation et d'importation, pour accéder à 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 l'agent de service

Les opérations d'exportation et d'importation utilisent un agent de service Cloud Firestore pour : autoriser les opérations Cloud Storage. Agent de service Cloud Firestore utilise la convention d'attribution de noms 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 la page Agents de service.

L'agent de service Cloud Firestore a besoin d'accéder à Bucket Cloud Storage utilisé dans une opération d'exportation ou d'importation. Si votre Le bucket Cloud Storage se trouve dans le même projet que votre Cloud Firestore base de données, l'agent de service Cloud Firestore peut accéder bucket par défaut.

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

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 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 permet de nommer votre agent de service Cloud Firestore. Pour afficher les pour le nom de l'agent de service, consultez la section Afficher le nom de l'agent de service.

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

Afficher le nom de l'agent de service

Vous pouvez voir le compte que vos opérations d'importation et d'exportation utilisent pour autoriser 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 Cloud Firestore ou l'ancien compte de service App Engine.

1. Consultez le compte d'autorisation à côté Libellé Les jobs d'importation/exportation s'exécutent en tant que.

L'agent de service a besoin du rôle Storage Admin pour Cloud Storage à utiliser 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 à partir de 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 des documents de votre base de données dans un ensemble de fichiers 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

  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'

Exporter à partir d'un code temporel PITR

Vous pouvez exporter votre base de données vers Cloud Storage à partir de données PITR à l'aide de la commande gcloud firestore export. Vous pouvez exporter des données PITR dont le code temporel est un horodatage d'une minute entière dans au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données ne sont plus existe à 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 l'exportation de collections spécifiques.

1. Exportez la base de données en spécifiant le paramètre snapshot-time vers l'horodatage de récupération souhaité.

   gcloud

   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] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Où :

   • PITR_TIMESTAMP : code temporel PITR au niveau de la minute, par exemple 2023-05-26T10:20:00.00Z.

   Veuillez noter les points suivants avant d'exporter les données PITR:

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

Importer des données

Une fois les fichiers exportés dans Cloud Storage, vous pouvez importer des documents dans ces 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.

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

  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 PARENT_FOLDER_NAME et .overall_export_metadata portent les noms même chose.

Importer tous les documents d'une exportation

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]

Importer une exportation PITR

Suivez la procédure Importer tous les documents pour importer vos base de données. Si un document existe déjà dans votre base de données, il sera remplacé.

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

Lorsque vous lancez 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 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

gcloud firestore operations list

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

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. Cloud Firestore peut omettre cette métrique s'il ne peut pas effectuer 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

gcloud firestore operations cancel [OPERATION_NAME]

L'annulation d'une opération en cours n'annule pas l'opération. Exportation annulée l'opération conservera les documents déjà exportés dans le fichier Cloud Storage et sera annulée l'opération d'importation conservera 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 exporter des fichiers depuis 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 avant de l'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 les écritures de documents aux taux indiqués dans Tarifs de Cloud Firestore. Les opérations d'exportation entraînent une opération de lecture par document exporté. Les opérations d'importation entraînent une opération d'écriture par document importé.

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

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éclenchent pas Google Cloud alertes budgétaires jusqu'à la fin de l'opération. 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 :

Exporter vers BigQuery

Vous pouvez charger les données d'une exportation Cloud Firestore dans BigQuery. mais seulement si vous avez spécifié un filtre collection-ids. Voir Chargement des données à partir d'exportations Cloud Firestore

Nombre maximal de colonnes : BigQuery

BigQuery impose une limite de 10 000 colonnes par table. Les opérations d'exportation Cloud Firestore génèrent une 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, la valeur Cloud Firestore opération d'exportation tente de rester en dessous de la limite de colonnes en traitant les champs de mappage comme des octets. Si cette conversion génère de colonnes inférieur à 10 000, vous pouvez charger les données 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 n'effectue pas générer un schéma BigQuery pour le groupe de collections, 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 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. 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 groupes de collections que les fichiers d'exportation contiennent :

protoc --decode_raw < export0.export_metadata

Migration de l'agent de service

Cloud Firestore utilise un agent de service Cloud Firestore pour autoriser l'importation et les opérations d'exportation au lieu d'utiliser le compte de service App Engine. L'agent de service et le compte de service utilisent les conventions d'attribution de noms suivantes:

Agent de service Cloud Firestore

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

Cloud Firestore a déjà utilisé le 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 à l'utilisation de l'agent de service Cloud Firestore.

App Engine compte de service

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 consulter le compte utilisé par vos opérations d'importation et d'exportation pour autoriser les requêtes sur la page Importations/Exportations de la console Google Cloud. Vous pouvez également vérifier si votre base de données utilise déjà Cloud Firestore à un agent de service Google Cloud.

1. Dans la console Google Cloud, accédez à la page Base 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. Consultez le compte d'autorisation à côté Libellé Les jobs d'importation/exportation s'exécutent en tant que.

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 des techniques suivantes :

• Migrer un projet en vérifiant et en mettant à jour les autorisations du bucket Cloud Storage (recommandé).
• Ajoutez une contrainte de règle d'administration qui affecte tous les projets de l'organisation.

La première de ces techniques est préférable, car elle localise la portée de dans un seul projet Cloud Firestore. La deuxième technique n'est pas privilégié, car il ne migre pas le bucket Cloud Storage existant autorisations. Il offre cependant une conformité en matière de sécurité au niveau de l'organisation d'application.

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. Consultez la section suivante pour en savoir plus plus de détails.
2. Confirmez la migration vers l'agent de service Cloud Firestore.

Autorisations de bucket pour les agents 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 pour ce bucket. Par exemple, les opérations qui déplacent des données vers un autre projet doit accéder à un bucket de cet autre projet. Sinon, ces les opérations échouent après la migration vers le service Cloud Firestore un agent.

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

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

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 autorisations, utilisez un rôle personnalisé.

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

Migrer un projet vers l'agent de service Firestore

Suivez les étapes suivantes pour passer du compte de service App Engine à l'agent de service Cloud Firestore. Une fois la migration terminée, annulée.

1. Dans la console Google Cloud, accédez à la page Base 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. Si votre projet n'a pas encore migré vers le service Cloud Firestore vous voyez une bannière décrivant la migration un bouton Vérifier l'état du bucket. L'étape suivante vous aide à identifier et pour corriger les éventuelles erreurs d'autorisation.

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

   Un menu s'affiche, avec une option permettant de terminer la migration et un liste de Cloud Storage buckets. L'opération peut prendre quelques minutes pour terminer le chargement.

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

5. Notez le nom principal du Cloud Firestore de votre projet. à un agent de service Google Cloud. Le nom de l'agent de service apparaît sous Agent de service autorisant l'accès au libellé.

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

   1. Sur la ligne du tableau de ce bucket, cliquez sur Corriger. La page des autorisations de ce bucket s'ouvre dans un nouvel onglet.

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

7. Cliquez sur Migrer vers l'agent de service Firestore. Si vous des buckets dont les vérifications d'autorisation ont échoué, confirmer votre migration en cliquant sur Migrer.

   Une alerte vous informe lorsque la migration est terminée. Cette opération est irréversible.

Afficher l'état de la migration

Pour vérifier l'état de la migration de votre projet:

1. Dans la console Google Cloud, accédez à la page Base 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. Recherchez le compte principal à côté du libellé Jobs d'importation/exportation exécutés en tant que.

   Si le compte principal est service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, cela signifie que votre projet a déjà été migré vers Cloud Firestore à un agent de service Google Cloud. La migration est irréversible.

   Si le projet n'a pas été migré, une bannière s'affiche en haut de la page. à l'aide d'un bouton Vérifier l'état du bucket. Voir Migrer vers l'agent de service Firestore pour terminer la migration.

Ajouter une contrainte de règle à l'échelle de l'organisation

• Définissez la contrainte suivante dans la règle 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 Agent de service Cloud Firestore pour autoriser les requêtes. Pour définir cette contrainte, consultez Créer et gérer des règles d'administration

L'application de cette contrainte de règle d'administration n'accorde pas automatiquement les autorisations appropriées pour le bucket Cloud Storage 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 Cloud Storage bucket les autorisations, vous pouvez la réactiver.