SDK do Databricks para R

  • Artigo

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 em workspaces do Azure Databricks e recursos relacionados 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

  1. 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, faça o seguinte:

    1. No workspace do Azure Databricks, clique no nome de usuário do Azure Databricks na barra superior e selecione Configurações na lista suspensa.
    2. Clique em Desenvolvedor.
    3. Ao lado de Tokens de acesso, clique em Gerenciar.
    4. Clique em Gerar novo token.
    5. (Opcional) Insira um comentário que ajude você a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
    6. Clique em Gerar.
    7. Copie o token exibido para um local seguro e clique em Concluído.

    Observação

    Lembre-se de salvar o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente aquele mesmo token. Em vez disso, será necessário repetir esse procedimento para criar um novo token. Caso você tenha perdido o token copiado ou acredite que ele tenha sido comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu workspace clicando no ícone de lixeira (Revogar) ao lado do token na página de Tokens de acesso.

    Se você não conseguir criar ou usar tokens em seu workspace, isso pode ocorrer porque o administrador do workspace desabilitou tokens ou não deu permissão para criar ou usar tokens. Veja o administrador do workspace ou o seguinte:

    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.

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

  3. 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"]

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

  5. 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:

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

  2. 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 arquivo results.log.

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

  3. 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: