Exporter et importer des entités

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Cette page explique comment exporter et importer des entités 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 Cloud Console, la CLI Google Cloud et l'API Datastore Admin (REST, RPC).

Le service d'exportation et d'importation géré vous permet de récupérer des données par inadvertance et de les exporter pour un traitement hors connexion. Vous pouvez exporter toutes les entités ou seulement des genres spécifiques d'entités. 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é, tenez compte des points 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 début de l'exportation et exclure les 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 la propriété par entité sont exportés et respectés lors de l'importation.

  • Les importations n'attribuent pas de nouveaux ID aux entités. Les importations utilisent les ID qui existaient au moment de l'exportation et écrasent toutes les entités existantes avec le même ID. Lors d'une importation, les ID sont réservés pendant l'importation des entités. Cette fonctionnalité empêche les conflits d'ID avec de nouvelles entités si les écritures sont activées pendant l'exécution d'une importation.

  • 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 après l'importation.

  • Les données exportées depuis une base de données en mode Datastore peuvent être importées dans une autre base de données en mode Datastore, même 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. Pour chaque requête, le service limite à 100 le nombre de combinaisons de filtres d'entités.

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

  • Pour importer uniquement un sous-ensemble d'entités ou pour importer des données dans BigQuery, vous devez spécifier un filtre d'entité dans votre exportation.

Avant de commencer

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 les fonctionnalités d'exportation et d'importation.

  2. Créez un bucket Cloud Storage au même emplacement que votre base de données Firestore en mode Datastore. Vous ne pouvez pas utiliser de buckets 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 Datastore Import Export Admin, par exemple, accorde les deux autorisations.

  4. Si le bucket Cloud Storage se trouve dans un autre projet, accordez à votre compte de service par défaut l'accès au bucket.

Configurer gcloud pour votre projet

Si vous envisagez d'utiliser gcloud pour lancer vos opérations d'importation et d'exportation, configurez gcloud et connectez-vous à votre projet de l'une des manières suivantes:

Démarrer 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.

Exporter toutes les entités

Console

  1. Accédez à la page Importations/Exportations Datastore dans Google Cloud Console.

    Accéder à la page "Importations/Exportations"

  2. Cliquez sur Exporter.

  3. Définissez le champ Espace de noms sur All Namespaces, puis définissez le champ Genre sur All Kinds.

  4. Sous Destination, saisissez le nom de votre bucket Cloud Storage.

  5. Cliquez sur Exporter.

La console revient à la page Importations/Exportations. Une alerte signale le succès ou l'échec de votre requête d'exportation gérée.

gcloud

Utilisez la commande gcloud datastore export pour exporter toutes les entités de votre base de données.

 gcloud datastore export gs://bucket-name --async

bucket-name est le nom de votre bucket Cloud Storage et un préfixe facultatif, par exemple, bucket-name/datastore-exports/export-name. Vous ne pouvez pas réutiliser le même préfixe pour une autre opération d'exportation. Si vous ne fournissez pas de préfixe de fichier, le service d'exportation géré en crée un en fonction de l'heure actuelle.

Ajoutez l'indicateur --async pour empêcher gcloud d'attendre la fin de l'opération. Si vous omettez l'option --async, vous pouvez saisir Ctrl+c pour arrêter d'attendre une opération. Cette opération n'annule pas l'opération.

repos

Avant d'utiliser les données de la requête, effectuez les remplacements suivants:

  • project-id : ID de votre projet.
  • bucket-name: nom de votre bucket Cloud Storage

Méthode HTTP et URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

Corps JSON de la requête:

{
  "outputUrlPrefix": "gs://bucket-name",
}

Pour envoyer votre demande, développez l'une de ces options:

Vous devriez recevoir une réponse JSON de ce type:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}
La réponse est une opération de longue durée dont vous pouvez vérifier l'achèvement.

Exporter des genres ou des espaces de noms spécifiques

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. Chaque requête est limitée à 100 combinaisons de filtres d'entités, où chaque combinaison de genre filtré et d'espace de noms est comptabilisée comme un filtre distinct dans cette limite.

Console

Dans la console, vous pouvez sélectionner tous les genres ou un genre spécifique. De même, vous pouvez sélectionner tous les espaces de noms ou un espace de noms spécifique.

Pour spécifier une liste d'espaces de noms et de genres à exporter, utilisez plutôt gcloud.

  1. Accédez à la page Exportation Cloud Datastore dans Google Cloud Console.

    Accéder à la page "Exportation Cloud Datastore"

  2. Cliquez sur Exporter.

  3. Définissez le champ Espace de noms sur All Namespaces ou sur le nom de l'un de vos espaces de noms.

  4. Définissez le champ Genre sur All Kinds ou sur le nom d'un genre.

  5. Sous Destination, saisissez le nom de votre bucket Cloud Storage.

  6. Cliquez sur Exporter.

La console revient à la page Importations/Exportations. Une alerte signale le succès ou l'échec de votre requête d'exportation gérée.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name --async

bucket-name est le nom de votre bucket Cloud Storage et un préfixe facultatif, par exemple, bucket-name/datastore-exports/export-name. Vous ne pouvez pas réutiliser le même préfixe pour une autre opération d'exportation. Si vous ne fournissez pas de préfixe de fichier, le service d'exportation géré en crée un en fonction de l'heure actuelle.

Ajoutez l'indicateur --async pour empêcher gcloud d'attendre la fin de l'opération. Si vous omettez l'option --async, vous pouvez saisir Ctrl+c pour arrêter d'attendre une opération. Cette opération n'annule pas l'opération.

repos

Avant d'utiliser les données de la requête, effectuez les remplacements suivants:

  • project-id: ID de votre projet.
  • bucket-name: nom de votre bucket Cloud Storage
  • kind : genre de l'entité.
  • namespace : ID de l'espace de noms (utilisez l'ID d'espace de noms par défaut).

Méthode HTTP et URL:

POST https://datastore.googleapis.com/v1/projects/project-id:export

Corps JSON de la requête:

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Pour envoyer votre demande, développez l'une de ces options:

Vous devriez recevoir une réponse JSON de ce type:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}
La réponse est une opération de longue durée dont vous pouvez vérifier l'achèvement.

Fichiers de métadonnées

Une opération d'exportation crée un fichier de métadonnées pour chaque paire espace de noms/genre spécifiée. Les fichiers de métadonnées sont généralement nommés NAMESPACE_NAME_KIND_NAME.export_metadata. Toutefois, si un espace de noms ou un genre crée un nom d'objet Cloud Storage non valide, le fichier est nommé export[NUM].export_metadata.

Les fichiers de métadonnées sont des tampons de protocole et peuvent être décodés à l'aide du compilateur de protocole protoc. Par exemple, vous pouvez décoder un fichier de métadonnées pour déterminer l'espace de noms et les genres que contiennent les fichiers d'exportation:

protoc --decode_raw < export0.export_metadata

Importer toutes les entités

Console

  1. Accédez à la page Importation dans Datastore dans Google Cloud Console.

    Accéder à la page "Importations Datastore"

  2. Cliquez sur Import (Importer).

  3. Dans le champ File, cliquez sur Parcourir et sélectionnez un fichier overall_export_metadata.

  4. Définissez le champ Espace de noms sur All Namespaces, puis définissez le champ Genre sur All Kinds.

  5. Cliquez sur Import (Importer).

La console revient à la page Importations/Exportations. Une alerte signale le succès ou l'échec de votre requête d'importation gérée.

gcloud

Exécutez la commande gcloud datastore import pour importer toutes les entités précédemment exportées avec le service d'exportation géré.

gcloud datastore import gs://bucket-name/file-path/file-name.overall_export_metadata --async

bucket-name/file-path/file-name est le chemin d'accès à votre fichier overall_export_metadata dans votre bucket Cloud Storage.

Ajoutez l'indicateur --async pour empêcher gcloud d'attendre la fin de l'opération. Si vous omettez l'option --async, vous pouvez saisir Ctrl+c pour arrêter d'attendre une opération. Cette opération n'annule pas l'opération.

repos

Avant d'utiliser les données de la requête, effectuez les remplacements suivants:

  • project-id: ID de votre projet.
  • bucket-name: nom de votre bucket Cloud Storage
  • object-name: nom de votre objet Cloud Storage (exemple: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata).

Méthode HTTP et URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

Corps JSON de la requête:

{
  "inputUrl": "gs://bucket-name/object-name",
}

Pour envoyer votre demande, développez l'une de ces options:

Vous devriez recevoir une réponse JSON de ce type:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}
La réponse est une opération de longue durée dont vous pouvez vérifier l'achèvement.

Localiser votre fichier overall_export_metadata

Vous pouvez déterminer la valeur de l'emplacement d'importation à l'aide du navigateur Cloud Storage dans Google Cloud Console:

Ouvrir le navigateur Cloud Storage

Vous pouvez également répertorier et décrire les opérations terminées. Le champ outputURL affiche le nom du fichier overall_export_metadata:

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Importer des genres ou des espaces de noms spécifiques

Pour importer 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.

Vous ne pouvez spécifier des genres et des espaces de noms que si les fichiers d'exportation ont été créés avec un filtre d'entité. Vous ne pouvez pas importer un sous-ensemble de genres et d'espaces de noms à partir d'une exportation de toutes les entités.

Console

Dans la console, vous pouvez sélectionner tous les genres ou un genre spécifique. De même, vous pouvez sélectionner tous les espaces de noms ou un espace de noms spécifique.

Pour spécifier une liste d'espaces de noms et de genres à importer, utilisez plutôt gcloud.

  1. Accédez à la page Importation dans Datastore dans Google Cloud Console.

    Accéder à la page "Importations Datastore"

  2. Cliquez sur Import (Importer).

  3. Dans le champ File, cliquez sur Parcourir et sélectionnez un fichier overall_export_metadata.

  4. Définissez le champ Espace de noms sur All Namespaces ou sur un espace de noms spécifique.

  5. Définissez le champ Genre sur All Kinds ou sur un genre spécifique.

  6. Cliquez sur Import (Importer).

La console revient à la page Importations/Exportations. Une alerte signale le succès ou l'échec de votre requête d'importation gérée.

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name/file-path/file-name.overall_export_metadata --async

bucket-name/file-path/file-name est le chemin d'accès à votre fichier overall_export_metadata dans votre bucket Cloud Storage.

Ajoutez l'indicateur --async pour empêcher gcloud d'attendre la fin de l'opération. Si vous omettez l'option --async, vous pouvez saisir Ctrl+c pour arrêter d'attendre une opération. Cette opération n'annule pas l'opération.

repos

Avant d'utiliser les données de la requête, effectuez les remplacements suivants:

  • project-id: ID de votre projet.
  • bucket-name : nom de votre bucket Cloud Storage
  • object-name: nom de votre objet Cloud Storage (exemple: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata).
  • kind : genre de l'entité.
  • namespace: ID de l'espace de noms (utilisez l'ID d'espace de noms par défaut).

Méthode HTTP et URL:

POST https://datastore.googleapis.com/v1/projects/project-id:import

Corps JSON de la requête:

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Pour envoyer votre demande, développez l'une de ces options:

Vous devriez recevoir une réponse JSON de ce type:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}
La réponse est une opération de longue durée dont vous pouvez vérifier l'achèvement.

Importer les transformations

Lorsque vous importez des entités à partir d'un autre projet, gardez à l'esprit que les clés d'entité incluent l'ID du projet. Une opération d'importation met à jour les clés d'entité et les propriétés de référence des clés dans les données d'importation avec l'ID du projet de destination. Si cette mise à jour augmente les tailles d'entité, cela peut entraîner des erreurs trop importantes d'entrées d'index ou d'index des opérations d'importation.

Pour éviter l'une de ces erreurs, importez le fichier dans un projet de destination avec un ID de projet plus court. Cela n'affecte pas les opérations d'importation avec des données du même projet.

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

Les opérations d'importation et d'exportation gérées sont des opérations de longue durée. Ces appels de méthode peuvent prendre beaucoup de temps.

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

Les noms des opérations comportent le préfixe projects/[PROJECT_ID]/databases/(default)/operations/, par exemple:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Vous pouvez omettre le préfixe lorsque vous spécifiez un nom d'opération pour les commandes gcloud.

Répertorier toutes les opérations de longue durée

Vous pouvez afficher les opérations en cours et récemment terminées de différentes manières. Les opérations sont répertoriées pendant quelques jours après la fin de l'opération:

Console

Vous pouvez afficher la liste des opérations d'exportation et d'importation les plus récentes sur la page Importations/Exportations en mode Datastore de Google Cloud Console.

Accéder à la page "Importations/Exportations"

gcloud

Pour répertorier les opérations de longue durée, utilisez la commande gcloud datastore Operations list.

gcloud datastore operations list

Par exemple, une opération d'exportation récemment terminée affiche les informations suivantes:

{
  "operations": [
    {
      "name": "projects/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://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

repos

Avant d'utiliser les données de la requête, effectuez les remplacements suivants:

  • project-id: ID de votre projet.

Méthode HTTP et URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Pour envoyer votre demande, développez l'une de ces options:

Pour en savoir plus sur cette réponse, consultez les informations ci-dessous.

Par exemple, une opération d'exportation récemment terminée affiche les informations suivantes:

{
  "operations": [
    {
      "name": "projects/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://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

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

Pour afficher l'état d'une opération de longue durée, procédez comme suit:

Console

Vous pouvez afficher la liste des opérations d'exportation et d'importation les plus récentes sur la page Importations/Exportations en mode Datastore de Google Cloud Console.

Accéder à la page "Importations/Exportations"

gcloud

Utilisez la commande operations describe pour afficher l'état d'une opération de longue durée.

gcloud datastore operations describe operation-name

repos

Avant d'utiliser les données de la requête, effectuez les remplacements suivants:

  • project-id: ID de votre projet.
  • operation-name : nom de l'opération

Méthode HTTP et URL:

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

Pour envoyer votre demande, développez l'une de ces options:

Vous devriez recevoir une réponse JSON de ce type:

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

Estimer le délai d'exécution

Lors de l'exécution de l'opération, consultez la valeur du champ state pour obtenir l'état général de l'opération.

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 affiche le nombre total estimé d'octets et de documents qu'une opération traitera.

  • 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, ce 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.

Voici, par exemple, l'état de progression d'une opération d'exportation:

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

Une fois l'opération terminée, sa description contient "done": true. Consultez la valeur du champ state pour obtenir le résultat de l'opération. Si le champ done n'est pas défini dans la réponse, sa valeur est false. Ne vous basez pas sur l'existence de la valeur done pour les opérations en cours.

Annuler une opération

Console

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

Accéder à la page "Importations/Exportations"

Dans la table Importations et exportations récentes, les opérations en cours d'exécution incluent un bouton Annuler dans la colonne Terminée. Cliquez sur le bouton Annuler pour arrêter l'opération. Le bouton devient un message Cancelling (Annulation), puis Cancelled (Annulée) lorsque l'opération s'arrête complètement.

gcloud

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

gcloud datastore 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 conserve les 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

gcloud

Utilisez la commande 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 datastore operations delete operation-name

Facturation et tarifs des exportations et importations gérées

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 contribuent à vos coûts Google Cloud de différentes manières:

Les coûts des opérations d'exportation et d'importation ne sont pas comptabilisés dans le plafond budgétaire d'App Engine. Les opérations d'exportation ou d'importation ne déclenchent aucune alerte de budget Google Cloud 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.

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édez au libellé goog-firestoremanaged depuis le menu des filtres.

Autorisations

Pour exécuter des opérations d'exportation et d'importation, votre compte utilisateur et le compte de service par défaut de votre projet nécessitent les autorisations Identity and Access Management décrites ci-dessous.

Autorisations des comptes utilisateur

Le compte utilisateur ou le compte de service à l'origine de l'opération nécessite les autorisations IAM datastore.databases.export et datastore.databases.import. Si vous êtes le propriétaire du projet, votre compte dispose des autorisations requises. Sinon, les rôles IAM suivants accordent les autorisations nécessaires:

  • Propriétaire Datastore
  • Administrateur des importations et des exportations Datastore

Vous pouvez également attribuer ces autorisations avec un rôle personnalisé.

Un propriétaire de projet peut attribuer l'un de ces rôles en suivant la procédure décrite dans la section Accorder l'accès.

Autorisations par défaut pour le compte de service

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 l'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 en mode Datastore, le compte de service par défaut a accès au bucket 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.

Attribuer des rôles au compte de service par défaut

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" au compte de service par défaut, exécutez la commande suivante:

gsutil iam ch serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

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

Opérations d'exportation

Pour les opérations d'exportation impliquant un bucket situé dans un autre projet, modifiez les autorisations du bucket pour attribuer l'un des rôles Cloud Storage suivants au compte de service par défaut du projet contenant votre base de données en mode Datastore:

  • Administrateur de l'espace de stockage
  • Administrateur des objets Storage
  • Rédacteur des anciens buckets Storage

Vous pouvez également créer un rôle personnalisé IAM avec des autorisations légèrement différentes de celles contenues dans les rôles répertoriés ci-dessus:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.list

Opérations d'importation

Pour les opérations d'importation impliquant un bucket Cloud Storage dans un autre projet, modifiez les autorisations du bucket pour attribuer l'un des rôles Cloud Storage suivants au compte de service par défaut du projet contenant votre base de données en mode Datastore:

  • Administrateur de l'espace de stockage
  • Lecteur des objets de l'espace de stockage et lecteur des anciens buckets Storage

Vous pouvez également créer un rôle personnalisé IAM avec les autorisations suivantes:

  • storage.buckets.get
  • storage.objects.get

Compte de service par défaut désactivé ou supprimé

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 en mode Datastore. Si vous avez désactivé votre compte de service App Engine, vous pouvez le réactiver en consultant 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. Pour en savoir plus, consultez la section Annuler la suppression d'un compte de service.

Différences par rapport aux sauvegardes administrateur Datastore

Si vous avez déjà utilisé la console d'administration Datastore pour les sauvegardes, vous devez noter les différences suivantes:

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

  • Le service d'exportation et d'importation géré n'accepte pas les mêmes métadonnées que la sauvegarde administrateur Datastore et ne stocke pas l'état de 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 page 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 Datastore. Vous pouvez importer un fichier de sauvegarde administrateur 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 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 du service d'exportation Datastore.

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 requête d'exportation doit inclure un ou plusieurs noms de genre dans le filtre d'entité.

Limite de colonnes BigQuery

BigQuery impose une limite de 10 000 colonnes par table. Les opérations d'exportation génèrent un schéma de table BigQuery pour chaque genre. Dans ce schéma, chaque propriété unique d'une entité de genre devient une colonne du schéma.

Si le schéma BigQuery d'un genre dépasse 10 000 colonnes, l'opération d'exportation tente de rester en dessous de la limite de colonnes en traitant les entités intégrées comme des blobs. Si cette conversion réduit le nombre de colonnes du schéma à moins de 10 000, vous pouvez charger les données dans BigQuery, mais vous ne pouvez pas interroger les propriétés des entités intégrées. 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 genre et vous ne pouvez pas charger ses données dans BigQuery.

Migration de l'agent de service

Vous pouvez maintenant utiliser un agent de service Firestore pour autoriser les opérations d'importation et d'exportation au lieu du 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 Firestore
service-project_number@gcp-sa-firestore.iam.gserviceaccount.com
Compte de service App Engine
project_id@appspot.gserviceaccount.com

L'agent de service Firestore est préférable, car il est spécifique à Firestore. Le compte de service App Engine est partagé par plusieurs services.

Vous pouvez migrer vers l'agent de service Firestore à l'aide de l'une des techniques suivantes:

La première de ces techniques est préférable, car elle localise le champ d'application de l'effet sur un seul projet en mode Datastore. La deuxième technique n'est pas recommandée, car elle ne permet pas de migrer les autorisations existantes du bucket Cloud Storage. Toutefois, cette solution offre des exigences de sécurité au niveau de l'organisation.

Effectuer la migration en vérifiant et en mettant à jour les autorisations des buckets Cloud Storage

Le processus de migration comporte deux étapes:

  1. Mettre à jour les autorisations relatives au bucket Cloud Storage Pour en savoir plus, consultez la section suivante.
  2. Confirmez la migration vers l'agent de service Firestore.

Autorisations relatives aux buckets d'agents de service

Pour les opérations d'exportation ou d'importation qui utilisent un bucket Cloud Storage dans un autre projet, vous devez accorder à l'agent de service Firestore les autorisations correspondantes. Par exemple, les opérations qui déplacent des données vers un autre projet doivent accéder à un bucket de cet autre projet. Sinon, ces opérations échouent après la migration vers l'agent de service 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 Firestore peut accéder par défaut aux buckets d'un même projet.

Mettez à jour les autorisations des buckets Cloud Storage des autres projets pour permettre à l'agent de service service-project_number@gcp-sa-firestore.iam.gserviceaccount.com d'accéder. Attribuez à 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 ne devez accorder que 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 pouvant nécessiter des mises à jour des autorisations.

Migrer un projet vers l'agent de service Firestore

Procédez comme suit pour migrer du compte de service App Engine vers l'agent de service Firestore. Elle est impossible à réaliser une fois la migration terminée.

  1. Accédez à la page Importations/Exportations Datastore dans Google Cloud Console.

    Accéder à la page "Importations/Exportations"

  2. Si la migration de votre projet vers l'agent de service Firestore n'a pas encore été effectuée, une bannière décrivant la migration et un bouton Vérifier l'état du bucket s'affichent. L'étape suivante vous permet d'identifier et de corriger les erreurs d'autorisation potentielles.

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

    Un menu comportant l'option permettant de terminer la migration et la liste des buckets Cloud Storage s'affiche. Le chargement de la liste peut prendre quelques minutes.

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

  3. Notez le nom principal de l'agent de service en mode Datastore de votre projet. Le nom de l'agent de service apparaît sous le libellé Agent de service auquel accorder l'accès.
  4. Pour tout bucket 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. La page des autorisations relatives à ce bucket s'ouvre dans un nouvel onglet.

    2. Cliquez sur Add (Ajouter).
    3. Dans le champ Nouveaux comptes principaux, saisissez le nom de votre agent de service Firestore.
    4. Dans le champ Sélectionner un rôle, sélectionnez Agents de service > Agent de service Firestore.
    5. Cliquez sur Save (Enregistrer).
    6. Revenez à l'onglet de la page Importations/Exportations en mode Datastore.
    7. Répétez ces étapes pour les autres buckets de la liste. Veillez à afficher toutes les pages de la liste.
  5. Cliquez sur Migrer vers l'agent de service Firestore. Si certains buckets comportent encore des échecs de vérification des autorisations, vous devez confirmer votre migration en cliquant sur Migrer.

    Une alerte s'affiche une fois la migration terminée. La migration est irréversible.

Afficher l'état de la migration

Pour vérifier l'état de la migration de votre projet, accédez à la page Importations/Exportations dans Google Cloud Console:

Accéder à la page "Importations/Exportations"

Recherchez le compte principal à côté du libellé Compte de service utilisé.

Si le compte principal est service-project_number@gcp-sa-firestore.iam.gserviceaccount.com, votre projet a déjà migré vers l'agent de service Firestore. La migration est irréversible.

Si le projet n'a pas été migré, une bannière apparaît en haut de la page avec le bouton Vérifier l'état du bucket. Consultez la section 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:

Exigez 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 l'agent de service Firestore pour autoriser les requêtes.

Pour définir cette contrainte, consultez la section Créer et gérer les règles d'administration.

L'application de cette contrainte de règle d'administration n'accorde pas automatiquement les autorisations de bucket Cloud Storage appropriées pour l'agent de service Firestore.

Si la contrainte crée des erreurs d'autorisation pour un workflow d'importation ou d'exportation, vous pouvez la désactiver pour revenir à l'utilisation du compte de service par défaut. Après avoir validé et mis à jour les autorisations sur un bucket Cloud Storage, vous pouvez réactiver la contrainte.