Databricks SDK pour R

remarque

Cet article couvre le Databricks SDK pour R de Databricks Labs, qui est dans un état expérimental. Pour fournir des commentaires, poser des questions et signaler des problèmes, veuillez utiliser l'onglet Issues dans le repository Databricks SDK pour R sur GitHub.

Dans cet article, vous apprenez à automatiser les opérations Databricks dans les workspaces Databricks avec le Databricks SDK pour R. Cet article complète la documentation Databricks SDK pour R.

remarque

Le SDK Databricks pour R ne prend pas en charge l'automatisation des opérations dans les comptes Databricks. Pour appeler des opérations au niveau du compte, utilisez un autre Databricks SDK, par exemple :

• Le SDK Databricks pour Python
• Le Databricks SDK pour Java
• Le SDK Databricks pour Go

Exigences

Pour utiliser le SDK Databricks pour R, votre machine de développement doit disposer de :

• Un jeton d'accès personnel Databricks pour le Workspace Databricks cible que vous souhaitez automatiser.

remarque

Le SDK Databricks pour R prend en charge l'authentification par jeton d'accès personnel Databricks uniquement.

• R, et éventuellement un environnement de développement intégré (IDE) compatible avec R. Databricks recommande RStudio Desktop et l'utilise dans les instructions de cet article.

Démarrer avec le SDK Databricks pour R

1. Mettez l'URL de votre Workspace Databricks et votre jeton d'accès personnel à la disposition des 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 l'URL de l'instance de votre Workspace, par exemple https://dbc-a1b2345c-d6e7.cloud.databricks.com. Remplacez <your-personal-access-token> par votre jeton d'accès personnel Databricks, par exemple dapi12345678901234567890123456789012.

   DATABRICKS_HOST=<your-workspace-url>
   DATABRICKS_TOKEN=<your-personal-access-token>

   Pour créer un jeton d'accès personnel Databricks, suivez les étapes indiquées sur Créer des jetons d'accès personnels pour les utilisateurs d'Workspace.

   Pour d'autres façons de fournir l'URL de votre Workspace Databricks et votre jeton d'accès personnel, consultez Authentification dans le repository Databricks SDK for R sur GitHub.

important

N'ajoutez pas de fichiers .Renviron aux systèmes de contrôle de version, car cela risquerait d'exposer des informations sensibles telles que les jetons d'accès personnels Databricks.

2. Installez le package Databricks SDK pour R. Par exemple, dans RStudio Desktop, dans la vue Console ( Vue > Déplacer le focus vers la console ), exécutez les commandes suivantes, une par une :

   R

   install.packages("devtools")
   library(devtools)
   install_github("databrickslabs/databricks-sdk-r")

remarque

Le package Databricks SDK pour R n'est pas disponible sur CRAN.

3. Ajoutez du code pour référencer le Databricks SDK pour R et pour lister tous les clusters de votre Databricks Workspace. Par exemple, dans le fichier main.r d'un projet, le code pourrait être le suivant :

   R

   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 main.r d'un projet actif, cliquez sur Source > Source ou Source with Echo .

5. La liste des clusters apparaît. Par exemple, dans RStudio Desktop, cela se trouve dans la vue Console .

Exemples de code

Les exemples de code suivants montrent comment utiliser le Databricks SDK pour R afin de créer et supprimer des clusters, et créer des jobs.

• Créer un cluster
• Supprimer définitivement un cluster
• Créer un Job

Créer un cluster

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

R

require(databricks)

client <- DatabricksClient()

response <- create_cluster(
  client = client,
  cluster_name = "my-cluster",
  spark_version = "12.2.x-scala2.12",
  node_type_id = "i3.xlarge",
  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 le cluster avec l'ID de cluster spécifié du Workspace.

R

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 Job

Cet exemple de code crée un job Databricks qui peut être utilisé pour exécuter le notebook spécifié sur le cluster spécifié. Lorsque ce code s'exécute, il obtient le chemin du Notebook existant, l'ID du cluster existant et les paramètres de Job associés de l'utilisateur à la console.

R

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 = "")
)

Journalisation

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

1. Installez le package logging. Par exemple, dans RStudio Desktop, dans la vue **Console** (**View > Move Focus to Console**), exécutez les commandes suivantes :

   R

   install.packages("logging")
   library(logging)

2. Initialisez le package d'enregistrement, définissez l'emplacement d'enregistrement des messages et définissez le niveau d'enregistrement. Par exemple, le code suivant logs tous les messages ERROR et inférieurs dans le fichier results.log.

   R

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

3. Journalisez les messages selon les besoins. Par exemple, le code suivant logs les erreurs si le code ne peut pas s'authentifier ou lister les noms des clusters disponibles.

   R

   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 cadres de test R tels que testthat. Pour tester votre code dans des conditions simulées sans appeler les Endpoint d'API REST Databricks ou modifier l'état de vos comptes ou Workspace Databricks, vous pouvez utiliser des bibliothèques de simulation R telles que mockery.

Par exemple, étant donné le fichier suivant nommé helpers.r contenant une fonction createCluster qui renvoie des informations sur le nouveau cluster :

R

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 étant donné le fichier suivant nommé main.R qui appelle la fonction createCluster :

R

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 renvoie la réponse attendue. Plutôt que de créer un cluster dans le Workspace cible, ce test simule un objet DatabricksClient, définit les paramètres de l'objet simulé, puis transmet l'objet simulé à la fonction createCluster. Le test vérifie ensuite si la fonction renvoie l'ID attendu du nouveau cluster simulé.

R

# 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, voir :

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