Databricks SDK for R

Artikel
09/10/2024

Hinweis

In diesem Artikel wird das Databricks SDK für R von Databricks Labs behandelt, das sich im experimentellen Zustand befindet. Verwenden Sie die Registerkarte Probleme im Repository von Databricks SDK für R auf GitHub, um Feedback zu geben, Fragen zu stellen und Probleme zu melden.

In diesem Artikel erfahren Sie, wie Sie Vorgänge in Azure Databricks-Arbeitsbereichen und zugehörigen Ressourcen mit dem Databricks SDK für R automatisieren. Dieser Artikel ergänzt die Dokumentation zu Databricks SDK für R.

Hinweis

Das Databricks SDK für R unterstützt die Automatisierung von Vorgängen in Azure Databricks-Konten nicht. Verwenden Sie zum Aufrufen von Vorgängen auf Kontoebene ein anderes Databricks SDK, z. B.:

Voraussetzungen

Zur Verwendung des Databricks SDK für R muss Ihr Entwicklungscomputer die folgenden Voraussetzungen erfüllen:

Ein persönliches Zugriffstoken von Azure Databricks für den Azure Databricks-Zielarbeitsbereich, den Sie automatisieren möchten.

Hinweis

Das Databricks SDK für R unterstützt nur die Authentifizierung mit persönlichen Zugriffstoken von Azure Databricks.
R und optional eine R-kompatible integrierte Entwicklungsumgebung (IDE). Databricks empfiehlt RStudio Desktop und verwendet es in den Anweisungen in diesem Artikel.

Erste Schritte mit dem Databricks SDK für R

Stellen Sie die URL ihres Azure Databricks-Arbeitsbereichs und das persönliche Zugriffstoken für die Skripts Ihres R-Projekts zur Verfügung. Beispielsweise können Sie der .Renviron-Datei eines R-Projekts Folgendes hinzufügen. Ersetzen Sie <your-workspace-url> durch Ihre arbeitsbereichsspezifische URL, z. B. https://adb-1234567890123456.7.azuredatabricks.net. Ersetzen Sie <your-personal-access-token> durch Ihr persönliches Azure Databricks-Zugriffstoken, z. B. dapi12345678901234567890123456789012.
```
DATABRICKS_HOST=<your-workspace-url>
DATABRICKS_TOKEN=<your-personal-access-token>
```
Tun Sie Folgendes, um ein persönliches Azure Databricks-Zugriffstoken zu erstellen:
1. Wählen Sie in Ihrem Azure Databricks-Arbeitsbereich in der oberen Leiste Ihren Azure Databricks-Benutzernamen und dann im Dropdownmenü die Option Einstellungen aus.
2. Klicken Sie auf Entwickler.
3. Klicken Sie neben Zugriffstoken auf Verwalten.
4. Klicken Sie auf Neues Token generieren.
5. (Optional) Geben Sie einen Kommentar ein, durch den Sie dieses Token in Zukunft identifizieren können, und ändern Sie die standardmäßige Lebensdauer des Tokens von 90 Tagen. Wenn Sie ein Token ohne Gültigkeitsdauer erstellen möchten (nicht empfohlen), lassen Sie das Feld Lebensdauer (Tage) leer.
6. Klicken Sie auf Generate (Generieren) .
7. Kopieren Sie das angezeigte Token an einen sicheren Speicherort, und klicken Sie auf Fertig.
Hinweis

Achten Sie darauf, den kopierten Token an einem sicheren Ort zu speichern. Geben Sie das kopierte Token nicht an andere Personen weiter. Wenn Sie das kopierte Token verlieren, können Sie das gleiche Token nicht erneut generieren. Stattdessen müssen Sie erneut das Verfahren zum Erstellen eines neuen Tokens durchlaufen. Wenn Sie das kopierte Token verlieren oder glauben, dass das Token kompromittiert wurde, empfiehlt Databricks dringend, dass Sie das Token sofort aus Ihrem Arbeitsbereich löschen. Klicken Sie hierzu auf der Seite Zugriffstoken auf das Papierkorbsymbol (Widerrufen) neben dem Token.

Wenn Sie in Ihrem Arbeitsbereich keine Token erstellen oder verwenden können, liegt dies möglicherweise daran, dass Ihr Arbeitsbereichsadministrator Token deaktiviert hat oder Ihnen keine Berechtigung zum Erstellen oder Verwenden von Token erteilt hat. Wenden Sie sich an Ihren Arbeitsbereichsadministrator oder lesen Sie die folgenden Themen:
- Aktivieren oder Deaktivieren der Authentifizierung mit persönlichen Zugriffstoken für den Arbeitsbereich
- Berechtigungen für persönliche Zugriffstoken
Weitere Möglichkeiten zum Bereitstellen der URL ihres Azure Databricks-Arbeitsbereichs und des persönlichen Zugriffstokens finden Sie unter Authentifizierung im Databricks SDK für R-Repository in GitHub.

Wichtig

Fügen Sie keine .Renviron-Dateien zu Versionskontrollsystemen hinzu, da dies das Risiko birgt, dass sensible Informationen, wie z. B. persönliche Azure Databricks-Zugriffstoken, preisgegeben werden.
Installieren Sie das Databricks SDK für R-Paket. Führen Sie beispielsweise in RStudio Desktop in der Konsolenansicht (Ansicht > Fokus auf Konsole verschieben) die folgenden Befehle nacheinander aus:
```
install.packages("devtools")
library(devtools)
install_github("databrickslabs/databricks-sdk-r")
```
Hinweis

Das Databricks SDK für R-Paket ist in CRAN nicht verfügbar.
Fügen Sie Code hinzu, um auf das Databricks SDK für R zu verweisen und alle Cluster in Ihrem Azure Databricks-Arbeitsbereich auflisten zu können. In der main.r-Datei eines Projekts kann der Code z. B. wie folgt aussehen:
```
require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]
```
Führen Sie Ihr Skript aus. Klicken Sie zum Beispiel in RStudio Desktop im Skript-Editor bei aktiver main.r-Datei eines Projekts auf Quelle > Quelle oder Quelle mit Echo.
Die Liste der Cluster wird angezeigt. In RStudio Desktop befindet sich dies beispielsweise in der Konsolenansicht.

Codebeispiele

Die folgenden Codebeispiele veranschaulichen, wie Sie das Databricks SDK für R zum Erstellen und Löschen von Clustern und zum Erstellen von Aufträgen verwenden.

Erstellen eines Clusters
Dauerhaftes Löschen eines Clusters
Erstellen eines Auftrags

Erstellen eines Clusters

In diesem Codebeispiel wird ein Cluster mit der angegebenen Databricks Runtime-Version und dem angegebenen Clusterknotentyp erstellt. Dieser Cluster umfasst einen Worker, und der Cluster wird nach 15 Minuten Leerlauf automatisch beendet.

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

Dauerhaftes Löschen eines Clusters

In diesem Codebeispiel wird der Cluster mit der angegebenen Cluster-ID dauerhaft aus dem Arbeitsbereich gelöscht.

require(databricks)

client <- DatabricksClient()

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

delete_cluster(client, cluster_id)

Erstellen eines Auftrags

In diesem Codebeispiel wird ein Azure Databricks-Auftrag erstellt, der zum Ausführen des angegebenen Notebooks auf dem angegebenen Cluster verwendet werden kann. Bei Ausführung dieses Codes werden der Pfad des vorhandenen Notebooks, die ID des vorhandenen Clusters und die zugehörigen Auftragseinstellungen vom Benutzer an der Konsole abgerufen.

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

Sie können das beliebte logging Paket zum Protokollieren von Nachrichten verwenden. Dieses Paket bietet Unterstützung für mehrere Protokollierungsebenen und benutzerdefinierte Protokollformate. Sie können dieses Paket verwenden, um Nachrichten in der Konsole oder in einer Datei zu protokollieren. Gehen Sie wie folgt vor, um Nachrichten zu protokollieren:

Installieren Sie das logging-Paket. Führen Sie beispielsweise in RStudio Desktop in der Konsolenansicht (Ansicht > Fokus auf Konsole verschieben) die folgenden Befehle aus:
```
install.packages("logging")
library(logging)
```
Starten Sie das Protokollierungspaket, legen Sie fest, wo die Nachrichten protokolliert werden sollen, und legen Sie die Protokollierungsebene fest. Der folgende Code protokolliert beispielsweise alle ERROR Nachrichten und darunter in der results.log Datei.
```
basicConfig()
addHandler(writeToFile, file="results.log")
setLevel("ERROR")
```

Protokollieren Sie Nachrichten nach Bedarf. Der folgende Code protokolliert beispielsweise Fehler, wenn der Code die Namen der verfügbaren Cluster nicht authentifizieren oder auflisten kann.

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

Testen

Um Ihren Code zu testen, können Sie R-Testframeworks wie testthat verwenden. Um Ihren Code unter simulierten Bedingungen zu testen, ohne Azure Databricks-REST-API-Endpunkte aufzurufen oder den Status Ihrer Azure Databricks-Konten oder -Arbeitsbereiche zu ändern, können Sie R-Modellbibliotheken wie mockery verwenden.

Angenommen, die folgende Datei mit dem Namen helpers.r enthält eine createCluster-Funktion, die Informationen über den neuen Cluster zurückgibt:

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

Und die folgende Datei mit dem Namen main.R, die die createCluster Funktion aufruft:

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)

Die folgende Datei mit dem Namen test-helpers.py testet, ob die createCluster Funktion die erwartete Antwort zurückgibt. Anstatt einen Cluster im Zielarbeitsbereich zu erstellen, simuliert dieser Test ein DatabricksClient Objekt, definiert die Einstellungen des Pseudoobjekts und übergibt dann das Pseudoobjekt an die createCluster Funktion. Der Test überprüft dann, ob die Funktion die erwartete ID des neuen simulierten Clusters zurückgibt.

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

Zusätzliche Ressourcen

Weitere Informationen finden Sie unter:

Freigeben über

Databricks SDK for R

Voraussetzungen

Erste Schritte mit dem Databricks SDK für R

Codebeispiele

Erstellen eines Clusters

Dauerhaftes Löschen eines Clusters

Erstellen eines Auftrags

Logging

Testen

Zusätzliche Ressourcen

Feedback

Zusätzliche Ressourcen