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

Dans cet article, vous allez apprendre à automatiser les opérations Azure Databricks dans les espaces de travail Azure Databricks 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.

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

1. 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 les éléments suivants au fichier d’un .Renviron 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, suivez les étapes décrites dans Créer des jetons d’accès personnels pour les utilisateurs de l’espace de travail.

   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.

2. 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.

3. 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 d’un main.r projet, le code peut être le suivant :

   require(databricks)
   
   client <- DatabricksClient()
   
   list_clusters(client)[, "cluster_name"]
   

4. Exécutez votre script. Par exemple, dans RStudio Desktop, dans l’éditeur de script avec le fichier d’un main.r projet actif, cliquez sur Source > Source ou Source avec Echo.

5. 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é. À mesure que ce code s’exécute, il obtient le chemin d’accès du notebook existant, l’ID de cluster existant et les paramètres de tâche associés fournis par l'utilisateur dans 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 = "")
)

Exploitation forestière

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 :

1. 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)
   

2. 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")
   

3. 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 simulant un DatabricksClient objet, définit les paramètres de l’objet fictif, puis transmet l’objet fictif à la createCluster fonction. Le test vérifie ensuite si la fonction retourne le nouvel ID attendu du 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 :

• Documentation du Kit SDK Databricks pour R
• Opérations de longue durée
• Réponses paginées