Condividi tramite

Databricks SDK per R

  • Articolo

Nota

Questo articolo illustra Databricks SDK per R di Databricks Labs, che si trova in uno stato sperimentale . Per fornire commenti e suggerimenti, porre domande e segnalare i problemi, usare la scheda Problemi nel repository Databricks SDK per R in GitHub.

Questo articolo illustra come automatizzare le operazioni nelle aree di lavoro di Azure Databricks e nelle risorse correlate con Databricks SDK per R. Questo articolo integra la documentazione di Databricks SDK per R.

Nota

Databricks SDK per R non supporta l'automazione delle operazioni negli account Azure Databricks. Per chiamare operazioni a livello di account, usare un SDK di Databricks diverso, ad esempio:

Operazioni preliminari

Prima di iniziare a usare Databricks SDK per R, il computer di sviluppo deve avere:

  • Un token di accesso personale di Azure Databricks per l'area di lavoro di Azure Databricks di destinazione che si vuole automatizzare.

    Nota

    Databricks SDK per R supporta solo l'autenticazione del token di accesso personale di Azure Databricks.

  • R e, facoltativamente, un ambiente di sviluppo integrato compatibile con R(IDE). Databricks consiglia RStudio Desktop e lo usa nelle istruzioni di questo articolo.

Introduzione a Databricks SDK per R

  1. Rendere disponibile l'URL dell'area di lavoro di Azure Databricks e il token di accesso personale agli script del progetto R. Ad esempio, è possibile aggiungere quanto segue al file di .Renviron un progetto R. Sostituire <your-workspace-url> con l'URL per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net. Sostituire <your-personal-access-token> con il token di accesso personale di Azure Databricks, ad esempio dapi12345678901234567890123456789012.

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

    Per creare un token di accesso personale di Azure Databricks, seguire questa procedura:

    1. Nell'area di lavoro di Azure Databricks fare clic sul nome utente di Azure Databricks nella barra superiore e quindi selezionare Impostazioni dall'elenco a discesa.
    2. Fare clic su Sviluppatore.
    3. Accanto a Token di accesso fare clic su Gestisci.
    4. Fare clic su Genera nuovo token.
    5. (Facoltativo) Immettere un commento che consente di identificare questo token in futuro e modificare la durata predefinita del token di 90 giorni. Per creare un token senza durata (scelta non consigliata), lasciare vuota la casella Durata (giorni) (vuota).
    6. Fare clic su Genera.
    7. Copiare il token visualizzato in un percorso sicuro e quindi fare clic su Fine.

    Nota

    Assicurarsi di salvare il token copiato in un percorso sicuro. Non condividere il token copiato con altri utenti. Se si perde il token copiato, non è possibile rigenerare lo stesso token esatto. È invece necessario ripetere questa procedura per creare un nuovo token. Se si perde il token copiato o si ritiene che il token sia stato compromesso, Databricks consiglia vivamente di eliminare immediatamente il token dall'area di lavoro facendo clic sull'icona del cestino (Revoca) accanto al token nella pagina Token di accesso.

    Se non è possibile creare o usare token nell'area di lavoro, questo potrebbe essere dovuto al fatto che l'amministratore dell'area di lavoro ha disabilitato i token o non ha concesso l'autorizzazione per creare o usare token. Vedere l'amministratore dell'area di lavoro o quanto segue:

    Per altri modi per fornire l'URL dell'area di lavoro di Azure Databricks e il token di accesso personale, vedere Autenticazione nel repository Databricks SDK per R in GitHub.

    Importante

    Non aggiungere .Renviron file ai sistemi di controllo della versione, perché questo rischio comporta l'esposizione di informazioni riservate, ad esempio i token di accesso personali di Azure Databricks.

  2. Installare il pacchetto Databricks SDK per R. Ad esempio, in RStudio Desktop, nella visualizzazione Console (Visualizza > sposta lo stato attivo nella console), eseguire i comandi seguenti, uno alla volta:

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

    Nota

    Il pacchetto Databricks SDK per R non è disponibile in CRAN.

  3. Aggiungere il codice per fare riferimento a Databricks SDK per R ed elencare tutti i cluster nell'area di lavoro di Azure Databricks. Ad esempio, nel file di main.r un progetto il codice potrebbe essere il seguente:

    require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]

  4. Eseguire lo script. Ad esempio, in RStudio Desktop, nell'editor di script con il file di main.r un progetto attivo fare clic su Origine> origine o origine con Echo.

  5. Viene visualizzato l'elenco dei cluster. Ad esempio, in RStudio Desktop, si trova nella visualizzazione Console .

Esempi di codice

Gli esempi di codice seguenti illustrano come usare Databricks SDK per R per creare ed eliminare cluster e creare processi.

Creare un cluster

Questo esempio di codice crea un cluster con la versione di Databricks Runtime e il tipo di nodo del cluster specificati. Questo cluster ha un ruolo di lavoro e il cluster termina automaticamente dopo 15 minuti di inattività.

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

Eliminare definitivamente un cluster

Questo esempio di codice elimina definitivamente il cluster con l'ID cluster specificato dall'area di lavoro.

require(databricks)

client <- DatabricksClient()

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

delete_cluster(client, cluster_id)

Creare un processo

Questo esempio di codice crea un processo di Azure Databricks che può essere usato per eseguire il notebook specificato nel cluster specificato. Durante l'esecuzione di questo codice, ottiene il percorso del notebook esistente, l'ID cluster esistente e le impostazioni del processo correlate dall'utente nella 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 = "")
)

Registrazione

È possibile usare il pacchetto più diffuso logging per registrare i messaggi. Questo pacchetto offre supporto per più livelli di registrazione e formati di log personalizzati. È possibile usare questo pacchetto per registrare i messaggi nella console o in un file. Per registrare i messaggi, eseguire le operazioni seguenti:

  1. Installare il pacchetto logging. Ad esempio, in RStudio Desktop, nella visualizzazione Console (Visualizza > sposta lo stato attivo nella console), eseguire i comandi seguenti:

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

  2. Eseguire il bootstrap del pacchetto di registrazione, impostare dove registrare i messaggi e impostare il livello di registrazione. Ad esempio, il codice seguente registra tutti i ERROR messaggi e sotto al results.log file.

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

  3. Registrare i messaggi in base alle esigenze. Ad esempio, il codice seguente registra eventuali errori se il codice non è in grado di autenticare o elencare i nomi dei cluster disponibili.

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

Test in corso

Per testare il codice, è possibile usare framework di test R, ad esempio testat. Per testare il codice in condizioni simulate senza chiamare gli endpoint dell'API REST di Azure Databricks o modificare lo stato degli account o delle aree di lavoro di Azure Databricks, è possibile usare librerie di simulazione di R, ad esempio le simulazioni.

Ad esempio, dato il file seguente denominato helpers.r contenente una createCluster funzione che restituisce informazioni sul nuovo 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 dato il file seguente denominato main.R che chiama la createCluster funzione:

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)

Il file seguente denominato test-helpers.py verifica se la createCluster funzione restituisce la risposta prevista. Anziché creare un cluster nell'area di lavoro di destinazione, questo test simula un DatabricksClient oggetto, definisce le impostazioni dell'oggetto fittizio e quindi passa l'oggetto fittizio alla createCluster funzione. Il test verifica quindi se la funzione restituisce l'ID previsto del nuovo cluster fittizio.

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

Risorse aggiuntive

Per altre informazioni, vedi: