Planifier des scripts et des notebooks SQL

Attention :L'exploration Dataplex est obsolète et ne sera plus pris en charge à compter du 1er juillet 2025. Nous vous recommandons de convertir vos composants BigQuery Studio pour simplifier l'exploration des données dans tous les outils d'analyse de Google Cloud. Consultez la section Migrer d'Explore vers BigQuery Studio.

La planification de scripts et de notebooks SQL vous permet d'opérationnaliser les ressources que vous avez créée dans l'atelier de travail "Exploration de données" (Explorer).

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

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 du script SQL, puis mettez à jour son contenu, la mise à jour est également reflétée dans le des exécutions planifiées du notebook ou du script SQL.

Coûts

Les scripts SQL programmés et les notebooks programmés déclenchent l'exécution des jobs à l'aide de Dataproc sans serveur. L'utilisation est facturée en fonction du modèle de tarification et des frais appliqués à Dataproc. apparaissent sous "Dataproc" au lieu de "Dataplex".

Avant de commencer

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

• Section Avant de commencer de Utiliser l'outil d'exploration de données

• La section Avant de commencer de l'article Planifier des tâches Spark et SparkSQL personnalisées

  Remarque : Les instructions concernant le compte de service de tâche décrites dans Planifier des tâches Spark et SparkSQL personnalisées s'appliquent aux scripts SQL et aux notebooks, ainsi qu'au compte de service utilisé pour planifier les scripts SQL et les notebooks.
  
  Instructions d'activation de l'accès privé à Google décrits dans Planifier des tâches Spark et SparkSQL personnalisées se rapportent au réseau utilisé pour planifier les scripts et les notebooks SQL. Vous ne pouvez utiliser que le sous-réseau par défaut lorsque vous planifiez un script SQL ou un notebook à l'aide de la console Google Cloud. Pour en savoir plus, consultez la section Limites connues.

Si un script SQL ou une programmation de notebook utilisent l'API BigQuery, vous devez accorder le rôle Consommateur d'utilisation du service (roles/serviceusage.serviceUsageConsumer).

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 au moment de l'exécution pour le notebook planifié. Pour les rendre disponibles au moment de l'exécution, vous devez créer une planification de notebook référençant une image de conteneur avec les packages supplémentaires requis. Pour en savoir plus, consultez Planifier des notebooks avec des packages personnalisés.

• Utiliser la console Google Cloud pour référencer un conteneur personnalisé lorsque la planification de notebooks n'est pas prise en charge. Utilisez plutôt la 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 planification avec de nouveaux paramètres.

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

• Lorsque vous planifiez des scripts et des 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 un sous-réseau, utilisez la CLI gcloud.

Consultez également les limites connues de l'exploration.

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 de la tâche 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 des tâches de script SQL planifiées
Taille du disque principal	Image du conteneur / Propriétés: spark.dataproc.driver.disk.size spark.dataproc.executor.disk.size
Nombre de nœuds	Nombre de lots / exécuteurs
Nombre maximal de nœuds	Nombre de lots/Nombre maximal d'exécuteurs
Version de l'image	Non hérité
Fichiers JAR	Image du conteneur / JARS Java
Packages Python	Non hérités
Propriétés supplémentaires	Image de 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 Explorer

2. Sélectionnez un script SQL que vous souhaitez planifier, soit en sélectionnant un seul à partir de la liste Scripts SQL Spark ou en ouvrant un script SQL dans l'éditeur SQL Spark.

3. Dans le menu Programmation, cliquez sur Créer un calendrier.

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

5. Dans la section Schedule Options (Options de programmation), indiquez si vous souhaitez exécuter le script SQL. une seule fois ou de façon 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 et l'heure de début.

   2. Si vous sélectionnez Répéter, indiquez si vous souhaitez exécuter le script SQL une fois par jour, par semaine mensuellement, ou selon un calendrier personnalisé spécifié à l'aide d'une expression Cron. En outre, spécifier la date de début et l'heure d'exécution de l'exécution planifiée initiale.

6. Dans la section 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 du 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 de scripts SQL à l'aide de la gcloud CLI, consultez la page Planifier une tâche SparkSQL.

Remarque : Dans la section Planifier une tâche SparkSQL, la description du paramètre --spark-sql-script-file indique que la valeur de ce paramètre peut être l'URI de Cloud Storage. Cela n'est pas pris en charge. Vous ne devez spécifier que le chemin d'accès au contenu d'un script SQL pour le paramètre --spark-sql-script-file.

REST

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

Remarque :Dans la documentation de référence REST, la description de SparkTaskConfig indique que la valeur du champ sqlScriptFile peut être l'URI de Cloud Storage. Cela n'est pas pris en charge. Vous ne devez spécifier que le chemin d'accès au contenu d'un script SQL pour le champ sqlScriptFile.

Gérer les planifications des scripts SQL

Console

Ouvrir la liste de tous les plannings de script 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 programmations de scripts SQL.

Ouvrir la liste de tous les plannings d'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 Planning, cliquez sur Afficher les calendriers.

   L'onglet Requêtes programmées s'ouvre avec une liste de planifications de scripts SQL filtrées. par le script SQL sélectionné.

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

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

2. Cliquez sur l'onglet Details (Détails) pour afficher les détails de la planification du script SQL et 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 planifié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 planifié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 la planification d'un script SQL

1. Accédez à l'onglet Requêtes programmées et sélectionnez la programmation SQL requise.

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

3. Cliquez sur Afficher les journaux pour afficher les journaux associés à l'exécution du script SQL planifié sélectionné dans Cloud Logging.

4. Cliquez sur l'ID de 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é Résultat pour ouvrir la page Cloud Storage. dans la console Google Cloud. Accéder aux détails de l'espace de stockage Cloud Storage correspondant bucket contenant le résultat de l'exécution du script SQL.

gcloud

Pour en savoir plus sur la surveillance des scripts SQL planifiés à l'aide de la gcloud CLI, consultez l'onglet gcloud dans 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 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 programmés à l'aide de REST, consultez l'onglet REST dans Gérer la planification.

Résultat d'un script SQL planifié

La sortie de chaque exécution d'un script SQL planifié est stockée à l'emplacement que vous avez spécifié pour le dossier Cloud Storage, selon 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 les notebooks

Configuration de l'environnement d'exécution pour les notebooks programmé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 la tâche 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 de la tâche de notebook planifiée
Taille du disque principal	Image du conteneur / Propriétés: spark.dataproc.driver.disk.size spark.dataproc.executor.disk.size
Nombre de nœuds	Nombre de lots / exécuteurs
Nombre maximal de nœuds	Nombre de lots/Nombre maximal d'exécuteurs
Version de l'image	Non hérité
Fichiers JAR	Image du conteneur / JARS Java
Packages Python	Non hérités
Propriétés supplémentaires	Image du conteneur / Propriétés

Remarque : Lorsqu'un notebook est planifié, les paramètres de tâche Dataplex correspondants sont définis en fonction de la configuration d'environnement d'origine. Modifier les paramètres de l'environnement de notebook d'origine n'a aucune incidence sur la configuration de la tâche Dataplex correspondante.

Programmer 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 de 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é, et l'environnement d'exécution par défaut ne comporte que les composants de la version d'exécution Spark de Dataproc sans serveur 1.0. 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ée avec les packages personnalisés nécessaires.

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

Si vous planifiez un notebook avec un environnement avec des packages personnalisés configurés, vous obtenez l'avertissement suivant:

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 créer une image de conteneur pour les notebooks planifiés et installer les packages Python personnalisés requis dans le fichier Dockerfile de l'image de conteneur, consultez la section Créer une image de conteneur personnalisée pour Dataproc Serverless for Spark.

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

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

Remarque :Les packages, à l'exception de google-auth, ipykernel et papermill, sont présents dans l'exemple de fichier Docker. décrit dans la section Créer une image de conteneur personnalisée pour Dataproc sans serveur pour Spark.

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

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

2. Ajoutez les lignes suivantes après l'étape d'installation des packages conda :

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

Planifier un notebook

Console

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

   Accéder à l'exploration Dataplex

2. Sélectionnez un notebook que vous souhaitez planifier, soit en sélectionnant un seul notebook dans la vue Notebooks ou en ouvrant un notebook dans sa page d'informations.

3. Dans le menu Programmation, cliquez sur Créer un calendrier.

4. Dans le champ Nom de la planification, saisissez un nom pour l'instance programmé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 souhaitez 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 et l'heure de début.

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

6. Dans la section Destination des résultats, choisissez l'emplacement où vous souhaitez stocker la sortie du notebook :

   1. Dans le champ Nom du dossier de sortie, cliquez sur Parcourir et sélectionnez un dossier du bucket Cloud Storage dans lequel vous que la sortie du notebook soit stockée.

   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 planifié, 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 la gcloud CLI décrite dans Planifier une tâche Spark (Java ou Python) avec les paramètres supplémentaires suivants :

Paramètre	Description
--notebook	Chemin d'accès au contenu du 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 s'agit mentionné que la valeur du paramètre --notebook peut être l'URI Cloud Storage de le fichier notebook. Cette fonctionnalité n'est pas disponible. Vous ne devez spécifier que le chemin d'accès au notebook Contenu du 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 Cloud Storage des fichiers à placer dans le répertoire de travail de chaque exécuteur.
Ressources de calcul requises 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 des images de conteneurs
--notebook-container-image	Facultatif : image de conteneur personnalisée pour le job.
--notebook-container-image-java-jars	Liste de fichiers JAR Java à ajouter au chemin de classe. Les entrées valides incluent les URI Cloud Storage vers des binaires JAR. Par exemple, gs://BUCKET_NAME/my/path/to/file.jar.
--notebook-container-image-properties	Propriétés à définir sur les fichiers de configuration du 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 la section Propriétés du cluster.
Réseau VPC Google Cloud utilisé pour exécuter l'infrastructure
--notebook-vpc-network-tags	Liste des tags réseau à appliquer à la tâche.
Identifiant du réseau VPC Cloud. Vous ne pouvez spécifier qu'un seul des éléments suivants.
--notebook-vpc-network-name	Réseau VPC Cloud dans lequel le job s'exécute. Par défaut, le réseau VPC Cloud nommé La valeur par défaut dans le projet est utilisée.
--notebook-vpc-sub-network-name	Sous-réseau VPC Cloud dans lequel l'ordre s'exécute.
Emplacement des sorties du notebook
--execution-args	Pour les tâches de notebook, l'argument suivant est obligatoire 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 programmer 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=[e-mail]  --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.

Remarque :Dans la documentation de référence REST, la description de la ressource NotebookTaskConfig indique que la valeur du champ notebook peut être l'URI de Cloud Storage. Cette fonctionnalité n'est pas disponible. Vous ne devez spécifier que le chemin d'accès au contenu d'un notebook pour le paramètre notebook.

Gérer les planifications des notebooks

Console

Ouvrir la liste de toutes les planifications de notebook

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

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

Ouvrir la liste de toutes les planifications pour 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 Planning, cliquez sur Afficher les calendriers.

   L'onglet Requêtes programmées s'ouvre et affiche la liste des planifications de notebooks filtrées. par le notebook sélectionné.

Afficher les détails d'une planification de notebook

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

2. Cliquez sur Détails pour afficher les détails de la planification du notebook et un aperçu de son contenu.

Activer et désactiver une programmation de notebook

1. Accédez à l'onglet Notebook planifié, puis sélectionnez le calendrier de notebook requis.

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

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

Supprimer une programmation de notebook existante

1. Accédez à l'onglet Notebook planifié, puis sélectionnez le calendrier de notebook requis.

2. Cliquez sur Supprimer pour supprimer définitivement un calendrier de notebook existant.

Afficher les journaux et gérer la planification d'un notebook

1. Accédez à l'onglet Notebook planifié, puis sélectionnez le calendrier de notebook requis.

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

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

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

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

6. Cliquez sur Gérer dans Cloud Storage à côté de l'étiquette 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 de l'exécution du notebook.

gcloud

Pour en savoir plus sur la surveillance des notebooks programmés à l'aide de la gcloud CLI, consultez l'onglet gcloud dans Surveiller vos tâches.

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

REST

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

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

Résultat d'un notebook programmé

La sortie de chaque exécution d'un notebook planifié est stockée à l'emplacement spécifié par vous pour le dossier Cloud Storage, selon la structure suivante :

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

Étape suivante

• Planifiez des tâches Spark et SparkSQL personnalisées.
• Configurez des alertes et des notifications pour les tâches Dataplex.