SDK do Databricks para R

Observação

Este artigo aborda o SDK do Databricks para R da Databricks Labs, que está em um estado Experimental . Para fornecer comentários, fazer perguntas e relatar problemas, use a guia Problemas no repositório Databricks SDK para R no GitHub.

Neste artigo, você aprenderá como automatizar operações no workspace do Databricks e recursos relacionados com o SDK do Databricks para R. Este artigo complementa a documentação do Databricks SDK para R.

Observação

O site Databricks SDK for R não oferece suporte à automação de operações na conta Databricks. Para chamar operações no nível da conta, use um SDK Databricks diferente, por exemplo:

Antes de começar

Antes de começar a usar o Databricks SDK para R, sua máquina de desenvolvimento deve ter:

  • Um access tokenpessoal do Databricks para o workspace do Databricks de destino que você deseja automatizar.

    Observação

    O SDK do Databricks para R dá suporte apenas à autenticação access tokens pessoal do Databricks.

  • R e, opcionalmente, um ambiente de desenvolvimento integrado (IDE) compatível com R. A Databricks recomenda o RStudio Desktop e o utiliza nas instruções deste artigo.

Comece a usar o Databricks SDK para R

  1. Disponibilize a URL do seu workspace Databricks e access tokens pessoal para os scripts do seu projeto R. Por exemplo, você pode adicionar o seguinte ao arquivo .Renviron de um projeto R. Substitua <your-workspace-url> pelo URL da instância do espaço de trabalho, por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com. Substitua <your-personal-access-token> pelos access tokens pessoal do Databricks, por exemplo, dapi12345678901234567890123456789012.

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

    Para criar um access token pessoal do Databricks, faça o seguinte:

    1. Em seu Databricks workspace, clique em seu nome de usuário Databricks na barra superior e selecione Settings (Configurações ) no menu suspenso.

    2. Clique em Desenvolvedor.

    3. Ao lado do access token, clique em gerenciar.

    4. Clique em Gerar novos tokens.

    5. (Opcional) Insira um comentário que o ajude a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem vida útil (não recomendado), deixe a caixa Duração (dias) vazia (em branco).

    6. Clique em Gerar.

    7. Copie o token exibido em um local seguro e clique em Concluído.

    Observação

    Certifique-se de salvar os tokens copiados em um local seguro. Não compartilhe seus tokens copiados com outras pessoas. Se você perder os tokens copiados, não poderá regenerar exatamente os mesmos tokens. Em vez disso, você deve repetir este procedimento para criar novos tokens. Se você perder os tokens copiados ou acreditar que os tokens foram comprometidos, o Databricks recomenda fortemente que você exclua imediatamente esses tokens do seu workspace clicando no ícone da lixeira (Revogar) ao lado dos tokens na página access tokens .

    Se não for possível criar ou usar tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou os tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do workspace ou o seguinte:

    Para obter formas adicionais de fornecer a URL workspace do Databricks e access tokens pessoal, consulte Autenticação no repositório Databricks SDK para R no GitHub.

    Importante

    Não adicione arquivos .Renviron aos sistemas de controle de versão, pois isso corre o risco de expor informações confidenciais, como access token pessoal do Databricks.

  2. Instale o pacote Databricks SDK para R. Por exemplo, no RStudio Desktop, na view Console (view > Move Focus to Console), execute os seguintes comandos, um por vez:

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

    Observação

    O pacote Databricks SDK para R não está disponível no CRAN.

  3. Adicione o código para referenciar o SDK do Databricks para R e listar todos os clusters em seu workspace do 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. execução do seu script. Por exemplo, no RStudio Desktop, no editor de script com o arquivo main.r de um projeto ativo, clique em Fonte > Fonte ou Fonte com Echo.

  5. A lista de clusters é exibida. Por exemplo, no RStudio Desktop, isso está na view Console .

Exemplos de código

Os exemplos de código a seguir demonstram como usar o Databricks SDK para R para criar e excluir clusters e criar Job.

Criar um clusters

Este exemplo de código cria clusters com a versão especificada do Databricks Runtime e o tipo de nó clusters . Esses clusters têm um worker e os clusters são encerrados automaticamente após 15 minutos de tempo de parada.

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

Excluir permanentemente um clusters

Este exemplo de código exclui permanentemente os clusters com o ID clusters especificado 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 Job

Este exemplo de código cria um Job do Databricks que pode ser usado para executar o Notebook especificado nos clusters especificados. Como esta execução de código, ele obtém o caminho do Notebookexistente, o ID clusters existentes e as configurações Job 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 = "")
)

Registro em log

O senhor pode usar o popular pacote logging para log mensagens. Esse pacote oferece suporte a vários níveis de registro e formatos personalizados do site log. O senhor pode usar esse pacote para log mensagens no console ou em um arquivo. Para log mensagens, faça o seguinte:

  1. Instale o pacote logging. Por exemplo, no RStudio Desktop, no Console view (view > Move Focus to Console), execute o seguinte comando:

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

  2. Inicialize o pacote de registro, defina onde log as mensagens e defina o nível de registro. Por exemplo, o código a seguir logs todas as mensagens ERROR e abaixo para o arquivo results.log.

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

  3. log mensagens conforme necessário. Por exemplo, o código a seguir logs qualquer erro 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)
})

Testes

Para testar seu código, o senhor pode usar estruturas de teste do R, como o testthat. Para testar seu código em condições simuladas sem chamar o endpoint Databricks REST API ou alterar o estado de sua conta ou espaço de trabalho Databricks, o senhor pode usar a biblioteca de simulação do R, como o mockery.

Por exemplo, dado o seguinte arquivo chamado 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 a seguir, denominado test-helpers.py, testa se a função createCluster retorna a resposta esperada. Em vez de criar um cluster no destino workspace, 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")
    }
  )
})