Exporter et importer des entités

Cette page explique comment exporter et importer des entités Cloud Firestore en mode Datastore à l'aide du service d'exportation et d'importation géré. Le service d'exportation et d'importation géré est disponible via l'outil de ligne de commande gcloud et l'API Admin pour Cloud Datastore (REST, RPC).

Le service d'exportation et d'importation géré vous permet de récupérer des données supprimées de manière accidentelle et de les exporter pour un traitement hors ligne. Vous pouvez exporter toutes les entités ou uniquement des genres d'entités spécifiques. De même, vous pouvez importer toutes les données d'une exportation ou uniquement des genres spécifiques. Lorsque vous utilisez le service d'exportation et d'importation géré, veuillez prendre en compte les éléments suivants :

  • Le service d'exportation utilise des lectures cohérentes à terme. Vous ne pouvez pas supposer qu'une exportation a lieu à un moment donné. L'exportation peut inclure des entités écrites après le lancement de l'exportation et exclure des entités écrites avant le début de l'exportation.

  • Une exportation ne contient aucun index. Lorsque vous importez des données, les index requis sont automatiquement recréés à l'aide des définitions d'index actuelles de votre base de données. Les paramètres d'index de valeur de propriété par entité sont exportés et sont valides lors de l'importation.

  • Les opérations d'importation n'attribuent pas de nouveaux ID aux entités. Elles utilisent les identifiants qui existaient au moment de l'exportation et écrasent toutes les entités existantes avec le même ID. Lors d'une opération d'importation, les ID sont réservés à mesure que les entités sont importées. Cette fonctionnalité empêche les conflits d'ID avec de nouvelles entités si les opérations d'écriture sont activées lorsqu'une importation est en cours d'exécution.

  • Si une entité de votre base de données n'est pas affectée par une importation, elle restera dans votre base de données une fois l'importation terminée.

  • Les données exportées à partir d'une base de données en mode Datastore peuvent être importées dans une autre base de données en mode Datastore, même si elle se trouve dans un autre projet.

  • Le service d'exportation et d'importation géré limite le nombre d'exportations et d'importations simultanées à 50 et autorise un maximum de 20 requêtes d'exportation et d'importation par minute pour un projet.

  • Le résultat d'une exportation gérée utilise le format de journal LevelDB.

Avant de commencer

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

  1. Assurez-vous que la facturation est activée pour votre projet Google Cloud Platform. Seuls les projets GCP avec la facturation activée peuvent utiliser les fonctionnalités d'exportation et d'importation. Pour en savoir plus sur la facturation, consultez la section Facturation et tarifs relatifs aux importations et aux exportations.

  2. Créez un bucket Cloud Storage pour votre projet en utilisant le même emplacement que votre emplacement de base de données Cloud Firestore en mode Datastore. Toutes les opérations d'exportation et d'importation dépendent de Cloud Storage et vous devez utiliser le même emplacement pour le bucket Cloud Storage et la base de données Cloud Firestore en mode Datastore. Vous ne pouvez pas utiliser de bucket "Paiements du demandeur" pour les opérations d'exportation et d'importation.

  3. Attribuez à votre compte utilisateur un rôle IAM, qui accorde l'autorisation datastore.databases.export si vous exportez des données ou l'autorisation datastore.databases.import si vous importez des données. Le rôle Cloud Datastore Import Export Admin, par exemple, accorde les deux autorisations.

  4. Attribuez un rôle IAM Cloud Storage à votre compte utilisateur, qui accorde des autorisations de lecture ou d'écriture pour le bucket Cloud Storage.

Configurer votre environnement

Avant d'exporter ou d'importer des données, vous devez configurer des variables d'environnement pour l'outil gcloud et vous authentifier à l'aide de votre compte utilisateur.

  1. Définissez une variable d'environnement pour l'ID de projet GCP.

    PROJECT_ID="YOUR_PROJECT_ID"
    
  2. Utilisez cette variable pour définir votre projet en tant que configuration active de l'outil gcloud.

    gcloud config set project ${PROJECT_ID}
    
  3. Authentifiez-vous à l'aide de l'outil gcloud.

    gcloud auth login
    
  4. Définissez une variable d'environnement pour votre ID de bucket Cloud Storage.

    BUCKET="YOUR_BUCKET_NAME[/NAMESPACE_PATH]"
    

    YOUR_BUCKET_NAME est le nom du bucket Cloud Storage et NAMESPACE_PATH un chemin d'accès facultatif à l'espace de noms Cloud Storage (il ne s'agit pas d'un espace de noms en mode Datastore). Pour en savoir plus sur les chemins d'accès aux espaces de noms Cloud Storage, consultez la section Remarques concernant les noms d'objet.

Lancer des opérations d'exportation et d'importation gérées

Cette section explique comment lancer une opération d'exportation ou d'importation gérée et en vérifier la progression.

Exporter des entités

Utilisez la commande ci-dessous pour exporter tous les genres d'entités dans l'espace de noms par défaut. Vous pouvez ajouter l'indicateur --async pour empêcher l'outil gcloud d'attendre que l'opération se termine.

gcloud

gcloud datastore export --namespaces="(default)" gs://${BUCKET}

Protocole

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "namespaceIds": [""], }, }'

Pour exporter un sous-ensemble spécifique de genres et/ou d'espaces de noms, fournissez un filtre d'entité avec des valeurs pour les genres et les ID d'espaces de noms.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="NAMESPACE1,NAMESPACE2" gs://${BUCKET}

Protocole

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "kinds": ["KIND1", "KIND2", …], "namespaceIds": ["NAMESPACE1", "NAMESPACE2", …], }, }

Importer des entités

Utilisez la commande ci-dessous pour importer des entités précédemment exportées avec le service d'exportation et d'importation géré. Vous pouvez ajouter l'indicateur --async pour empêcher l'outil gcloud d'attendre que l'opération se termine.

gcloud

gcloud datastore import gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata

Protocole

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:import
-d '{ "inputUrl": "gs://'${BUCKET}'/[PATH]/[FILE].overall_export_metadata", }'

Vous pouvez déterminer la valeur à utiliser pour l'emplacement de l'importation en utilisant l'interface utilisateur Cloud Storage de la console Google Cloud Platform pour afficher le bucket ou en examinant le résultat gcloud datastore export ou ExportEntitiesResponse une fois l'exportation terminée. Voici un exemple de valeur d'un emplacement d'importation :

gcloud

gs://${BUCKET}/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

Protocole

"outputUrl": "gs://'${BUCKET}'/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Exportations ou importations asynchrones

Les opérations d'exportation et d'importation peuvent prendre beaucoup de temps. Lorsque vous effectuez une opération d'exportation ou d'importation, vous pouvez ajouter l'indicateur --async pour empêcher l'outil gcloud d'attendre que l'opération se termine.

Après avoir initié une opération d'exportation ou d'importation, vous pouvez utiliser l'identifiant renvoyé par l'outil gcloud pour vérifier le statut de l'opération. Exemple :

gcloud datastore operations describe ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI

Si vous oubliez l'indicateur --async, vous pouvez également utiliser Ctrl+c pour ne pas avoir à attendre une opération. Taper Ctrl+c n'annulera pas l'opération.

Gérer les opérations de longue durée

Les opérations de longue durée sont des appels de méthodes dont l'exécution peut prendre un temps considérable. Les bases de données en mode Datastore créent des opérations de longue durée lorsque vous exportez ou importez des données.

Par exemple, lorsque vous démarrez une exportation, la base de données en mode Datastore crée une opération de longue durée pour suivre l'état de l'exportation. Voici le résultat du début d'une exportation :

{
  "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2017-05-25T23:54:39.583780Z",
      "operationType": "EXPORT_ENTITIES"
    },
    "progressEntities": {},
    "progressBytes": {},
    "entityFilter": {
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
  }
}

La valeur du champ name correspond à l'ID d'une opération de longue durée.

Cloud Firestore en mode Datastore fournit une API Admin des opérations permettant de vérifier l'état des opérations de longue durée, ainsi que d'annuler, de supprimer ou de répertorier les opérations de longue durée :

Method Description
projects.operations.cancel Annule une opération de longue durée.
projects.operations.delete Supprime une opération de longue durée.

Remarque : La suppression d'une opération ne l'annule pas.
projects.operations.get Obtient l'état d'une opération de longue durée.
projects.operations.list Répertorie les opérations de longue durée.

Liste des opérations de longue durée

Pour répertorier les opérations de longue durée, exécutez les commandes suivantes :

gcloud

gcloud datastore operations list

Protocole

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}/operations

Cet exemple de résultat montre une opération d'exportation ayant pris fin récemment. Une fois terminées, les opérations restent accessibles pendant quelques jours :

{
  "operations": [
    {
      "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://[YOUR_BUCKET_NAME]/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Utilisez la valeur input_url lorsque vous importez les entités.

Estimation du 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 d'entités qu'une opération va traiter, en fonction de . workCompleted indique le nombre d'octets et d'entités traités jusqu'à présent. Une fois l'opération terminée, workCompleted reflète le nombre total d'octets et d'entités réellement traités, qui peut être supérieur à la valeur de workEstimated.

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

Par exemple, voici l'état de la progression d'une opération d'exportation :

{
  "operations": [
    {
      "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

Facturation et tarifs relatifs aux importations et aux exportations

Vous devez activer la facturation pour votre projet Google Cloud Platform 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 opérations de lecture et d'écriture d'entités aux tarifs indiqués dans la section Tarifs du mode Datastore.

Les frais liés aux opérations d'exportation et d'importation ne sont pas comptabilisés parmi les plafonds budgétaires App Engine. En outre, si vous avez défini un budget pour Google Cloud Platform, l'opération d'exportation ou d'importation ne déclenchera pas d'alertes avant 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.

Pour en savoir plus sur la facturation, consultez la section Support pour la facturation et les paiements.

Autorisations

Afin de démarrer les opérations d'exportation et d'importation, les rôles IAM de votre compte utilisateur doivent accorder les autorisations datastore.databases.export et datastore.databases.import. Le rôle Cloud Datastore Import Export Admin, par exemple, accorde les deux autorisations. De même, si vous émettez des requêtes REST depuis la ligne de commande à l'aide de curl, vous devez attribuer un rôle IAM qui accorde ces autorisations à votre compte utilisateur. Pour en savoir plus sur les autorisations d'accès à la base de données en mode Datastore, consultez la section Gestion de l'authentification et des accès (IAM).

Si vous utilisez l'exemple d'application Cron, ses requêtes utilisent le compte de service par défaut App Engine du projet GCP. Vous devez attribuer au compte de service par défaut App Engine le rôle Cloud Datastore Import Export Admin ou un autre rôle accordant l'autorisation datastore.databases.export.

En outre, pour toutes les demandes d'exportation, le compte qui en fait la demande et le compte de service par défaut App Engine pour le projet GCP doivent tous les deux avoir un rôle IAM qui accorde les autorisations suivantes pour votre bucket Cloud Storage :

Nom de l'autorisation Description
storage.buckets.get Lire les métadonnées d'un bucket, à l'exclusion des stratégies IAM.
storage.objects.create Ajouter des objets à un bucket.
storage.objects.list Répertorier les objets dans un bucket. Lire également les métadonnées des objets, à l'exclusion des LCA, lors de la création d'une liste.

Pour obtenir une liste des rôles Cloud Storage, consultez la page Rôles IAM Cloud Storage. Par exemple, les rôles Storage Admin ou Storage Legacy Bucket Writer incluent toutes les autorisations Cloud Storage nécessaires aux opérations d'exportation et peuvent être appliqués à un projet entier ou à un bucket spécifique. Notez que le rôle Storage Object Creator n'inclut pas toutes les autorisations Cloud Storage nécessaires à une opération d'exportation.

Pour les demandes d'importation, le compte qui en fait la demande et le compte de service par défaut App Engine pour le projet GCP doivent tous les deux avoir un rôle IAM qui accorde les autorisations suivantes pour votre bucket Cloud Storage :

Nom de l'autorisation Description
storage.objects.get Lire les données et les métadonnées des objets, à l'exclusion des LCA.
storage.objects.list Répertorier les objets dans un bucket. Lire également les métadonnées des objets, à l'exclusion des LCA, lors de la création d'une liste.

Le rôle Storage Object Viewer accorde toutes les autorisations requises pour l'importation.

Différences par rapport aux sauvegardes administrateur Cloud Datastore

Si vous avez déjà utilisé la console d'administration Cloud Datastore pour les opérations de sauvegarde, vous remarquerez les différences suivantes :

  • Le service d'exportation et d'importation géré ne comprend pas d'interface graphique.

  • Les exportations créées par une opération d'exportation gérée n'apparaissent pas dans la console d'administration Cloud Datastore. Les opérations d'exportation et d'importation gérées constituent un nouveau service qui ne partage pas de données avec la fonctionnalité de sauvegarde et de restauration App Engine, qui est administrée via la console GCP.

  • Le service d'exportation et d'importation géré n'accepte pas les mêmes métadonnées que la sauvegarde administrateur Cloud Datastore et ne stocke pas l'état de la progression dans votre base de données. Pour en savoir plus sur la vérification de la progression des opérations d'exportation et d'importation, consultez la section Gérer les opérations de longue durée.

  • Vous ne pouvez pas afficher les journaux de service des opérations d'exportation et d'importation gérées.

  • Le service d'importation géré est rétrocompatible avec les fichiers de sauvegarde administrateur Cloud Datastore. Vous pouvez importer un fichier de sauvegarde administrateur Cloud Datastore à l'aide du service d'importation géré, mais vous ne pouvez pas importer le résultat d'une exportation gérée à l'aide de la console d'administration Cloud Datastore.

Importer des données dans BigQuery

Pour importer des données d'une exportation gérée dans BigQuery, consultez la section Charger des données à partir de sauvegardes Cloud Datastore.

Limites

  • Les données exportées sans filtre d'entité spécifié ne peuvent pas être chargées dans BigQuery. Si vous souhaitez importer des données dans BigQuery, votre demande d'exportation doit inclure un ou plusieurs noms de genre dans le filtre d'entité.
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Cloud Datastore