Programmer une exportation

Cette page explique comment planifier une exportation automatique d'entités Cloud Firestore en mode Datastore.

Pour planifier les exportations de vos entités, nous vous recommandons de déployer un service App Engine qui appelle la fonctionnalité d'exportation gérée du mode Datastore. Une fois déployé, ce service peut être exécuté selon un calendrier défini avec le service Cron d'App Engine.

Avant de commencer

Pour pouvoir planifier des exportations de données avec App Engine et la fonctionnalité d'exportation gérée, vous devez effectuer les tâches suivantes :

  1. Activer la facturation pour votre projet Google Cloud. Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser la fonctionnalité d'exportation et d'importation.

  2. Créez un bucket Cloud Storage pour votre projet. Toutes les opérations d'exportation et d'importation gérées dépendent de Cloud Storage. Vous devez utiliser le même emplacement pour votre bucket Cloud Storage et votre base de données en mode Datastore.

    Pour trouver l'emplacement de votre base de données en mode Datastore, consultez la page Afficher l'emplacement de votre projet.

  3. Installez le SDK Google Cloud pour déployer l'application.

Configurer des exportations planifiées

Une fois les conditions ci-dessus remplies, configurez les exportations planifiées en suivant les procédure décrites ci-dessous.

Configurer les autorisations d'accès

Cette application utilise le compte de service App Engine par défaut pour authentifier et autoriser ses requêtes d'exportation. Lorsque vous créez un projet, App Engine crée un compte de service par défaut au format suivant :

[PROJECT_ID]@appspot.gserviceaccount.com

Le compte de service requiert une autorisation pour démarrer les opérations d'exportation de la base de données en mode Datastore et pour écrire dans le bucket Cloud Storage. Pour accorder ces autorisations, attribuez les rôles IAM suivants au compte de service par défaut :

  • Datastore Import Export Admin
  • Storage Admin du bucket Cloud Storage

Vous pouvez utiliser les outils de ligne de commande gcloud et gsutil du SDK Cloud pour attribuer ces rôles :

  1. Utilisez l'outil de ligne de commande gcloud pour attribuer le rôle Administrateur d'exportation Cloud Datastore :

        gcloud projects add-iam-policy-binding [PROJECT_ID] \
            --member serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com \
            --role roles/datastore.importExportAdmin
        

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

  2. Utilisez l'outil de ligne de commande gsutil pour attribuer le rôle Administrateur de l'espace de stockage sur votre bucket :

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

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

Déployer l'application

Déployez l'exemple d'application suivant en Python ou en Java :

Python

Créer les fichiers de l'application

Dans un nouveau dossier sur votre machine de développement, créez les fichiers suivants, qui intègrent une application App Engine dans le code :

  • app.yaml
  • cloud_datastore_admin.py

Utilisez le code suivant pour les fichiers :

app.yaml

Le fichier suivant permet de configurer le déploiement de l'application :

runtime: python27
    api_version: 1
    threadsafe: true
    service: cloud-datastore-admin

    libraries:
    - name: webapp2
      version: "latest"

    handlers:
    - url: /cloud-datastore-export
      script: cloud_datastore_admin.app
      login: admin

    

La ligne service: cloud-datastore-admin déploie l'application vers le service cloud-datastore-admin. S'il s'agit du seul service App Engine de votre projet, supprimez cette ligne pour déployer l'application sur le service default.

cloud_datastore_admin.py

import datetime
    import httplib
    import json
    import logging
    import webapp2

    from google.appengine.api import app_identity
    from google.appengine.api import urlfetch

    class Export(webapp2.RequestHandler):

      def get(self):
        access_token, _ = app_identity.get_access_token(
            'https://www.googleapis.com/auth/datastore')
        app_id = app_identity.get_application_id()
        timestamp = datetime.datetime.now().strftime('%Y%m%d-%H%M%S')

        output_url_prefix = self.request.get('output_url_prefix')
        assert output_url_prefix and output_url_prefix.startswith('gs://')
        if '/' not in output_url_prefix[5:]:
          # Only a bucket name has been provided - no prefix or trailing slash
          output_url_prefix += '/' + timestamp
        else:
          output_url_prefix += timestamp

        entity_filter = {
            'kinds': self.request.get_all('kind'),
            'namespace_ids': self.request.get_all('namespace_id')
        }
        request = {
            'project_id': app_id,
            'output_url_prefix': output_url_prefix,
            'entity_filter': entity_filter
        }
        headers = {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + access_token
        }
        url = 'https://datastore.googleapis.com/v1/projects/%s:export' % app_id
        try:
          result = urlfetch.fetch(
              url=url,
              payload=json.dumps(request),
              method=urlfetch.POST,
              deadline=60,
              headers=headers)
          if result.status_code == httplib.OK:
            logging.info(result.content)
          elif result.status_code >= 500:
            logging.error(result.content)
          else:
            logging.warning(result.content)
          self.response.status_int = result.status_code
        except urlfetch.Error:
          logging.exception('Failed to initiate export.')
          self.response.status_int = httplib.INTERNAL_SERVER_ERROR

    app = webapp2.WSGIApplication(
        [
            ('/cloud-datastore-export', Export),
        ], debug=True)

    

Déployer l'application

  1. Assurez-vous que gcloud est configuré pour le bon projet :

    gcloud config set project [PROJECT_NAME]
        
  2. Dans le même répertoire que votre fichier app.yaml, déployez l'application dans votre projet :

    gcloud app deploy
        

Java

L'exemple d'application suivant suppose que vous avez configuré Maven avec le plugin App Engine.

Télécharger l'application

Téléchargez le dépôt java-docs-samples et accédez au répertoire de l'application datastore-schedule-export :

  1. Clonez le dépôt de l'exemple d'application sur votre machine locale :

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
        

    Vous pouvez également télécharger l'exemple sous forme de fichier ZIP et l'extraire.

  2. Accédez au répertoire qui contient l'exemple de code :

    cd java-docs-samples/appengine-java8/datastore-schedule-export/
        

L'application configure un servlet dans le fichier DatastoreExportServlet.java.

Déployer l'application sur un autre service

Si vous déployez l'application en l'état, elle est déployée sur le service default. Si vous disposez déjà d'un service default, vous devez plutôt la déployer sur un autre service.

Modifiez le fichier src/main/webapp/WEB-INF/appengine-web.xml en ajoutant <module>service_name</module>. Exemple :

   <?xml version="1.0" encoding="utf-8"?>
       <appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
          <runtime>java8</runtime>
          <!-- ... -->
          <module>cloud-datastore-admin</module>
          <!-- ... -->
       </appengine-web-app>
    

Pour en savoir plus sur le fichier de configuration de l'application, consultez la documentation de référence sur appengine-web.xml.

Déployer l'application

  1. Assurez-vous que gcloud est configuré pour le bon projet :

    gcloud config set project [PROJECT_NAME]
        
  2. Déployez l'application sur votre projet :

    mvn appengine:deploy
        

Le service reçoit les requêtes d'exportation à l'adresse [SERVICE_URL]/cloud-datastore-export et envoie une requête authentifiée à l'API Admin pour Cloud Datastore pour commencer l'exportation.

Le service utilise les paramètres d'URL suivants pour configurer la requête d'exportation :

  • output_url_prefix (obligatoire) : spécifie l'emplacement d'enregistrement de la base de données en mode Datastore à exporter. Si l'URL se termine par un signe "/", celui-ci est utilisé tel quel. Sinon, l'application ajoute un horodatage à l'URL.
  • kind (facultatif, multiple) : restreint l'exportation à ces genres.
  • namespace_id (facultatif, multiple) : limite l'exportation à ces espaces de noms.

Déployer la tâche Cron

Pour configurer une tâche Cron qui appelle l'application schedule-datastore-exports, créez et déployez un fichier cron.yaml.

  1. Créez un fichier cron.yaml :

    Python

    cron:
        - description: "Daily Cloud Datastore Export"
          url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]
          target: cloud-datastore-admin
          schedule: every 24 hours
        

    Si vous avez déployé l'application sur le service default plutôt que sur le service cloud-datastore-admin, supprimez target: cloud-datastore-admin.

    Java

    cron:
        - description: "Daily Cloud Datastore Export"
          url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]
          schedule: every 24 hours
        

    Si vous n'avez pas déployé l'application sur le service default, ajoutez une ligne cible au service. Exemple : target: cloud-datastore-admin.

    Remplacez [BUCKET_NAME] par le nom de votre bucket Cloud Storage.

  2. Configurez la tâche Cron. L'exemple cron.yaml lance une requête d'exportation de chaque entité toutes les 24 heures. Pour plus d'options de planification, consultez la section Format de planification.

    Pour n'exporter que des entités de genres spécifiques, ajoutez des paramètres kind à la valeur url. De même, ajoutez des paramètres namespace_id pour exporter des entités à partir d'espaces de noms spécifiques. Exemple :

    • Exporter les entités de genre Song :

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&kind=Song
          
    • Exporter les entités de genre Song et de genre Album :

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&kind=Song&kind=Album
          
    • Exporter les entités de genre Song et de genre Album si elles se trouvent dans l'espace de noms Classical ou dans l'espace de noms Pop :

      url: /cloud-datastore-export?output_url_prefix=gs://[BUCKET_NAME]&namespace_id=Classical&namespace_id=Pop&kind=Song&kind=Album
          
  3. Déployez la tâche Cron. Exécutez la commande suivante dans le même répertoire que votre fichier cron.yaml :

      gcloud app deploy cron.yaml
        

Tester l'application Cron

Pour tester votre tâche Cron déployée, exécutez la tâche Cron au début de la page Tâches Cron de Google Cloud Console :

  1. Ouvrez la page Tâches Cron dans Cloud Console.
    Ouvrir la page Tâches Cron

  2. Cliquez sur le bouton Exécuter correspondant à votre tâche Cron.

  3. Une fois la tâche terminée, vérifiez le message d'état dans la section Statut. Pour afficher le fichier journal de la tâche Cron, cliquez sur Afficher dans la colonne Journal.

Afficher les exportations

Une fois la tâche Cron terminée, vous pouvez afficher les exportations dans votre bucket Cloud Storage.

  1. Ouvrez le navigateur Cloud Storage dans Cloud Console.
    Ouvrir le navigateur Cloud Storage

  2. Dans la liste des buckets, cliquez sur le bucket que vous avez créé pour vos exportations.

  3. Vérifiez que les exportations sont bien répertoriées dans le bucket.

Étape suivante

  • Pour apprendre à importer des données à partir d'une exportation de base de données en mode Datastore, consultez Importer des entités.