Charger des données à partir d'exportations Cloud Datastore

Google BigQuery accepte le chargement de données à partir des exportations Cloud Datastore créées à l'aide du service d'importation et d'exportation géré de Cloud Datastore. Le service d'importation et d'exportation géré permet d'exporter des entités Cloud Datastore dans un bucket Cloud Storage. Il suffit ensuite de charger l'exportation dans BigQuery en tant que table.

Pour savoir comment créer un fichier d'exportation Cloud Datastore, consultez la page Exporter et importer des entités de la documentation Cloud Datastore. Pour en savoir plus sur la planification des exportations, consultez la page Programmer une exportation.

Pour contrôler les propriétés que BigQuery doit charger, définissez la propriété projectionFields dans l'API ou utilisez l'indicateur --projection_fields dans l'interface de ligne de commande.

Si vous préférez éviter le processus de chargement, configurez l'exportation en tant que source de données externe afin de pouvoir l'interroger directement. Pour en savoir plus, consultez la page Sources de données externes.

Lorsque vous chargez des données depuis Cloud Storage dans une table BigQuery, l'ensemble de données contenant la table doit se trouver dans la même zone régionale ou multirégionale que le bucket Cloud Storage.

Autorisations requises

Lorsque vous chargez des données dans BigQuery, vous avez besoin d'autorisations au niveau du projet ou de l'ensemble de données qui vous permettent de procéder au chargement dans des tables et partitions BigQuery nouvelles ou existantes. Si vous chargez des données depuis Cloud Storage, vous devez également avoir accès au bucket contenant vos données.

Autorisations BigQuery

Lorsque vous chargez des données dans BigQuery depuis Cloud Storage, vous devez disposer du rôle bigquery.dataOwner ou bigquery.dataEditor au niveau du projet ou de l'ensemble de données. Les deux rôles permettent aux utilisateurs et aux groupes de charger les données dans une nouvelle table, de les ajouter à une table existante ou de les utiliser pour écraser une table.

L'attribution des rôles au niveau du projet donne à l'utilisateur ou au groupe la possibilité de charger les données dans les tables de chaque ensemble de données du projet. L'attribution des rôles au niveau de l'ensemble de données permet à l'utilisateur ou au groupe de charger les données uniquement dans les tables de cet ensemble de données.

Pour plus d'informations sur la configuration de l'accès aux ensembles de données, consultez la page Contrôler l'accès aux ensembles de données. Pour plus d'informations sur les rôles IAM dans BigQuery, consultez la page Contrôle des accès.

Autorisations Cloud Storage

Pour charger les données d'un bucket Cloud Storage, vous devez disposer des autorisations storage.objects.get au niveau du projet ou du bucket concerné. Si vous utilisez un caractère générique dans l'URI, vous devez également disposer des autorisations storage.objects.list.

Le rôle IAM prédéfini storage.objectViewer peut être attribué pour accorder les autorisations storage.objects.get et storage.objects.list.

Limites

Lorsque vous chargez des données dans BigQuery à partir d'une exportation Cloud Datastore, tenez compte des restrictions suivantes :

  • Vous ne pouvez pas utiliser de caractère générique dans l'URI Cloud Storage lorsque vous spécifiez un fichier d'exportation Cloud Datastore.
  • Vous ne pouvez spécifier qu'un seul URI Cloud Storage lors du chargement de données à partir d'exportations Cloud Datastore.
  • Vous ne pouvez pas ajouter de données d'exportation Cloud Datastore à une table existante avec un schéma défini.
  • Pour qu'une exportation Cloud Datastore se charge correctement, les entités des données d'exportation doivent partager un schéma cohérent.
  • Les données exportées sans filtre d'entité spécifié ne peuvent pas être chargées dans BigQuery. La requête d'exportation doit inclure un ou plusieurs noms de genre dans le filtre d'entité.
  • La taille maximale du champ pour les exportations Cloud Datastore est de 64 Ko. Lorsque vous chargez une exportation Cloud Datastore, si le champ dépasse 64 Ko, il est tronqué.

Charger des données du service d'exportation Cloud Datastore

Pour charger des données à partir d'un fichier de métadonnées d'exportation Cloud Datastore, procédez comme suit :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP.

    Accéder à l'UI Web de BigQuery

  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données. Cliquez sur Create table (Créer une table). Le processus de chargement des données est identique au processus de création d'une table vide.

    Créer une table

  3. Dans la section Source de la page Create table (Créer une table) :

    • Dans Create table from (Créer une table à partir de), sélectionnez Cloud Storage.

      Source pour la création d'une table

    • Dans le champ "Source", saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit se trouver dans le même emplacement que l'ensemble de données contenant la table que vous créez. L'URI de votre fichier d'exportation Cloud Datastore doit se terminer par [KIND_NAME].export_metadata. Par exemple : default_namespace_kind_Book.export_metadata. Dans cet exemple, Book est le nom de genre et default_namespace_kind_Book est le nom de fichier généré par Cloud Datastore.

      Vérifiez que [KIND_NAME] est spécifié dans votre URI Cloud Storage. Si vous spécifiez l'URI sans [KIND_NAME], vous obtenez l'erreur suivante : does not contain valid backup metadata. (error code: invalid).

    • Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore.

  4. Dans la section Destination de la page Create table (Créer une table) :

    • Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.

      Sélectionner un ensemble de données

    • Dans le champ Nom de la table, saisissez le nom de la table que vous créez dans BigQuery.

    • Vérifiez que Table type (Type de table) est défini sur Native table (Table native).

  5. Aucune action n'est nécessaire dans la section Schéma. Le schéma est obtenu à partir d'une exportation Cloud Datastore.

  6. Sélectionnez les éléments applicables dans la section Options avancées, puis cliquez sur Créer une table. Pour en savoir plus sur les options disponibles, consultez la section Options Cloud Datastore.

UI classique

  1. Accédez à l'UI Web classique de BigQuery.
    Accéder à l'UI Web de BigQuery
  2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Cliquez ensuite sur la flèche vers le bas image de la flèche vers le bas, puis sur Créer une table. Le processus de chargement des données est identique au processus de création d'une table vide.
  3. Dans la section Données sources de la page Créer une table, procédez comme suit :
    • Laissez l'option Créer à partir de la source sélectionnée.
    • Dans le champ Emplacement, sélectionnez Cloud Storage et, dans le champ "Source", saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit être situé dans le même emplacement que l'ensemble de données contenant la table que vous êtes en train de créer. L'URI de votre fichier d'exportation Cloud Datastore doit se terminer par [KIND_NAME].export_metadata. Par exemple : default_namespace_kind_Book.export_metadata. Dans cet exemple, Book est le nom de genre et default_namespace_kind_Book est le nom de fichier généré par Cloud Datastore.

      Vérifiez que [KIND_NAME] est spécifié dans votre URI Cloud Storage. Si vous spécifiez l'URI sans [KIND_NAME], vous obtenez l'erreur suivante : does not contain valid backup metadata. (error code: invalid).

    • Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore.
  4. Dans la section Table de destination de la page Créer une table :
    • Pour Nom de la table, sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table que vous créez dans BigQuery dans le champ correspondant.
    • Vérifiez que Type de table est défini sur Table native.
  5. Aucune action n'est nécessaire dans la section Schéma. Le schéma est obtenu à partir d'une exportation Cloud Datastore.
  6. Sélectionnez les éléments applicables dans la section Options, puis cliquez sur Créer une table. Pour en savoir plus sur les options disponibles, consultez la section Options Cloud Datastore.

Ligne de commande

Utilisez la commande bq load en définissant source_format sur DATASTORE_BACKUP. Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement.

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

où :

  • [LOCATION] correspond à votre emplacement. Cet indicateur --location est facultatif. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez définir une valeur par défaut pour l'emplacement en utilisant le fichier .bigqueryrc.
  • [FORMAT] est DATASTORE_BACKUP.
  • [DATASET] est l'ensemble de données qui contient la table dans laquelle vous chargez les données.
  • [TABLE] est la table dans laquelle vous chargez les données. Si cette table n'existe pas, elle est créée.
  • [PATH_TO_SOURCE] est l'URI Cloud Storage.

Par exemple, la commande suivante charge le fichier d'exportation Cloud Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata dans une table nommée book_data. mybucket et mydataset ont été créés dans la zone multirégionale US.

bq --location=US load --source_format=DATASTORE_BACKUP mydataset.book_data gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Définissez les propriétés suivantes pour charger les données d'exportation Cloud Datastore à l'aide de l'API.

  1. Créez une tâche de chargement qui pointe vers les données sources dans Cloud Storage.

  2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.

  3. Les URI sources doivent être complets et doivent respecter le format gs://[BUCKET]/[OBJECT]. Le nom du fichier (objet) doit se terminer par [KIND_NAME].export_metadata. Vous ne pouvez spécifier qu'un seul URI pour les exportations Cloud Datastore. En outre, celui-ci ne doit pas comporter de caractère générique.

  4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur DATASTORE_BACKUP.

Sauvegardes administrateur Cloud Datastore

Si vous utilisez la fonctionnalité Sauvegardes administrateur Cloud Datastore pour exporter vos données Cloud Datastore, notez que l'extension de fichier sera .backup_info au lieu de .export_metadata. Lorsque vous importez vos données dans BigQuery, vous pouvez utiliser un fichier .backup_info ou un fichier .export_metadata jusqu'à ce que le service Sauvegardes administrateur Cloud Datastore ne soit plus disponible.

Ajouter ou écraser une table avec des données Cloud Datastore

Lorsque vous chargez des données d'exportation Cloud Datastore dans BigQuery, vous pouvez créer une nouvelle table pour stocker les données ou écraser une table existante. Vous ne pouvez pas ajouter de données d'exportation Cloud Datastore à une table existante.

Si vous tentez d'ajouter des données d'exportation Cloud Datastore à une table existante, le message d'erreur suivant s'affiche : Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

Pour écraser une table existante avec des données d'exportation Cloud Datastore, procédez comme suit :

Console

  1. Ouvrez l'interface utilisateur Web de BigQuery dans la console GCP. Accéder à l'UI Web de BigQuery
  2. Dans la section Ressources du panneau de navigation, développez votre projet et sélectionnez un ensemble de données. Cliquez sur Create table (Créer une table). Le processus de chargement des données est identique au processus de création d'une table vide. Créer une table
  3. Dans la section Source de la page Create table (Créer une table) :

    • Dans Create table from (Créer une table à partir de), sélectionnez Cloud Storage.

      Source pour la création d'une table

    • Dans le champ "Source", saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit se trouver dans le même emplacement que l'ensemble de données contenant la table que vous créez. L'URI de votre fichier d'exportation Cloud Datastore doit se terminer par [KIND_NAME].export_metadata. Par exemple : default_namespace_kind_Book.export_metadata. Dans cet exemple, Book est le nom de genre et default_namespace_kind_Book est le nom de fichier généré par Cloud Datastore.

      Vérifiez que [KIND_NAME] est spécifié dans votre URI Cloud Storage. Si vous spécifiez l'URI sans [KIND_NAME], vous obtenez l'erreur suivante : does not contain valid backup metadata. (error code: invalid).

    • Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore.

  4. Dans la section Destination de la page Create table (Créer une table) :

    • Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données approprié.

      Sélectionner un ensemble de données

    • Dans le champ Nom de la table, saisissez le nom de la table que vous créez dans BigQuery.

    • Vérifiez que Table type (Type de table) est défini sur Native table (Table native).

  5. Aucune action n'est nécessaire dans la section Schéma. Le schéma est obtenu à partir d'une exportation Cloud Datastore.

  6. Dans la section Options avancées, pour Préférence d'écriture, sélectionnez Écraser la table.

  7. Cliquez sur Create table (Créer une table).

UI classique

  1. Accédez à l'UI Web classique de BigQuery.
    Accéder à l'UI Web de BigQuery
  2. Dans le panneau de navigation, passez la souris sur un ensemble de données. Cliquez ensuite sur la flèche vers le bas image de la flèche vers le bas, puis sur Créer une table. Le processus de chargement des données est identique au processus de création d'une table vide.
  3. Dans la section Données sources de la page Créer une table, procédez comme suit :
    • Laissez l'option Créer à partir de la source sélectionnée.
    • Dans le champ Emplacement, sélectionnez Cloud Storage et, dans le champ "Source", saisissez l'URI Cloud Storage. Le bucket Cloud Storage doit être situé dans le même emplacement que l'ensemble de données contenant la table que vous êtes en train de créer. L'URI de votre fichier d'exportation Cloud Datastore doit se terminer par [KIND_NAME].export_metadata. Par exemple : default_namespace_kind_Book.export_metadata. Dans cet exemple, Book est le nom de genre et default_namespace_kind_Book est le nom de fichier généré par Cloud Datastore.

      Vérifiez que [KIND_NAME] est spécifié dans votre URI Cloud Storage. Si vous spécifiez l'URI sans [KIND_NAME], vous obtenez l'erreur suivante : does not contain valid backup metadata. (error code: invalid).

    • Pour le champ Format de fichier, sélectionnez Sauvegarde Cloud Datastore.
  4. Dans la section Table de destination de la page Créer une table :
    • Dans le champ Nom de la table, sélectionnez l'ensemble de données approprié, puis saisissez le nom de la table que vous écrasez.
    • Vérifiez que Type de table est défini sur Table native.
  5. Aucune action n'est nécessaire dans la section Schéma. Le schéma est obtenu à partir d'une exportation Cloud Datastore.
  6. Dans la section Options, pour Préférence d'écriture, sélectionnez Écraser la table.
  7. Cliquez sur Créer une table.

Ligne de commande

Utilisez la commande bq load avec l'indicateur --replace et le paramètre source_format défini sur DATASTORE_BACKUP. Spécifiez l'indicateur --location et définissez la valeur sur votre emplacement .

bq --location=[LOCATION] load --source_format=[FORMAT] --replace [DATASET].[TABLE] [PATH_TO_SOURCE]

où :

  • [LOCATION] correspond à votre emplacement. Cet indicateur --location est facultatif. Par exemple, si vous utilisez BigQuery dans la région de Tokyo, définissez la valeur de l'indicateur sur asia-northeast1. Vous pouvez définir une valeur par défaut pour l'emplacement en utilisant le fichier .bigqueryrc.
  • [FORMAT] est DATASTORE_BACKUP.
  • [DATASET] est l'ensemble de données contenant la table dans laquelle vous chargez les données.
  • [TABLE] est la table que vous écrasez.
  • [PATH_TO_SOURCE] est l'URI Cloud Storage.

Par exemple, la commande suivante charge le fichier d'exportation Cloud Datastore gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata et écrase une table nommée book_data :

bq load --source_format=DATASTORE_BACKUP --replace mydataset.book_data gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Définissez les propriétés suivantes pour charger des données à partir de l'API.

  1. Créez une tâche de chargement qui pointe vers les données sources dans Cloud Storage.

  2. Spécifiez votre emplacement dans la propriété location de la section jobReference de la ressource de tâche.

  3. Les URI sources doivent être complets et doivent respecter le format gs://[BUCKET]/[OBJECT]. Le nom du fichier (objet) doit se terminer par [KIND_NAME].export_metadata. Vous ne pouvez spécifier qu'un seul URI pour les exportations Cloud Datastore. En outre, celui-ci ne doit pas comporter de caractère générique.

  4. Spécifiez le format de données en définissant la propriété configuration.load.sourceFormat sur DATASTORE_BACKUP.

  5. Spécifiez la préférence d'écriture en définissant la propriété configuration.load.writeDisposition sur WRITE_TRUNCATE.

Options Cloud Datastore

Pour modifier la façon dont BigQuery analyse les données d'exportation Cloud Datastore, spécifiez des options supplémentaires dans l'interface utilisateur Web classique, l'interface de ligne de commande ou l'API.

Option CSV Option de l'UI classique Indicateur de la CLI Propriété de l'API BigQuery Description
Champs de projection Aucune --projection_fields projectionFields Liste séparée par des virgules indiquant les propriétés d'entité à charger dans BigQuery à partir d'une exportation Cloud Datastore. Les noms de propriété sont sensibles à la casse et doivent être des propriétés de premier niveau. Si aucune propriété n'est spécifiée, BigQuery charge toutes les propriétés. Si une propriété nommée est introuvable dans l'exportation Cloud Datastore, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est ".
Nombre d'enregistrements incorrects autorisés Nombre d'erreurs autorisées --max_bad_records maxBadRecords (Facultatif) Nombre maximal d'enregistrements incorrects pouvant être ignorés par BigQuery lors de l'exécution de la tâche. Si le nombre d'enregistrements incorrects dépasse cette valeur, une erreur "non valide" est renvoyée dans le résultat de la tâche. La valeur par défaut est 0, ce qui nécessite que tous les enregistrements soient valides.

Conversion des types de données

BigQuery convertit les données de chaque entité des fichiers d'exportation Cloud Datastore en types de données BigQuery. Le tableau suivant décrit la conversion entre les types de données.

Type de données Cloud Datastore Type de données BigQuery
Blob BigQuery ignore ces valeurs lors du chargement des données.
Clé blobstore STRING
Booléen BOOLEAN
Catégorie STRING
Clé Datastore RECORD
Date et heure TIMESTAMP
Adresse e-mail STRING
Entité intégrée RECORD
Nombre à virgule flottante FLOAT
Point géographique

RECORD


[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
        
IMHandle STRING
Entier INTEGER
Lien STRING
N° de téléphone STRING
Adresse postale STRING
Note INTEGER
Blob court BigQuery ignore ces valeurs lors du chargement des données.
Chaîne STRING (tronqué à 64 Ko)
Utilisateur

RECORD


[{"email","STRING"}
 {"userid","STRING"}]
        

Propriétés de la clé Datastore

Dans Cloud Datastore, chaque entité possède une clé unique contenant des informations telles que l'espace de noms et le chemin d'accès. BigQuery crée un type de données RECORD pour la clé, avec des champs imbriqués pour chaque information, comme décrit dans le tableau suivant.

Propriété de la clé Description Type de données BigQuery
__key__.app Nom de l'application Cloud Datastore. STRING
__key__.id ID de l'entité, ou null si __key__.name est défini. INTEGER
__key__.kind Genre de l'entité. STRING
__key__.name Nom de l'entité, ou null si __key__.id est défini. STRING
__key__.namespace Si l'application Cloud Datastore utilise un espace de noms personnalisé, espace de noms de l'entité. Sinon, l'espace de noms par défaut est représenté par une chaîne vide. STRING
__key__.path Chemin ancestral aplati de l'entité, constitué de la séquence de paires genre-identifiant de l'entité racine à l'entité elle-même. Par exemple : "Country", "USA", "PostalCode", 10011, "Route", 1234. STRING
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.