Compartir a través de

SDK de Databricks para R

  • Artículo

Nota:

En este artículo se trata el SDK de Databricks para R de Databricks Labs, que se encuentra en estado experimental. Si desea enviar comentarios, formular preguntas y notificar problemas, use la pestaña Problemas en el repositorio del SDK de Databricks para R en GitHub.

En este artículo, aprenderá a automatizar operaciones en las áreas de trabajo de Azure Databricks y en los recursos relacionados con el SDK de Databricks para R. Este artículo complementa la documentación del SDK de Databricks para R.

Nota:

El SDK de Databricks para R no admite la automatización de operaciones en cuentas de Azure Databricks. Para llamar a operaciones de nivel de cuenta, use un SDK de Databricks diferente, por ejemplo:

Antes de empezar

Antes de empezar a usar el SDK de Databricks para R, la máquina de desarrollo debe cumplir con lo siguiente:

  • Un token de acceso personal de Azure Databricks para el área de trabajo de Azure Databricks de destino que desea automatizar.

    Nota:

    El SDK de Databricks para R solo admite la autenticación de tokens de acceso personal de Azure Databricks.

  • R y, opcionalmente, un entorno de desarrollo integrado (IDE) compatible con R. Databricks recomienda RStudio Desktop y lo usa en las instrucciones de este artículo.

Introducción al SDK de Databricks para R

  1. Haga que la dirección URL del área de trabajo de Azure Databricks y el token de acceso personal estén disponibles para los scripts del proyecto de R. Por ejemplo, puede agregar lo siguiente al archivo .Renviron de un proyecto de R. Reemplace <your-workspace-url> por la dirección URL por área de trabajo; por ejemplo, https://adb-1234567890123456.7.azuredatabricks.net. Reemplace <your-personal-access-token> por el token de acceso personal de Azure Databricks, por ejemplo dapi12345678901234567890123456789012.

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

    Para crear un token de acceso personal de Azure Databricks, haga lo siguiente:

    1. En el área de trabajo de Azure Databricks, haga clic en el nombre de usuario de Azure Databricks en la barra superior y, a continuación, seleccione Configuración en la lista desplegable.
    2. Haga clic en Desarrollador.
    3. Junto a Tokens de acceso, haga clic en Administrar.
    4. Haga clic en Generate new token (Generar nuevo token).
    5. (Opcional) Escriba un comentario que le ayude a identificar este token en el futuro y cambie la duración predeterminada del token de 90 días. Para crear un token sin duración (no recomendado), deje el cuadro Duración (días) vacío (en blanco).
    6. Haga clic en Generar.
    7. Copie el token mostrado en una ubicación segura y, a continuación, haga clic en Listo.

    Nota:

    Asegúrese de guardar el token copiado en una ubicación segura. No comparta el token copiado con otros usuarios. Si pierde el token copiado, no podrá volver a generar ese mismo token. Debe repetir el procedimiento para crear un nuevo token. Si pierde el token copiado o cree que el token se ha visto comprometido, Databricks recomienda eliminar inmediatamente ese token del área de trabajo haciendo clic en el icono de papelera (Revocar) situado junto al token en la página Tokens de acceso.

    Si no puede crear o usar tokens en el área de trabajo, puede deberse a que el administrador del área de trabajo tiene tokens deshabilitados o no le ha concedido permiso para crear o usar tokens. Consulte el administrador del área de trabajo o los siguientes temas:

    Para obtener más formas de proporcionar la dirección URL del área de trabajo de Azure Databricks y el token de acceso personal, consulte Autenticación en el repositorio del SDK de Databricks para R en GitHub.

    Importante

    No agregue archivos .Renviron a los sistemas de control de versiones, ya que esto conlleva la exposición de información confidencial, como los tokens de acceso personal de Azure Databricks.

  2. Instale el SDK de Databricks para el paquete de R. Por ejemplo, en RStudio Desktop, en la vista Consola (Ver > mover el foco a la consola), ejecute los siguientes comandos, de uno en uno:

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

    Nota:

    El paquete del SDK de Databricks para R no está disponible en CRAN.

  3. Agregue código para hacer referencia al SDK de Databricks para R y para enumerar todos los clústeres del área de trabajo de Azure Databricks. Por ejemplo, en el archivo main.r de un proyecto, el código podría ser el siguiente:

    require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]

  4. Ejecute el script. Por ejemplo, en RStudio Desktop, en el editor de scripts con el archivo de un proyecto main.r activo, haga clic en Origen > Origen u Origen con Eco.

  5. Aparecerá la lista de clústeres. Por ejemplo, en RStudio Desktop, esto se encuentra en la vista Consola.

Ejemplos de código

En los ejemplos de código siguientes, se muestra cómo usar el SDK de Databricks para R para crear y eliminar clústeres, y crear trabajos.

Crear un clúster

En este ejemplo de código se crea un clúster con la versión de Databricks Runtime y el tipo de nodo de clúster especificados. Este clúster tiene un rol de trabajo y el clúster se finaliza automáticamente después de un tiempo de inactividad de 15 minutos.

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

Eliminación permanente de un usuario

En este ejemplo de código, se elimina permanentemente el clúster con el identificador de clúster especificado del área de trabajo.

require(databricks)

client <- DatabricksClient()

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

delete_cluster(client, cluster_id)

Creación de un trabajo

En este ejemplo de código, se crea un trabajo de Azure Databricks que ejecuta el cuaderno especificado en el clúster especificado. A medida que se ejecuta el código, obtiene la ruta de acceso del cuaderno existente, el id. de clúster existente y la configuración del trabajo relacionado del usuario en el terminal.

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

Registro

Puede usar el paquete popular logging para registrar mensajes. Este paquete proporciona compatibilidad con varios niveles de registro y formatos de registro personalizados. Puede usar este paquete para registrar mensajes en la consola o en un archivo. Para registrar mensajes, haga lo siguiente:

  1. Instale el paquete logging. Por ejemplo, en RStudio Desktop, en la vista Consola (Ver> Mover foco a consola), ejecute los siguientes comandos:

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

  2. Arranque el paquete de registro, establezca dónde registrar los mensajes y establezca el nivel de registro. Por ejemplo, el código siguiente registra todos los mensajes ERROR y debajo en el archivo results.log.

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

  3. Registre los mensajes según sea necesario. Por ejemplo, el código siguiente registra los errores si el código no puede autenticarse ni enumerar los nombres de los clústeres 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)
})

Prueba

Para probar el código, puede usar marcos de pruebas de R, como testthat. Para probar el código en condiciones simuladas sin llamar a los puntos de conexión de la API de REST de Azure Databricks ni cambiar el estado de las cuentas o áreas de trabajo de Azure Databricks, puede usar bibliotecas simuladas de R, como simulacro.

Por ejemplo, dado el siguiente archivo denominado helpers.r que contiene una función createCluster que devuelve información sobre el nuevo clúster:

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)
}

Y dado el siguiente archivo denominado main.R que llama a la función 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)

El siguiente archivo denominado test-helpers.py comprueba si la función createCluster devuelve la respuesta esperada. En lugar de crear un clúster en el área de trabajo de destino, esta prueba simula un objeto DatabricksClient, define la configuración del objeto simulado y después pasa el objeto simulado a la función createCluster. A continuación, la prueba comprueba si la función devuelve el nuevo identificador esperado del clúster ficticio.

# 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")
    }
  )
})

Recursos adicionales

Para más información, consulte: