Programmer des scripts et des notebooks SQL

La planification de scripts et de notebooks SQL vous permet d'opérationnaliser les éléments créés dans Data Exploration Workbench (Explorer).

La planification d'un script SQL ou d'un notebook crée une tâche Dataplex qui s'exécute à un moment prédéterminé, une fois ou de manière récurrente. À chaque exécution, une tâche est créée qui capture les métadonnées d'exécution, telles que l'heure de début et de fin d'exécution, l'état d'exécution, les journaux et les sorties générées.

Lorsqu'une exécution est déclenchée pour un script SQL planifié ou un notebook, la version actuelle du notebook ou du script SQL est exécutée. Cela signifie que si vous planifiez un notebook ou un script SQL, puis mettez à jour son contenu, la mise à jour est également reflétée dans les exécutions programmées du notebook ou du script SQL.

Coûts

Les scripts SQL planifiés et les notebooks planifiés déclenchent l'exécution de la tâche à l'aide de Dataproc sans serveur. Les utilisations sont facturées conformément au modèle de tarification Dataproc, et les frais apparaissent sous Dataproc au lieu de Dataplex.

Avant de commencer

Consultez et remplissez les conditions préalables décrites dans les documents suivants:

Si un script SQL ou un calendrier de notebook utilise l'API BigQuery, vous devez attribuer le rôle Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer) au compte de service.

Limitations connues

  • Lorsque vous planifiez un notebook à l'aide de la console Google Cloud, les packages Python supplémentaires configurés dans l'environnement sélectionné ne sont pas disponibles lors de l'exécution du notebook planifié. Pour les rendre disponibles au moment de l'exécution, vous devez créer une planification de notebook faisant référence à une image de conteneur avec les packages supplémentaires requis. Pour en savoir plus, consultez Planifier des notebooks avec des packages personnalisés.

  • Il n'est pas possible d'utiliser la console Google Cloud pour référencer des images de conteneurs personnalisées lors de la planification des notebooks. Utilisez plutôt gcloud CLI.

  • Une fois la planification créée, vous ne pouvez plus la modifier. Pour mettre à jour les paramètres de planification, vous devez recréer la programmation avec de nouveaux paramètres.

  • Vous ne pouvez pas définir une version spécifique d'un script SQL ou d'un notebook à utiliser dans une planification. Lorsque la planification est déclenchée, la version actuelle du script SQL ou du notebook est utilisée.

  • Lors de la planification de scripts et de notebooks SQL à l'aide de la console Google Cloud, le sous-réseau par défaut est utilisé. Pour spécifier un autre réseau ou sous-réseau, utilisez gcloud CLI.

Consultez également les limites connues d'Explorer.

Créer et gérer des planifications pour des scripts SQL

Configuration de l'environnement d'exécution pour les scripts SQL planifiés

Lorsqu'un script SQL est planifié, il s'exécute en tant que tâche Dataplex. Lorsqu'une planification est créée à l'aide de la console Google Cloud, les paramètres d'exécution correspondants pour les scripts SQL planifiés sont hérités de l'environnement de ce script SQL en fonction du mappage suivant:

Paramètre de configuration de l'environnement Paramètre de configuration d'une tâche de script SQL programmée
Taille du disque principal Image / Propriétés du conteneur:
   spark.dataproc.driver.disk.size
   spark.dataproc.executor.disk.size
Nombre de nœuds Nombre d'exécuteurs / par lot
Nombre maximal de nœuds Nombre d'exécuteurs / nombre maximal d'exécuteurs
Version de l'image Non héritée
Fichiers JAR Image du conteneur / JARS Java
Packages Python Non héritée
Propriétés supplémentaires Image du conteneur / Propriétés

Planifier un script SQL

Console

  1. Dans la console Google Cloud, accédez à la page Explorer de Dataplex.

    Accéder à Dataplex

  2. Sélectionnez le script SQL que vous souhaitez planifier. Pour ce faire, sélectionnez un seul script SQL dans la liste Scripts SQL Spark ou ouvrez un script SQL dans l'éditeur SQL Spark.

  3. Dans le menu Programmation, cliquez sur Créer une planification.

  4. Dans le champ Nom de la planification, saisissez le nom de l'instance planifiée.

  5. Dans la section Options de programmation, indiquez si vous souhaitez exécuter le script SQL
    une seule fois ou de manière récurrente:

    1. Si vous sélectionnez Exécuter une fois, indiquez si vous souhaitez exécuter le script SQL immédiatement ou à une heure planifiée, à l'aide des options du menu Démarrer. Pour une exécution planifiée, spécifiez la date de début et l'heure d'exécution.

    2. Si vous sélectionnez Répéter, indiquez si vous souhaitez exécuter le script SQL tous les jours, toutes les semaines, tous les mois ou une planification personnalisée spécifiée à l'aide d'une expression Cron. Spécifiez également la date de début et l'heure d'exécution de l'exécution planifiée initiale.

  6. Dans la section Destination for results (Destination des résultats), procédez comme suit:

    1. Dans le champ Nom du dossier de sortie, cliquez sur Parcourir, puis sélectionnez un dossier dans un bucket Cloud Storage dans lequel vous souhaitez stocker les résultats de script.

    2. Cliquez sur Sélectionner.

    3. Sélectionnez le format de sortie du script. Les formats acceptés sont CSV, JSON, ORC et Parquet.

  7. Dans la section Identifiants du script planifié, sélectionnez un compte de service dans le menu Compte de service utilisateur.

  8. Cliquez sur Schedule (Programmer).

gcloud

Pour en savoir plus sur la planification des scripts SQL à l'aide de gcloud CLI, consultez Planifier une tâche SparkSQL.

REST

Utilisez APIs Explorer pour créer une tâche.

Gérer les planifications de scripts SQL

Console

Ouvrir la liste des planifications de scripts SQL

  1. Dans la console Google Cloud, accédez à la page Processus de Dataplex.

  2. Cliquez sur l'onglet Requêtes programmées pour afficher la liste des planifications de scripts SQL.

Ouvrir la liste de toutes les planifications pour un script SQL spécifique

  1. Dans la console Google Cloud, accédez à la page Explorer de Dataplex.

  2. Sélectionnez le script SQL requis.

  3. Dans le menu Programmation, cliquez sur Afficher les programmations.

    L'onglet Requêtes programmées s'ouvre avec la liste des planifications de scripts SQL filtrées en fonction du script SQL sélectionné.

Afficher les détails d'une planification de script SQL

  1. Accédez à l'onglet Requêtes programmées, puis sélectionnez la planification de script SQL requise.

  2. Cliquez sur l'onglet Détails pour afficher les détails de la planification du script SQL et obtenir un aperçu du contenu du script SQL planifié.

Activer et désactiver une planification de script SQL

  1. Accédez à l'onglet Requêtes programmées, puis sélectionnez la planification de script SQL requise.

  2. Cliquez sur Désactiver pour désactiver une planification de script SQL active.

  3. Cliquez sur Activer pour activer une planification de script SQL inactive.

Supprimer une planification de script SQL existante

  1. Accédez à l'onglet Requêtes programmées, puis sélectionnez la planification de script SQL requise.

  2. Cliquez sur Supprimer pour supprimer définitivement une planification de script SQL existante.

Afficher les journaux et gérer une planification de scripts SQL

  1. Accédez à l'onglet Requêtes programmées, puis sélectionnez la planification de script SQL requise.

  2. Cliquez sur l'onglet Tâches, puis sur l'ID de tâche de l'exécution de script SQL planifié que vous souhaitez afficher.

  3. Cliquez sur Afficher les journaux pour afficher les journaux liés au script SQL planifié sélectionné qui est exécuté dans Cloud Logging.

  4. Cliquez sur l'ID du lot Dataproc pour ouvrir la page "Dataproc" dans la console Google Cloud. Accédez aux détails de la session Dataproc sans serveur correspondante.

  5. Cliquez sur Gérer dans Cloud Storage à côté du libellé Sortie pour ouvrir la page Cloud Storage dans la console Google Cloud. Accédez aux détails du bucket Cloud Storage correspondant contenant la sortie d'exécution du script SQL.

gcloud

Pour en savoir plus sur la surveillance des scripts SQL planifiés à l'aide de gcloud CLI, consultez l'onglet gcloud de la section Surveiller votre tâche.

Pour en savoir plus sur la gestion des scripts SQL planifiés à l'aide de gcloud CLI, consultez l'onglet gcloud dans la section Gérer la planification.

REST

Pour en savoir plus sur la surveillance des scripts SQL planifiés à l'aide de REST, consultez l'onglet REST dans Surveiller votre tâche.

Pour en savoir plus sur la gestion des scripts SQL planifiés à l'aide de REST, consultez l'onglet REST dans Gérer la planification.

Résultat d'un script SQL planifié

Le résultat de chaque exécution d'un script SQL planifié est stocké à l'emplacement que vous avez spécifié pour le dossier Cloud Storage, dans la structure suivante:

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

Créer et gérer des planifications pour des notebooks

Configuration de l'environnement d'exécution pour les notebooks planifiés

Lorsqu'un notebook est planifié, il s'exécute en tant que tâche Dataplex. Lorsqu'une planification est créée à l'aide de la console Google Cloud, les paramètres d'exécution de tâches correspondants pour les notebooks planifiés sont hérités de l'environnement de ce notebook en fonction du mappage suivant:

Paramètre de configuration de l'environnement Paramètre de configuration des tâches planifiées pour notebook
Taille du disque principal Image / Propriétés du conteneur:
   spark.dataproc.driver.disk.size
   spark.dataproc.executor.disk.size
Nombre de nœuds Nombre d'exécuteurs / par lot
Nombre maximal de nœuds Nombre d'exécuteurs / nombre maximal d'exécuteurs
Version de l'image Non héritée
Fichiers JAR Image du conteneur / JARS Java
Packages Python Non héritée
Propriétés supplémentaires Image du conteneur / Propriétés

Planifier des notebooks avec des packages personnalisés

Pour les notebooks interactifs, lors de la configuration d'un environnement, Dataplex vous permet de spécifier des packages Python personnalisés à installer dans les sessions utilisateur provisionnées pour l'environnement. Lorsqu'un tel notebook est planifié, les packages Python personnalisés configurés dans son environnement ne sont pas disponibles au moment de l'exécution pour le notebook planifié. L'environnement d'exécution par défaut ne comprend que les composants de la version 1.0 de l'environnement d'exécution Spark sans serveur Dataproc. Pour que les packages Python personnalisés soient disponibles au moment de l'exécution pour les notebooks planifiés, fournissez une image de conteneur personnalisé avec les packages personnalisés nécessaires.

Il n'est pas possible de spécifier une image de conteneur personnalisée lors de la planification d'un notebook à l'aide de la console Google Cloud. Utilisez plutôt gcloud CLI. Pour en savoir plus, consultez la section Planifier un notebook.

Si vous planifiez un notebook avec un environnement dans lequel des packages personnalisés sont configurés, l'avertissement suivant s'affiche:

Selected environment  has additional Python packages configured.
These packages will not be available in the default runtime for the scheduled notebook
when scheduling in the Console. To make the required additional Python packages
available in the runtime, please create Notebook Schedule using gcloud command
instead, referencing a container image with required additional packages.

Créer une image de conteneur personnalisée pour les notebooks planifiés

Pour savoir comment établir une image de conteneur pour les notebooks planifiés et installer les packages Python personnalisés requis dans le fichier Docker de l'image de conteneur, consultez la section Créer une image de conteneur personnalisée pour Dataproc sans serveur pour Spark.

Assurez-vous d'avoir installé les packages Conda suivants dans l'image de conteneur:

  • gcsfs
  • google-cloud-bigquery
  • google-cloud-storage
  • google-auth
  • ipykernel
  • papermill

Pour installer les composants gcloud dans une image de conteneur, ouvrez le fichier Docker de l'image de conteneur et procédez comme suit:

  1. Ajoutez le package google-cloud-sdk à la liste des packages conda à installer.

  2. Après les étapes d'installation des packages Conda, ajoutez les lignes suivantes:

    # (Optional) Installing gcloud components
RUN gcloud components install alpha beta bq gsutil

Planifier un notebook

Console

  1. Dans la console Google Cloud, accédez à la page Explorer de Dataplex.

    Accéder à Dataplex

  2. Sélectionnez le notebook que vous souhaitez planifier. Pour ce faire, sélectionnez un seul notebook dans la vue Notebooks ou ouvrez la page de détails du notebook.

  3. Dans le menu Programmation, cliquez sur Créer une planification.

  4. Dans le champ Nom de la planification, saisissez le nom de l'instance planifiée.

  5. Dans la section Options de planification, indiquez si vous souhaitez exécuter le notebook une seule fois ou de manière récurrente:

    1. Si vous sélectionnez Exécuter une fois, indiquez si vous voulez exécuter le notebook immédiatement ou à une heure planifiée, à l'aide des options du menu Démarrer. Pour une exécution planifiée, spécifiez la date de début et l'heure d'exécution.

    2. Si vous sélectionnez Repeat (Répéter), indiquez si vous souhaitez exécuter le notebook tous les jours, toutes les semaines, tous les mois ou selon un calendrier personnalisé spécifié à l'aide de l'expression Cron. Indiquez également la date et l'heure de début de l'exécution planifiée initiale.

  6. Dans la section Destination for results (Destination des résultats), choisissez un emplacement où stocker la sortie du notebook:

    1. Dans le champ Nom du dossier de sortie, cliquez sur Parcourir, puis sélectionnez un dossier dans un bucket Cloud Storage dans lequel stocker la sortie du notebook.

    2. Cliquez sur Sélectionner.

    3. Sélectionnez le format de sortie du script. Les formats acceptés sont CSV, JSON, ORC et Parquet.

  7. Dans la section Identifiants du notebook programmé, sélectionnez un compte de service dans le menu Compte de service utilisateur.

  8. Dans la section Paramètres, ajoutez des paramètres d'exécution pour le notebook en tant que paires clé/valeur en cliquant sur Ajouter.

  9. Cliquez sur Schedule (Programmer).

gcloud

Exécutez la commande de gcloud CLI décrite dans la section Planifier une tâche Spark (Java ou Python) avec les paramètres supplémentaires suivants:

Paramètre Description
--notebook Chemin d'accès à un contenu de notebook pour le notebook d'entrée. Les arguments d'exécution sont accessibles en tant que variables d'environnement. Par exemple, TASK_key=value.
Remarque: : Dans la documentation de référence gcloud sur la planification des notebooks en tant que tâches, il est indiqué que la valeur du paramètre --notebook peut être l'URI Cloud Storage du fichier notebook. Cela n'est pas possible. Vous ne devez spécifier le chemin d'accès au contenu du notebook que pour le paramètre --notebook.
--notebook-archive-uris URI Cloud Storage des archives à extraire dans le répertoire de travail de chaque exécuteur. Les types de fichiers compatibles sont JAR, tar, tar.gz, tgz et zip.
--notebook-file-uris URI Google Cloud Storage des fichiers à placer dans le répertoire de travail de chaque exécuteur.
Ressources de calcul nécessaires pour une tâche lorsque vous utilisez Dataproc sans serveur
--notebook-batch-executors-count Nombre d'exécuteurs de tâches.
--notebook-batch-max-executors-count Nombre maximal d'exécuteurs configurables.
Si notebook-batch-max-executors-count est supérieur à notebook-batch-executors-count, l'autoscaling est activé.
Configuration de l'environnement d'exécution de l'image de conteneur
--notebook-container-image Facultatif: Image de conteneur personnalisé pour la tâche
--notebook-container-image-java-jars Liste de fichiers JAR Java à ajouter au classpath. Une entrée valide inclut les URI Cloud Storage des binaires JAR. Exemple : gs://BUCKET_NAME/my/path/to/file.jar.
--notebook-container-image-properties Propriétés à définir sur les fichiers de configuration daemon
Les clés de propriété sont spécifiées au format prefix:property. Par exemple:
core:hadoop.tmp.dir.
Pour en savoir plus, consultez Propriétés du cluster.
Réseau VPC Cloud utilisé pour exécuter l'infrastructure
--notebook-vpc-network-tags Liste des tags réseau à appliquer à la tâche.
Identifiant de réseau Cloud VPC. Vous pouvez spécifier un maximum de ce qui suit.
--notebook-vpc-network-name Réseau VPC Cloud dans lequel la tâche s'exécute. Le réseau VPC Cloud par défaut du projet est utilisé par défaut.
--notebook-vpc-sub-network-name Sous-réseau Cloud VPC dans lequel la tâche s'exécute.
Emplacement des sorties du notebook
--execution-args Pour les tâches de notebook, l'argument suivant est obligatoire et doit être transmis en tant que TASK_ARGS.
--execution-args=^::^TASK_ARGS="--output_location,CLOUD_STORAGE_URI_OF_OUTPUT_DIRECTORY"

Voici un exemple de commande gcloud utilisée pour planifier des notebooks: 

gcloud dataplex tasks create sample-task --project=sample-project --location=us-central1 --lake=my-lake --trigger-type=ON_DEMAND --notebook="projects/my-project-id/locations/us-central1/lakes/my-lake/content/my-notebook.ipynb" --execution-service-account=associated-service-account@sample-project.iam.gserviceaccount.com  --execution-args=^::^TASK_ARGS="--output_location,gs://my-bucket/Demo" --notebook-batch-executors-count=2 --notebook-batch-max-executors-count=5 --notebook-container-image=container-image --notebook-container-image-java-jars=java-jar1,java-jar-2

REST

Utilisez APIs Explorer pour créer une tâche.

Gérer les planifications de notebooks

Console

Ouvrir la liste de toutes les planifications de notebooks

  1. Dans la console Google Cloud, accédez à la page Processus de Dataplex.

  2. Cliquez sur l'onglet Notebooks programmés pour afficher la liste des planifications de scripts SQL.

Ouvrir la liste de toutes les planifications d'un notebook spécifique

  1. Dans la console Google Cloud, accédez à la page Explorer de Dataplex.

  2. Sélectionnez le notebook requis.

  3. Dans le menu Programmation, cliquez sur Afficher les programmations.

    L'onglet Requêtes programmées affiche la liste des planifications de notebooks filtrées en fonction du notebook sélectionné.

Afficher les détails d'une planification de notebook

  1. Accédez à l'onglet Notebooks programmés, puis sélectionnez la planification de notebooks requise.

  2. Cliquez sur Détails du calendrier du notebook et afficher un aperçu du contenu du notebook planifié.

Activer et désactiver une planification de notebook

  1. Accédez à l'onglet Notebook planifié, puis sélectionnez la planification de notebooks requise.

  2. Cliquez sur Désactiver pour désactiver une planification de notebook active.

  3. Cliquez sur Activer pour activer une planification de notebook inactive.

Supprimer une planification de notebooks existante

  1. Accédez à l'onglet Notebook planifié, puis sélectionnez la planification de notebooks requise.

  2. Cliquez sur Supprimer pour supprimer définitivement une planification de notebook existante.

Afficher les journaux et gérer une planification de notebook

  1. Accédez à l'onglet Notebook planifié, puis sélectionnez la planification de notebooks requise.

  2. Cliquez sur l'onglet Jobs, puis sur l'ID de tâche de l'exécution planifiée du notebook que vous souhaitez afficher.

  3. Dans la section Aperçu de la sortie, examinez la sortie de l'exécution du notebook.

  4. Cliquez sur Afficher les journaux pour afficher les journaux liés à l'exécution du notebook planifié sélectionné dans Cloud Logging.

  5. Cliquez sur l'ID du lot Dataproc pour ouvrir la page "Dataproc" dans la console Google Cloud. Accédez aux détails de la session Dataproc sans serveur correspondante.

  6. Cliquez sur Gérer dans Cloud Storage à côté du libellé Résultat pour ouvrir la page Cloud Storage dans la console Google Cloud. Accédez aux détails du bucket Cloud Storage correspondant contenant la sortie d'exécution du notebook.

gcloud

Pour en savoir plus sur la surveillance des notebooks planifiés à l'aide de gcloud CLI, consultez l'onglet gcloud de la section Surveiller votre tâche.

Pour en savoir plus sur la gestion des notebooks planifiés à l'aide de gcloud CLI, consultez l'onglet gcloud de la page Gérer la planification.

REST

Pour en savoir plus sur la surveillance des notebooks planifiés à l'aide de REST, consultez l'onglet REST de la page Monitor your task (Surveiller votre tâche).

Pour en savoir plus sur la gestion des notebooks planifiés à l'aide de REST, consultez l'onglet REST de la page Gérer la planification.

Sortie d'un notebook planifié

Les résultats de chaque exécution d'un notebook planifié sont stockés à l'emplacement que vous avez spécifié pour le dossier Cloud Storage, dans la structure suivante:

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

Étapes suivantes