Kit de développement logiciel (SDK) Databricks pour R

Article
09/10/2024

Remarque

Cet article couvre le Kit de développement logiciel (SDK) Databricks pour R de Databricks Labs, qui est dans un état expérimental. Pour envoyer des commentaires, poser des questions et signaler des problèmes, utilisez l’onglet Problèmes du référentiel du kit SDK Databricks pour R dans GitHub.

Dans cet article, vous allez apprendre à automatiser les opérations dans les espaces de travail Azure Databricks et les ressources associées avec le Kit de développement logiciel (SDK) Databricks pour R. Cet article complète la documentation du Kit de développement logiciel (SDK) Databricks pour R.

Remarque

Le Kit de développement logiciel (SDK) Databricks pour R ne prend pas en charge l’automatisation des opérations dans les comptes Azure Databricks. Pour appeler des opérations au niveau du compte, utilisez un autre Kit de développement logiciel (SDK) Databricks, par exemple :

Avant de commencer

Avant de commencer à utiliser le kit SDK Databricks pour R, assurez-vous que votre ordinateur de développement dispose des éléments suivants :

Jeton d’accès personnel Azure Databricks pour l’espace de travail Azure Databricks cible que vous souhaitez automatiser.

Remarque

Le Kit de développement logiciel (SDK) Databricks pour R prend uniquement en charge l’authentification par jeton d’accès personnel Azure Databricks.
R et éventuellement un environnement de développement intégré (IDE) compatible R. Databricks recommande RStudio Desktop et l’utilise dans les instructions de cet article.

Prise en main du kit SDK Databricks pour R

Rendez l’URL de votre espace de travail Azure Databricks et le jeton d’accès personnel disponibles pour les scripts de votre projet R. Par exemple, vous pouvez ajouter ce qui suit au fichier .Renviron d’un projet R. Remplacez <your-workspace-url> par votre URL par espace de travail, par exemple https://adb-1234567890123456.7.azuredatabricks.net. Remplacez <your-personal-access-token> par la valeur de votre jeton d’accès personnel Azure Databricks, par exemple dapi12345678901234567890123456789012.
```
DATABRICKS_HOST=<your-workspace-url>
DATABRICKS_TOKEN=<your-personal-access-token>
```
Pour créer un jeton d’accès personnel Azure Databricks, effectuez les étapes suivantes :
1. Dans votre espace de travail Azure Databricks, cliquez sur votre nom d’utilisateur Azure Databricks dans la barre supérieure, puis sélectionnez Paramètres dans la liste déroulante.
2. Cliquez sur Développeur.
3. À côté de Jetons d’accès, cliquez sur Gérer.
4. Cliquez sur Générer un nouveau jeton.
5. (Facultatif) Entrez un commentaire qui vous aide à identifier ce jeton à l’avenir et modifiez sa durée de vie par défaut (90 jours). Pour créer un jeton sans durée de vie (non recommandé), laissez vide la zone Durée de vie (en jours).
6. Cliquez sur Générer.
7. Copiez le jeton affiché dans un emplacement sécurisé, puis cliquez sur Terminé.
Remarque

Veillez à enregistrer le jeton copié dans un emplacement sécurisé. Ne partagez pas votre jeton copié avec d'autres. Si vous le perdez, vous ne pouvez pas régénérer exactement le même. Vous devez donc répéter cette procédure pour créer un jeton. Si vous perdez le jeton copié ou si vous pensez que le jeton a été compromis, Databricks vous recommande vivement de supprimer immédiatement ce jeton de votre espace de travail en cliquant sur l’icône de la corbeille (Révoquer) à côté du jeton de la page Jetons d’accès.

Si vous n'êtes pas en mesure de créer ou d'utiliser des jetons dans votre espace de travail, cela peut être dû au fait que votre administrateur d'espace de travail a désactivé les jetons ou ne vous a pas donné l'autorisation de créer ou d'utiliser des jetons. Consultez votre administrateur d'espace de travail ou les rubriques suivantes :
- Activer ou désactiver l'authentification par jeton d'accès personnel pour l'espace de travail
- Autorisations de jeton d'accès personnel
Pour obtenir d’autres façons de fournir l’URL de votre espace de travail Azure Databricks et le jeton d’accès personnel, consultez Authentification dans le référentiel du Kit de développement logiciel (SDK) Databricks pour R dans GitHub.

Important

N’ajoutez pas de fichiers .Renviron aux systèmes de gestion de version, car cela risque d’exposer des informations sensibles telles que les jetons d’accès personnels Azure Databricks.
Installez le package Databricks SDK pour R. Par exemple, dans RStudio Desktop, dans la vue Console (Afficher > déplacer le focus vers la console), exécutez les commandes suivantes, une par une :
```
install.packages("devtools")
library(devtools)
install_github("databrickslabs/databricks-sdk-r")
```
Remarque

Le package du Kit de développement logiciel (SDK) Databricks pour R n’est pas disponible sur CRAN.
Ajoutez du code pour référencer le Kit de développement logiciel (SDK) Databricks pour R et répertorier tous les clusters dans votre espace de travail Azure Databricks. Par exemple, dans le fichier main.r d’un projet, le code peut être comme suit :
```
require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]
```
Exécutez votre script. Par exemple, dans RStudio Desktop, dans l’éditeur de script avec le fichier main.r d’un projet actif, cliquez sur Source > Source ou Source avec Echo.
La liste des clusters s’affiche. Par exemple, dans RStudio Desktop, cela se trouve dans la vue Console.

Exemples de code

Les exemples de code suivants montrent comment utiliser le kit SDK Databricks pour R pour créer et supprimer des clusters, et exécuter des travaux.

Créer un cluster
Supprimer définitivement un cluster
Créer un travail

Créer un cluster

Cet exemple de code crée un cluster avec la version Databricks Runtime et le type de nœud de cluster spécifiés. Ce cluster possède un Worker et s’arrête automatiquement après 15 minutes d’inactivité.

require(databricks)

client <- DatabricksClient()

response <- create_cluster(
  client = client,
  cluster_name = "my-cluster",
  spark_version = "12.2.x-scala2.12",
  node_type_id = "Standard_DS3_v2",
  autotermination_minutes = 15,
  num_workers = 1
)

# Get the workspace URL to be used in the following results message.
get_client_debug <- strsplit(client$debug_string(), split = "host=")
get_host <- strsplit(get_client_debug[[1]][2], split = ",")
host <- get_host[[1]][1]

# Make sure the workspace URL ends with a forward slash.
if (endsWith(host, "/")) {
} else {
  host <- paste(host, "/", sep = "")
}

print(paste(
  "View the cluster at ",
  host,
  "#setting/clusters/",
  response$cluster_id,
  "/configuration",
  sep = "")
)

Supprimer définitivement un cluster

Cet exemple de code supprime définitivement de l’espace de travail le cluster possédant l’ID spécifié.

require(databricks)

client <- DatabricksClient()

cluster_id <- readline("ID of the cluster to delete (for example, 1234-567890-ab123cd4):")

delete_cluster(client, cluster_id)

Créer un travail

Cet exemple de code crée une tâche Azure Databricks qui peut être utilisée pour exécuter le notebook spécifié sur le cluster spécifié. En cours d’exécution, ce code récupère le chemin du notebook existant, l’ID du cluster existant et les paramètres de tâche associés depuis l’utilisateur sur la console.

require(databricks)

client <- DatabricksClient()

job_name <- readline("Some short name for the job (for example, my-job):")
description <- readline("Some short description for the job (for example, My job):")
existing_cluster_id <- readline("ID of the existing cluster in the workspace to run the job on (for example, 1234-567890-ab123cd4):")
notebook_path <- readline("Workspace path of the notebook to run (for example, /Users/someone@example.com/my-notebook):")
task_key <- readline("Some key to apply to the job's tasks (for example, my-key):")

print("Attempting to create the job. Please wait...")

notebook_task <- list(
  notebook_path = notebook_path,
  source = "WORKSPACE"
)

job_task <- list(
  task_key = task_key,
  description = description,
  existing_cluster_id = existing_cluster_id,
  notebook_task = notebook_task
)

response <- create_job(
  client,
  name = job_name,
  tasks = list(job_task)
)

# Get the workspace URL to be used in the following results message.
get_client_debug <- strsplit(client$debug_string(), split = "host=")
get_host <- strsplit(get_client_debug[[1]][2], split = ",")
host <- get_host[[1]][1]

# Make sure the workspace URL ends with a forward slash.
if (endsWith(host, "/")) {
} else {
  host <- paste(host, "/", sep = "")
}

print(paste(
  "View the job at ",
  host,
  "#job/",
  response$job_id,
  sep = "")
)

Logging

Vous pouvez utiliser le package populaire logging pour consigner les messages. Ce package prend en charge plusieurs niveaux de journalisation et des formats de journaux personnalisés. Vous pouvez utiliser ce package pour consigner des messages dans la console ou dans un fichier. Pour consigner les messages, procédez comme suit :

Installez le package logging. Par exemple, dans RStudio Desktop, dans la vue Console (Afficher > déplacer le focus vers la console), exécutez les commandes suivantes :
```
install.packages("logging")
library(logging)
```
Démarrez le package de journalisation, définissez où consigner les messages et définissez le niveau de journalisation. Par exemple, le code suivant enregistre tous les messages ERROR et ci-dessous dans le fichier results.log.
```
basicConfig()
addHandler(writeToFile, file="results.log")
setLevel("ERROR")
```

Consignez les messages en fonction des besoins. Par exemple, le code suivant enregistre des erreurs si le code ne peut pas s’authentifier ou répertorier les noms des clusters disponibles.

require(databricks)
require(logging)

basicConfig()
addHandler(writeToFile, file="results.log")
setLevel("ERROR")

tryCatch({
  client <- DatabricksClient()
}, error = function(e) {
  logerror(paste("Error initializing DatabricksClient(): ", e$message))
  return(NA)
})

tryCatch({
  list_clusters(client)[, "cluster_name"]
}, error = function(e) {
  logerror(paste("Error in list_clusters(client): ", e$message))
  return(NA)
})

Test

Pour tester votre code, vous pouvez utiliser des frameworks de test R tels que testthat. Pour tester votre code dans des conditions simulées sans appeler des points de terminaison d’API REST d’Azure Databricks ni modifier l’état de vos comptes ou espaces de travail Azure Databricks, vous pouvez utiliser des bibliothèques fictives R telles que mockery.

Par exemple, compte tenu du fichier suivant nommé helpers.r contenant une fonction createCluster qui retourne des informations sur le nouveau cluster :

library(databricks)

createCluster <- function(
  databricks_client,
  cluster_name,
  spark_version,
  node_type_id,
  autotermination_minutes,
  num_workers
) {
  response <- create_cluster(
    client = databricks_client,
    cluster_name = cluster_name,
    spark_version = spark_version,
    node_type_id = node_type_id,
    autotermination_minutes = autotermination_minutes,
    num_workers = num_workers
  )
  return(response)
}

Et compte tenu du fichier suivant nommé main.R qui appelle la fonction createCluster :

library(databricks)
source("helpers.R")

client <- DatabricksClient()

# Replace <spark-version> with the target Spark version string.
# Replace <node-type-id> with the target node type string.
response = createCluster(
  databricks_client = client,
  cluster_name = "my-cluster",
  spark_version = "<spark-version>",
  node_type_id = "<node-type-id>",
  autotermination_minutes = 15,
  num_workers = 1
)

print(response$cluster_id)

Le fichier suivant nommé test-helpers.py teste si la fonction createCluster retourne la réponse attendue. Au lieu de créer un cluster dans l’espace de travail cible, ce test simule un objet DatabricksClient, définit les paramètres de l’objet fictif, puis transmet l’objet fictif à la fonction createCluster. Le test vérifie ensuite si la fonction retourne l’ID attendu du nouveau cluster fictif.

# install.packages("testthat")
# install.pacakges("mockery")
# testthat::test_file("test-helpers.R")
lapply(c("databricks", "testthat", "mockery"), library, character.only = TRUE)
source("helpers.R")

test_that("createCluster mock returns expected results", {
  # Create a mock response.
  mock_response <- list(cluster_id = "abc123")

  # Create a mock function for create_cluster().
  mock_create_cluster <- mock(return_value = mock_response)

  # Run the test with the mock function.
  with_mock(
    create_cluster = mock_create_cluster,
    {
      # Create a mock Databricks client.
      mock_client <- mock()

      # Call the function with the mock client.
      # Replace <spark-version> with the target Spark version string.
      # Replace <node-type-id> with the target node type string.
      response <- createCluster(
        databricks_client = mock_client,
        cluster_name = "my-cluster",
        spark_version = "<spark-version>",
        node_type_id = "<node-type-id>",
        autotermination_minutes = 15,
        num_workers = 1
      )

      # Check that the function returned the correct mock response.
      expect_equal(response$cluster_id, "abc123")
    }
  )
})

Ressources supplémentaires

Pour plus d'informations, consultez les pages suivantes :

Partager via

Kit de développement logiciel (SDK) Databricks pour R

Avant de commencer

Prise en main du kit SDK Databricks pour R

Exemples de code

Créer un cluster

Supprimer définitivement un cluster

Créer un travail

Logging

Test

Ressources supplémentaires

Commentaires

Ressources supplémentaires