Databricks SDK for R

[アーティクル]
09/10/2024

Note

この記事では、実験状態の Databricks Labs による Databricks SDK for R への対応について説明します。フィードバックの提供、質問、問題の報告を行うには、GitHub の Databricks SDK for R リポジトリの [問題] タブを使用します。

この記事では、Databricks SDK for R を使用して Azure Databricks ワークスペースと関連リソースの操作を自動化する方法について説明します。この記事では、Databricks SDK for R のドキュメントを補足します。

Note

Databricks SDK for R では、Azure Databricks アカウントでの操作の自動化はサポートされていません。アカウントレベルの操作を呼び出すには、次に示すように別の Databricks SDK を使用します。

開始する前に

Databricks SDK for R の使用を開始する前に、開発マシンには次が必要です。

自動化するターゲットの Azure Databricks ワークスペース用の Azure Databricks 個人用アクセストークン。

Note

Databricks SDK for R では、Azure Databricks 個人用アクセストークン認証のみがサポートされています。
R、および必要に応じた R 互換の統合開発環境 (IDE)。 Databricks は RStudio Desktop を推奨しており、この記事の手順で使用します。

Databricks SDK for R を使ってみる

Azure Databricks ワークスペース URL と個人用アクセストークンを R プロジェクトのスクリプトで使用できるようにします。たとえば、R プロジェクトの .Renviron ファイルに次の内容を追加できます。 <your-workspace-url> をワークスペースごとの URL に置き換えます (例: https://adb-1234567890123456.7.azuredatabricks.net)。 <your-personal-access-token> は、dapi12345678901234567890123456789012 などの Azure Databricks 個人用アクセストークンに置き換えます。
```
DATABRICKS_HOST=<your-workspace-url>
DATABRICKS_TOKEN=<your-personal-access-token>
```
Azure Databricks 個人用アクセストークンを作成するには、以下を実行します。
1. Azure Databricks ワークスペースの上部バーで、目的の Azure Databricks ユーザー名をクリックし、次にドロップダウンから [設定] を選択します。
2. [開発者] をクリックします。
3. [アクセストークン] の横にある [管理] をクリックします。
4. [新しいトークンの生成] をクリックします。
5. (省略可能) 将来このトークンを識別するのに役立つコメントを入力し、トークンの既定の有効期間 90 日を変更します。有効期間のないトークンを作成するには (推奨されません)、[有効期間 (日)] ボックスを空のままにします。
6. [Generate](生成) をクリックします。
7. 表示されたトークンを安全な場所にコピーし、[完了] をクリックします。
Note

コピーしたトークンは必ず安全な場所に保存してください。コピーしたトークンは他人に見せないでください。コピーしたトークンを失った場合、それとまったく同じトークンは再生成できません。代わりに、この手順を繰り返して新しいトークンを作成する必要があります。コピーしたトークンを紛失した場合や、トークンが侵害されていると思われる場合、Databricks では、[アクセストークン] ページのトークンの横にあるごみ箱 ([取り消し]) アイコンをクリックして、ワークスペースからそのトークンをすぐに削除することを強くお勧めします。

ワークスペースでトークンを作成することや使用することができない場合は、ワークスペース管理者によってトークンが無効にされているか、トークンを作成または使用する権限が作業者に付与されていない可能性があります。ワークスペース管理者に連絡するか、以下のトピックを参照してください。
- ワークスペースの個人アクセストークン認証を有効または無効にする
- 個人用アクセストークンのアクセス許可
Azure Databricks ワークスペース URL と個人用アクセストークンを提供するその他の方法については、GitHub の Databricks SDK for R リポジトリの認証を参照してください。

重要

Azure Databricks 個人用アクセストークンなどの機密情報が公開されるリスクが高まるため、バージョンコントロールシステムに .Renviron ファイルを追加しないでください。
Databricks SDK for R パッケージをインストールします。たとえば、RStudio Desktop の [コンソール] ビュー ([表示] > [コンソールにフォーカスを移動]) で、次のコマンドを一度に 1 つずつ実行します。
```
install.packages("devtools")
library(devtools)
install_github("databrickslabs/databricks-sdk-r")
```
Note

Databricks SDK for R パッケージは CRAN では使用できません。
Databricks SDK for R を参照し、Azure Databricks ワークスペース内のすべてのクラスターを一覧表示するコードを追加します。たとえば、プロジェクトの main.r ファイルでは、コードは次のようになります。
```
require(databricks)

client <- DatabricksClient()

list_clusters(client)[, "cluster_name"]
```
スクリプトを実行します。たとえば、RStuidio Desktop では、プロジェクトの main.r ファイルがアクティブであるスクリプトエディターで、[ソース] > [ソース] または [エコーを含むソース] をクリックします。
クラスターの一覧が表示されます。たとえば、RStudio Desktop では、これは コンソール ビューにあります。

コード例

次のコード例は、Databricks SDK for R を使用して、クラスターを作成および削除し、ジョブを作成する方法を示しています。

クラスターの作成
クラスターを完全に削除する
ジョブを作成する

クラスターの作成

このコード例では、Databricks Runtime バージョンとクラスターノードの種類を指定してクラスターを作成します。このクラスターには 1 つのワーカーがあり、クラスターは 15 分のアイドル時間の後に自動的に終了します。

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

クラスターを完全に削除する

このコード例では、指定したクラスター ID のクラスターをワークスペースから完全に削除しています。

require(databricks)

client <- DatabricksClient()

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

delete_cluster(client, cluster_id)

ジョブの作成

このコード例では、指定したクラスターで指定したノートブックを実行するために使用可能な Azure Databricks ジョブを作成しています。このコードを実行すると、コンソールでユーザーから既存のノートブックのパス、既存のクラスター ID、および関連するジョブ設定が取得されます。

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 パッケージを使用して、メッセージをログに記録することができます。このパッケージでは、複数のログレベルとカスタムログ形式がサポートされます。このパッケージを使用して、コンソールまたはファイルにメッセージを記録できます。メッセージをログに記録するには、次のようにします。

logging パッケージをインストールします。たとえば、RStudio Desktop の [コンソール] ビュー ([表示] > [コンソールにフォーカスを移動]) で、次のコマンドを実行します。
```
install.packages("logging")
library(logging)
```
ログパッケージのブートストラップを実行し、メッセージを記録する場所を設定し、ログレベルを設定します。たとえば、次のコードは、ERROR 以下のメッセージを results.log ファイルに記録します。
```
basicConfig()
addHandler(writeToFile, file="results.log")
setLevel("ERROR")
```

必要に応じてメッセージをログに記録します。たとえば、次のコードは、コードで認証できない場合、または使用可能なクラスターの名前を一覧表示できない場合にエラーをログに記録します。

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

テスト

コードをテストするには、testthat などの R テストフレームワークを使用することができます。 Azure Databricks REST API エンドポイントを呼び出したり、Azure Databricks アカウントまたはワークスペースの状態を変更したりせずに、シミュレートされた条件下でコードをテストするには、mockery などの R モックライブラリを使用することができます。

たとえば、新しいクラスターに関する情報を返す createCluster 関数を含む、helpers.r という名前の次のファイルがあるとします。

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

また、createCluster 関数を呼び出す、main.R という名前の次のファイルがあるとします。

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)

test-helpers.py という名前の次のファイルは、createCluster 関数が、想定される応答を返すかどうかをテストします。このテストでは、ターゲットワークスペースにクラスターを作成するのではなく、DatabricksClient オブジェクトをモックし、モックオブジェクトの設定を定義し、モックオブジェクトを createCluster 関数に渡します。このテストでは次に、関数が、新しいモッククラスターの想定される ID を返すかどうかを確認します。

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

その他のリソース

詳細については、以下を参照してください:

次の方法で共有

Databricks SDK for R

開始する前に

Databricks SDK for R を使ってみる

コード例

クラスターの作成

クラスターを完全に削除する

ジョブの作成

ログ機能

テスト

その他のリソース

フィードバック

その他のリソース