SDK do Databricks para R
Observação
Este artigo aborda o SDK do Databricks para R do Databricks Labs, que está em um estado experimental. Para fornecer comentários, fazer perguntas e relatar problemas, use a guia Problemas no repositório do SDK do Databricks para R no GitHub.
Neste artigo, você aprenderá a automatizar operações do Azure Databricks em workspaces do Azure Databricks com o SDK do Databricks para R. Este artigo complementa a documentação do SDK do Databricks para R.
Observação
O SDK do Databricks para R não dá suporte à automação de operações em contas do Azure Databricks. Para chamar as operações de nível da conta, use um SDK do Databricks diferente, por exemplo:
Antes de começar
Antes de começar a usar o SDK do Databricks para R, seu computador de desenvolvimento deve ter:
Um token de acesso pessoal do Azure Databricks para o workspace de destino do Azure Databricks que você deseja automatizar.
Observação
O SDK do Databricks para R dá suporte apenas à autenticação de token de acesso pessoal do Azure Databricks.
R e, opcionalmente, um IDE (ambiente de desenvolvimento integrado) compatível com R. O Databricks recomenda o RStudio Desktop e o usa nas instruções deste artigo.
Introdução ao SDK do Databricks para R
Disponibilize a URL do workspace do Azure Databricks o token de acesso pessoal disponível para os scripts do projeto do R. Por exemplo, você pode adicionar o seguinte ao arquivo
.Renviron
de um projeto do R. Substitua<your-workspace-url>
por sua URL por workspace, por exemplo,https://adb-1234567890123456.7.azuredatabricks.net
. Substitua<your-personal-access-token>
pelo token de acesso pessoal do Azure Databricks, por exemplo,dapi12345678901234567890123456789012
.DATABRICKS_HOST=<your-workspace-url> DATABRICKS_TOKEN=<your-personal-access-token>
Para criar um token de acesso pessoal do Azure Databricks, siga as etapas em Tokens de acesso pessoal do Azure Databricks para usuários do workspace.
Para obter outras maneiras de fornecer a URL do workspace do Azure Databricks e o token de acesso pessoal, consulte Autenticação no repositório do SDK do Databricks para R in GitHub.
Importante
Não adicione arquivos
.Renviron
a sistemas de controle de versão, pois isso traz o risco de expor informações confidenciais, como tokens de acesso pessoal do Azure Databricks.Instalar o pacote do SDK do Databricks para R. Por exemplo, no RStudio Desktop, na exibição Console (Exibir > Mover Foco para Console), execute os seguintes comandos, um de cada vez:
install.packages("devtools") library(devtools) install_github("databrickslabs/databricks-sdk-r")
Observação
O pacote do SDK do Databricks para R não está disponível no CRAN.
Adicione código para referenciar o SDK do Databricks para R e para listar todos os clusters em seu workspace do Azure Databricks. Por exemplo, no arquivo
main.r
de um projeto, o código pode ser o seguinte:require(databricks) client <- DatabricksClient() list_clusters(client)[, "cluster_name"]
Executar o script. Por exemplo, no RStudio Desktop, no editor de scripts com o arquivo
main.r
de um projeto ativo, clique em Fonte > Fonte ou Fonte com Echo.A lista de clusters aparece. Por exemplo, no RStudio Desktop, isso está na exibição Console.
Exemplos de código
Os exemplos de código a seguir demonstram como usar o SDK do Databricks para R para criar e excluir clusters e criar trabalhos.
Criar um cluster
Este exemplo de código cria um cluster com a versão especificada do Databricks Runtime e o tipo de nó do cluster. Este cluster tem um trabalho e o cluster é encerrado automaticamente após 15 minutos de tempo ocioso.
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 = "")
)
Excluir um cluster permanentemente
Este exemplo de código exclui permanentemente o cluster com a ID de cluster especificada do workspace.
require(databricks)
client <- DatabricksClient()
cluster_id <- readline("ID of the cluster to delete (for example, 1234-567890-ab123cd4):")
delete_cluster(client, cluster_id)
Criar um trabalho
Este exemplo de código cria um trabalho do Azure Databricks que pode ser utilizado para executar o notebook especificado no cluster especificado. À medida que o código é executado, ele obtém o caminho do notebook existente, a ID do cluster existente e as configurações de trabalho relacionadas do usuário no 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
Você pode usar o pacote popular logging
para registrar mensagens em log. Esse pacote fornece suporte para vários níveis de log e formatos de log personalizados. Você pode usar esse pacote para registrar mensagens no console ou em um arquivo. Para registrar mensagens em log, faça o seguinte:
Instale o pacote
logging
. Por exemplo, no RStudio Desktop, na exibição Console (Exibir > Mover Foco para Console), execute os seguintes comandos:install.packages("logging") library(logging)
Inicialize o pacote de log, defina onde registrar as mensagens e defina o nível de log. Por exemplo, o código a seguir registra todas as mensagens
ERROR
e abaixo no arquivoresults.log
.basicConfig() addHandler(writeToFile, file="results.log") setLevel("ERROR")
Registrar mensagens conforme necessário. Por exemplo, o código a seguir registra erros se o código não puder autenticar ou listar os nomes dos clusters disponíveis.
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) })
Testando
Para testar seu código, você pode usar estruturas de teste do R, como testthat. Para testar seu código em condições simuladas sem chamar pontos de extremidade da API REST do Azure Databricks ou alterar o estado de suas contas ou workspaces do Azure Databricks, você pode usar bibliotecas de simulação do R, como simulação.
Por exemplo, dado o seguinte arquivo nomeado helpers.r
contendo uma função createCluster
que retorna informações sobre o novo 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)
}
E dado o seguinte arquivo chamado main.R
que chama a função 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)
O arquivo nomeado test-helpers.py
a seguir testa se a função createCluster
retorna a resposta esperada. Em vez de criar um cluster no workspace de destino, esse teste simula um objeto DatabricksClient
, define as configurações do objeto simulado e, em seguida, passa o objeto simulado para a função createCluster
. Em seguida, o teste verifica se a função retorna a ID esperada do novo cluster simulado.
# 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 adicionais
Para saber mais, veja: