Udostępnij za pośrednictwem

Zestaw SDK usługi Databricks dla języka R

  • Artykuł

Uwaga

W tym artykule opisano zestaw SDK usługi Databricks dla języka R by Databricks Labs, który jest w stanie eksperymentalnym. Aby przekazać opinię, zadawać pytania i zgłaszać problemy, użyj karty Problemy w repozytorium Zestawu SDK usługi Databricks dla języka R w usłudze GitHub.

Z tego artykułu dowiesz się, jak zautomatyzować operacje w obszarach roboczych usługi Azure Databricks i powiązanych zasobach przy użyciu zestawu SDK usługi Databricks dla języka R. Ten artykuł uzupełnia dokumentację zestawu SDK usługi Databricks dla języka R.

Uwaga

Zestaw SDK usługi Databricks dla języka R nie obsługuje automatyzacji operacji na kontach usługi Azure Databricks. Aby wywołać operacje na poziomie konta, użyj innego zestawu SDK usługi Databricks, na przykład:

Zanim rozpoczniesz

Przed rozpoczęciem korzystania z zestawu SDK usługi Databricks dla języka R maszyna deweloperna musi mieć następujące elementy:

  • Osobisty token dostępu usługi Azure Databricks dla docelowego obszaru roboczego usługi Azure Databricks, który chcesz zautomatyzować.

    Uwaga

    Zestaw SDK usługi Databricks dla języka R obsługuje tylko uwierzytelnianie osobistego tokenu dostępu usługi Azure Databricks.

  • Język R i opcjonalnie zintegrowane środowisko projektowe (IDE) zgodne z językiem R. Usługa Databricks zaleca program RStudio Desktop i używa go w instrukcjach tego artykułu.

Wprowadzenie do zestawu SDK usługi Databricks dla języka R

  1. Udostępnij adres URL obszaru roboczego usługi Azure Databricks i osobisty token dostępu skryptom projektu języka R. Możesz na przykład dodać następujący kod do pliku projektu .Renviron języka R. Zastąp <your-workspace-url> ciąg adresem URL obszaru roboczego, na przykład https://adb-1234567890123456.7.azuredatabricks.net. Zastąp <your-personal-access-token> ciąg osobistym tokenem dostępu usługi Azure Databricks, na przykład dapi12345678901234567890123456789012.

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

    Aby utworzyć osobisty token dostępu usługi Azure Databricks, wykonaj następujące czynności:

    1. W obszarze roboczym usługi Azure Databricks kliknij nazwę użytkownika usługi Azure Databricks na górnym pasku, a następnie wybierz pozycję Ustawienia z listy rozwijanej.
    2. Kliknij pozycję Deweloper.
    3. Obok pozycji Tokeny dostępu kliknij pozycję Zarządzaj.
    4. Kliknij pozycję Generuj nowy token.
    5. (Opcjonalnie) Wprowadź komentarz, który pomaga zidentyfikować ten token w przyszłości i zmienić domyślny okres istnienia tokenu na 90 dni. Aby utworzyć token bez okresu istnienia (niezalecane), pozostaw puste pole Okres istnienia (dni) (puste).
    6. Kliknij pozycję Generate (Generuj).
    7. Skopiuj wyświetlony token do bezpiecznej lokalizacji, a następnie kliknij przycisk Gotowe.

    Uwaga

    Pamiętaj, aby zapisać skopiowany token w bezpiecznej lokalizacji. Nie udostępniaj skopiowanego tokenu innym osobom. W przypadku utraty skopiowanego tokenu nie można wygenerować tego samego tokenu. Zamiast tego należy powtórzyć tę procedurę, aby utworzyć nowy token. Jeśli utracisz skopiowany token lub uważasz, że token został naruszony, usługa Databricks zdecydowanie zaleca natychmiastowe usunięcie tego tokenu z obszaru roboczego, klikając ikonę kosza (Odwołaj) obok tokenu na stronie Tokeny dostępu.

    Jeśli nie możesz utworzyć lub użyć tokenów w obszarze roboczym, może to być spowodowane tym, że administrator obszaru roboczego wyłączył tokeny lub nie udzielił Ci uprawnień do tworzenia lub używania tokenów. Zobacz administratora obszaru roboczego lub następujące elementy:

    Aby uzyskać dodatkowe sposoby udostępniania adresu URL obszaru roboczego usługi Azure Databricks i osobistego tokenu dostępu, zobacz Authentication in the Databricks SDK for R repository in GitHub (Uwierzytelnianie w repozytorium Zestawu SDK usługi Databricks dla języka R w usłudze GitHub).

    Ważne

    Nie należy dodawać .Renviron plików do systemów kontroli wersji, ponieważ wiąże się to z ryzykiem ujawnienia poufnych informacji, takich jak osobiste tokeny dostępu usługi Azure Databricks.

  2. Zainstaluj zestaw SDK usługi Databricks dla języka R. Na przykład w programie RStudio Desktop w widoku Konsola (Wyświetl > przenieś fokus do konsoli) uruchom następujące polecenia pojedynczo:

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

    Uwaga

    Zestaw SDK usługi Databricks dla języka R nie jest dostępny w usłudze CRAN.

  3. Dodaj kod, aby odwołać się do zestawu SDK usługi Databricks dla języka R i wyświetlić listę wszystkich klastrów w obszarze roboczym usługi Azure Databricks. Na przykład w pliku projektu main.r kod może być następujący:

    require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]

  4. Uruchom skrypt. Na przykład w programie RStudio Desktop w edytorze skryptów z aktywnym plikiem projektu kliknij pozycję Źródło źródłowe> lub Źródło z echo.main.r

  5. Zostanie wyświetlona lista klastrów. Na przykład w programie RStudio Desktop jest to w widoku Konsola.

Przykłady kodu

W poniższych przykładach kodu pokazano, jak używać zestawu SDK usługi Databricks dla języka R do tworzenia i usuwania klastrów oraz tworzenia zadań.

Tworzenie klastra

Ten przykładowy kod tworzy klaster z określoną wersją środowiska Databricks Runtime i typem węzła klastra. Ten klaster ma jeden proces roboczy, a klaster automatycznie kończy działanie po upływie 15 minut bezczynności.

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

Trwałe usuwanie klastra

Ten przykład kodu trwale usuwa klaster z określonym identyfikatorem klastra z obszaru roboczego.

require(databricks)

client <- DatabricksClient()

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

delete_cluster(client, cluster_id)

Tworzenie zadania

Ten przykładowy kod tworzy zadanie usługi Azure Databricks, które może służyć do uruchamiania określonego notesu w określonym klastrze. W miarę uruchamiania tego kodu pobiera on ścieżkę istniejącego notesu, istniejący identyfikator klastra i powiązane ustawienia zadania od użytkownika w konsoli programu .

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

Rejestrowanie

Do rejestrowania komunikatów można użyć popularnego logging pakietu. Ten pakiet zapewnia obsługę wielu poziomów rejestrowania i niestandardowych formatów dziennika. Za pomocą tego pakietu można rejestrować komunikaty w konsoli lub w pliku. Aby rejestrować komunikaty, wykonaj następujące czynności:

  1. Zainstaluj pakiet logging. Na przykład w programie RStudio Desktop w widoku Konsola (Wyświetl > przenieś fokus do konsoli) uruchom następujące polecenia:

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

  2. Uruchom pakiet rejestrowania, ustaw miejsce rejestrowania komunikatów i ustaw poziom rejestrowania. Na przykład poniższy kod rejestruje wszystkie ERROR komunikaty i poniżej do results.log pliku.

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

  3. W razie potrzeby rejestruje komunikaty. Na przykład poniższy kod rejestruje błędy, jeśli kod nie może uwierzytelnić lub wyświetlić listy nazw dostępnych klastrów.

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

Testowanie

Aby przetestować kod, możesz użyć platform testowych języka R, takich jak test. Aby przetestować kod w symulowanych warunkach bez wywoływania punktów końcowych interfejsu API REST usługi Azure Databricks lub zmieniania stanu kont lub obszarów roboczych usługi Azure Databricks, możesz użyć wyśmiewanych bibliotek języka R, takich jak pozorowanie.

Na przykład, biorąc pod uwagę następujący plik o nazwie helpers.r zawierającej funkcję zwracającą createCluster informacje o nowym klastrze:

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

I biorąc pod uwagę następujący plik o nazwie main.R , który wywołuje createCluster funkcję:

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)

Poniższy plik o nazwie test-helpers.py testuje, czy createCluster funkcja zwraca oczekiwaną odpowiedź. Zamiast tworzyć klaster w docelowym obszarze roboczym, ten test wyśmiewa DatabricksClient obiekt, definiuje wyśmiewane ustawienia obiektu, a następnie przekazuje pozorowany obiekt do createCluster funkcji. Następnie test sprawdza, czy funkcja zwraca oczekiwany identyfikator nowego wyśmiewanego klastra.

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

Dodatkowe zasoby

Aby uzyskać więcej informacji, zobacz: