Partilhar via

Databricks SDK para R

  • Artigo

Nota

Este artigo aborda o Databricks SDK for 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 Databricks SDK for R no GitHub.

Neste artigo, você aprenderá a automatizar operações em espaços de trabalho do Azure Databricks e recursos relacionados com o SDK do Databricks para R. Este artigo complementa a documentação do Databricks SDK for R.

Nota

O SDK do Databricks para R não oferece suporte à automação de operações em contas do Azure Databricks. Para chamar operações no nível da conta, use um SDK do Databricks diferente, por exemplo:

Antes de começar

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

  • Um token de acesso pessoal do Azure Databricks para o espaço de trabalho de destino do Azure Databricks que você deseja automatizar.

    Nota

    O SDK do Databricks para R dá suporte apenas à autenticação de token de acesso pessoal do Azure Databricks.

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

Introdução ao SDK do Databricks para R

  1. Disponibilize a URL do espaço de trabalho do Azure Databricks e o token de acesso pessoal para os scripts do seu projeto R. Por exemplo, você pode adicionar o seguinte ao arquivo de .Renviron um projeto R. Substitua <your-workspace-url> pelo URL por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net. Substitua <your-personal-access-token> pelo seu 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 seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
    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 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 tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
    6. Clique em Generate (Gerar).
    7. Copie o token exibido para um local seguro e clique em Concluído.

    Nota

    Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

    Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou o seguinte:

    Para obter maneiras adicionais de fornecer a URL do espaço de trabalho do Azure Databricks e o token de acesso pessoal, consulte Autenticação no repositório do SDK do Databricks para R no GitHub.

    Importante

    Não adicione .Renviron arquivos a sistemas de controle de versão, pois isso corre o risco de expor informações confidenciais, como tokens de acesso pessoal do Azure Databricks.

  2. Instale o pacote Databricks SDK for R. Por exemplo, no RStudio Desktop, na visualização Console (View > Move Focus to Console), execute os seguintes comandos, um de cada vez:

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

    Nota

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

  3. Adicione código para fazer referência ao SDK do Databricks para R e listar todos os clusters em seu espaço de trabalho do Azure Databricks. Por exemplo, no arquivo de main.r um projeto, o código pode ser o seguinte:

    require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]

  4. Execute o script. Por exemplo, no RStudio Desktop, no editor de scripts com o arquivo de main.r um projeto ativo, clique em Source > Source ou Source with Echo.

  5. A lista de clusters é exibida. Por exemplo, no RStudio Desktop, isso está na visualização Console .

Exemplos de código

Os exemplos de código a seguir demonstram como usar o Databricks SDK for 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. Esse cluster tem um trabalhador 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 permanentemente um cluster

Este exemplo de código exclui permanentemente o cluster com a ID de cluster especificada do espaço de trabalho.

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 usado para executar o bloco de anotações especificado no cluster especificado. À medida que esse código é executado, ele obtém o caminho do bloco de anotações existente, o 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 = "")
)

Registo

Você pode usar o pacote popular logging para registrar mensagens. Este pacote fornece suporte para vários níveis de log e formatos de log personalizados. Você pode usar este pacote para registrar mensagens no console ou em um arquivo. Para registrar mensagens, faça o seguinte:

  1. Instale o pacote logging. Por exemplo, no RStudio Desktop, na visualização Console (View > Move Focus to 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 ERROR mensagens e abaixo no results.log arquivo.

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

  3. Registre mensagens conforme necessário. Por exemplo, o código a seguir registra quaisquer 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)
})

Testar

Para testar seu código, você pode usar estruturas de teste 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 espaços de trabalho do Azure Databricks, você pode usar bibliotecas de simulação R, como simulação.

Por exemplo, dado o seguinte arquivo chamado helpers.r contendo uma createCluster função 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 createCluster função:

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 chamado test-helpers.py testa se a createCluster função retorna a resposta esperada. Em vez de criar um cluster no espaço de trabalho de destino, esse teste simula um DatabricksClient objeto, define as configurações do objeto simulado e, em seguida, passa o objeto simulado para a createCluster função. 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 obter mais informações, consulte: