Créer un pack manuellement

Dans ce tutoriel, vous allez créer des ressources Databricks regroupées à partir de zéro. Ce pack simple se compose de deux notebooks et de la définition d’un travail Azure Databricks pour exécuter ces notebooks. Ensuite, vous validez, déployez et exécutez le projet déployé dans votre espace de travail Databricks Azure. Ces étapes automatisent le démarrage rapide intitulé Créer votre premier flux de travail avec un travail Azure Databricks.

Spécifications

• Databricks CLI 0.218.0 ou une version ultérieure. Pour vérifier la version de Databricks CLI installée, exécutez la commande databricks -v. Pour installer l’interface CLI Databricks, consultez Installer ou mettre à jour l’interface CLI Databricks.
• Authentification configurée pour l’interface CLI Databricks. Consultez Authentification pour l’interface CLI Databricks.
• L’espace de travail Databricks distant doit disposer de fichiers d’espace de travail activés. Consultez l’article Que sont les fichiers d’espace de travail ?.

Étape 1 : créer le pack

Un pack contient les artefacts que vous souhaitez déployer et les paramètres des workflows que vous souhaitez exécuter.

1. Créez ou identifiez un répertoire vide sur votre ordinateur de développement.
2. Commutez vers l’annuaire vide de votre terminal ou ouvrez-le dans votre IDE.

Étape 2 : ajouter des notebooks au projet

Au cours de cette étape, vous ajoutez deux notebooks à votre projet. Le premier notebook obtient une liste des noms de bébé en vogue depuis 2007 provenant de sources de données publiques du Département de la Santé de l’État de New York. Voir Baby Names: Trending by Name: Beginning 2007 sur le site web du département. Le premier notebook enregistre ensuite ces données dans votre volume Azure Databricks Unity Catalog nommé my-volume dans un schéma nommé default dans un catalogue nommé main. Le deuxième notebook interroge les données enregistrées et affiche les nombres agrégés de noms de bébé par prénom et sexe pour 2014.

1. À partir de la racine du répertoire, créez le premier notebook, un fichier nommé retrieve-baby-names.py.

2. Ajoutez le code suivant au fichier retrieve-baby-names.py :

   # Databricks notebook source
   import requests
   
   response = requests.get('http://health.data.ny.gov/api/views/jxy9-yhdk/rows.csv')
   csvfile = response.content.decode('utf-8')
   dbutils.fs.put("/Volumes/main/default/my-volume/babynames.csv", csvfile, True)
   

3. Créez le deuxième notebook, un fichier nommé filter-baby-names.py, dans le même répertoire.

4. Ajoutez le code suivant au fichier filter-baby-names.py :

   # Databricks notebook source
   babynames = spark.read.format("csv").option("header", "true").option("inferSchema", "true").load("/Volumes/main/default/my-volume/babynames.csv")
   babynames.createOrReplaceTempView("babynames_table")
   years = spark.sql("select distinct(Year) from babynames_table").toPandas()['Year'].tolist()
   years.sort()
   dbutils.widgets.dropdown("year", "2014", [str(x) for x in years])
   display(babynames.filter(babynames.Year == dbutils.widgets.get("year")))
   

Étape 3 : ajouter un fichier de schéma de configuration du pack au projet

Si vous utilisez un IDE tel que Visual Studio Code, PyCharm Professional ou IntelliJ IDEA Ultimate qui prend en charge les fichiers YAML et les fichiers de schéma JSON, vous pouvez non seulement utiliser votre IDE pour créer le fichier de schéma de configuration du regroupement, mais pour vérifier la syntaxe et la mise en forme du fichier de configuration. Bien que le fichier de configuration du regroupement que vous créerz l’étape 5 est basé sur YAML, le fichier de schéma de configuration du pack dans cette étape est basé sur JSON.

Visual Studio Code

1. Ajoutez la prise en charge du serveur de langage YAML à Visual Studio Code, par exemple en installant l’extension YAML à partir de la place de marché Visual Studio Code.

2. Générez le fichier de schéma JSON de configuration du pack de ressources Databricks en utilisant l’interface CLI Databricks pour exécuter la commande bundle schema et rediriger la sortie vers un fichier JSON. Par exemple, générez un fichier nommé bundle_config_schema.json dans le répertoire actif, comme suit :

   databricks bundle schema > bundle_config_schema.json
   

3. À l’étape 5, vous allez ajouter le commentaire suivant au début de votre fichier de configuration du pack, qui associe votre fichier de configuration du pack au fichier de schéma JSON spécifié :

   # yaml-language-server: $schema=bundle_config_schema.json
   

   Remarque

   Dans le commentaire précédent, si votre fichier de schéma JSON de configuration du pack de ressources Databricks se trouve dans un chemin d’accès différent, remplacez bundle_config_schema.json par le chemin d’accès complet à votre fichier de schéma.

PyCharm Professional

1. Générez le fichier de schéma JSON de configuration du regroupement de ressources Databricks en utilisant l’interface CLI Databricks pour exécuter la commande bundle schema et rediriger la production vers un fichier JSON. Par exemple, générez un fichier nommé bundle_config_schema.json dans le répertoire actif, comme suit :

   databricks bundle schema > bundle_config_schema.json
   

2. Configurez PyCharm pour reconnaître le fichier de schéma JSON de configuration du pack, puis effectuez la mise en correspondance du schéma JSON en suivant les instructions fournies dans Configurer un schéma JSON personnalisé.

3. À l’étape 5, vous allez utiliser PyCharm pour créer ou ouvrir un fichier de configuration du regroupement. Par convention, ce fichier est nommé databricks.yml.

IntelliJ IDEA Ultimate

1. Générez le fichier de schéma JSON de configuration du pack de ressources Databricks en utilisant l’interface CLI Databricks pour exécuter la commande bundle schema et rediriger la sortie vers un fichier JSON. Par exemple, générez un fichier nommé bundle_config_schema.json dans le répertoire actif, comme suit :

   databricks bundle schema > bundle_config_schema.json
   

2. Configurez IntelliJ IDEA pour reconnaître le fichier de schéma JSON de configuration du pack, puis effectuez la mise en correspondance du schéma JSON en suivant les instructions fournies dans Configurer un schéma JSON personnalisé.

3. À l’étape 5, vous allez utiliser IntelliJ IDEA pour créer ou ouvrir un fichier de configuration du regroupement. Par convention, ce fichier est nommé databricks.yml.

Étape 4 : configurer l’authentification

Dans cette étape, vous configurez l’authentification entre l’interface CLI Databricks sur votre machine de développement et votre espace de travail Azure Databricks. Cet article suppose que vous voulez utiliser l’authentification utilisateur à machine (U2M) OAuth et un profil de configuration Azure Databricks correspondant nommé DEFAULT pour l’authentification.

1. Utilisez l’interface CLI Databricks pour lancer la gestion des jetons OAuth localement en exécutant la commande suivante pour chaque espace de travail cible.

   Dans la commande suivante, remplacez <workspace-url> par votre URL d’espace de travail Azure Databricks, par exemple https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. L’interface CLI Databricks vous invite à enregistrer les informations que vous avez entrées en tant que profil de configuration Azure Databricks. Appuyez sur Enter pour accepter le nom de profil suggéré, ou entrez le nom d’un profil nouveau ou existant. Tout profil existant portant le même nom est remplacé par les informations que vous avez entrées. Vous pouvez utiliser des profils pour changer rapidement de contexte d’authentification entre plusieurs espaces de travail.

   Pour obtenir la liste des profils existants, dans un autre terminal ou une autre invite de commandes, utilisez l’interface CLI Databricks pour exécuter la commande databricks auth profiles. Pour voir les paramètres existants d’un profil spécifique, exécutez la commande databricks auth env --profile <profile-name>.

3. Dans votre navigateur web, suivez les instructions à l’écran pour vous connecter à votre espace de travail Azure Databricks.

4. Pour voir la valeur du jeton OAuth actuel d’un profil et l’horodatage de l’expiration à venir du jeton, exécutez une des commandes suivantes :

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   Si vous avez plusieurs profils avec la même valeur pour --host, il peut être nécessaire de spécifier aussi les options --host et -p pour permettre à l’interface CLI Databricks de trouver les informations du jeton OAuth correspondant.

Étape 5 : ajouter un fichier de configuration du pack au projet

Dans cette étape, vous définissez la façon dont vous aller déployer et exécuter les deux notebooks. Pour cette démonstration, vous allez utiliser un travail Azure Databricks pour exécuter le premier notebook, puis le deuxième notebook. Étant donné que le premier notebook enregistre les données et que le deuxième notebook interroge les données enregistrées, il faut que le premier notebook finisse son exécution avant que le deuxième notebook ne démarre. Vous modélisez ces objectifs dans un fichier de configuration du regroupement dans votre projet.

1. À partir de la racine du répertoire, créez le fichier de configuration du pack, un fichier nommé databricks.yml.
2. Ajoutez le code suivant au fichier databricks.yml, en remplaçant <workspace-url> par votre URL par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net. Cette URL doit correspondre à celle de votre fichier .databrickscfg :

# yaml-language-server: $schema=bundle_config_schema.json
bundle:
  name: baby-names

resources:
  jobs:
    retrieve-filter-baby-names-job:
      name: retrieve-filter-baby-names-job
      job_clusters:
        - job_cluster_key: common-cluster
          new_cluster:
            spark_version: 12.2.x-scala2.12
            node_type_id: Standard_DS3_v2
            num_workers: 1
      tasks:
        - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./retrieve-baby-names.py
        - task_key: filter-baby-names-task
          depends_on:
            - task_key: retrieve-baby-names-task
          job_cluster_key: common-cluster
          notebook_task:
            notebook_path: ./filter-baby-names.py

targets:
  development:
    workspace:
      host: <workspace-url>

Pour la personnalisation des tâches, les mappages dans une déclaration de tâche correspondent à la charge utile de la demande, exprimée au format YAML, de l’opération de création de projets telle que documentée dans POST /api/2.1/jobs/create dans la référence de l’API REST.

Étape 6 : valider le fichier de configuration du pack du projet

Dans cette étape, vous vérifiez si la configuration du pack est valide.

1. Utilisez l’interface Databricks CLI pour exécuter la commande bundle validate comme suit :

   databricks bundle validate
   

2. Si un résumé de la configuration de l’offre groupée est retourné, la validation a réussi. Si des erreurs sont renvoyées, corrigez-les , puis répétez cette étape.

Si vous apportez des modifications à votre pack après cette étape, vous devez répéter cette étape pour vérifier si les paramètres de votre pack sont toujours valides.

Étape 7 : déployer le projet local sur l’espace de travail distant

Au cours de cette étape, vous allez déployer les deux notebooks locaux dans votre espace de travail Databricks Azure distant et créer le travail Azure Databricks dans votre espace de travail.

1. Utilisez l’interface Databricks CLI pour exécuter la commande bundle deploy comme suit :

   databricks bundle deploy -t development
   

2. Vérifiez si les deux notebooks locaux ont été déployés : dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Espace de travail.

3. Cliquez dans le dossier Utilisateurs ><your-username>> .bundle > baby-names > développement > fichiers. Les deux blocs-notes doivent se trouver dans ce dossier.

4. Vérifiez si le travail a été créé : dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Flux de travail.

5. Dans l’onglet Travaux, cliquez sur retrieve-filter-baby-names-job.

6. Cliquez sur l’onglet Tâches. Il doit y avoir deux tâches : retrieve-baby-names-task et filter-baby-names-task.

Si vous apportez des modifications à votre pack après cette étape, vous devez répéter les étapes 6 à 7 pour vérifier si la configuration de votre pack est toujours valide, puis redéployer le projet.

Étape 8 : exécuter le projet déployé

Dans cette étape, vous allez exécuter le travail Azure Databricks dans votre espace de travail.

1. Utilisez l’interface Databricks CLI pour exécuter la commande bundle run comme suit :

   databricks bundle run -t development retrieve-filter-baby-names-job
   

2. Copiez la valeur Run URL qui apparaît dans votre terminal et collez cette valeur dans votre navigateur web pour ouvrir votre espace de travail Azure Databricks.

3. Dans votre espace de travail Azure Databricks, une fois les deux tâches terminées avec succès et les barres de titre vertes affichées, cliquez sur la tâche filter-baby-names-task pour afficher les résultats de la requête.

Si vous apportez des modifications à votre pack après cette étape, vous devez répéter les étapes 6 à 8 pour vérifier si la configuration de votre pack est toujours valide, puis redéployer le projet et exécuter le projet redéployé.

Étape 9 : nettoyer

Au cours de cette étape, vous allez supprimer les deux blocs-notes déployés et le travail de votre espace de travail.

1. Utilisez l’interface Databricks CLI pour exécuter la commande bundle destroy comme suit :

   databricks bundle destroy
   

2. Confirmez la demande de suppression de travail : lorsque l’option de détruire définitivement des ressources s’affiche, tapez y et appuyez sur Enter.

3. Confirmez la demande de suppression des notebooks : lorsque l’option de détruire définitivement le dossier précédemment déployé et tous ses fichiers s’affiche, tapez y et appuyez sur Enter.

L’exécution de la commande bundle destroy supprime uniquement le travail déployé et le dossier contenant les deux notebooks déployés. Cette commande ne supprime aucun effet secondaire, tel que le fichier babynames.csv créé par le premier bloc-notes. Pour supprimer le fichier babybnames.csv, procédez comme suit :

1. Dans la barre latérale de votre espace de travail Azure Databricks, cliquez sur Catalogues.
2. Cliquez sur Parcourir DBFS.
3. Cliquez sur le fichier FileStore.
4. Cliquez sur la flèche déroulante à côté de babynames.csv, puis cliquez sur Supprimer.
5. Si vous souhaitez également supprimer le pack de votre ordinateur de développement, vous pouvez maintenant supprimer le répertoire local de l’étape 1.