Databricks SDK for R

注

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

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

注

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

• The Databricks SDK for Python

• Databricks SDK for Java

• The Databricks SDK for Go

始める前に

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

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

  注

  R 用 Databricks SDK では、Databricks の個人用アクセストークン認証のみがサポートされています。

• R、およびオプションで R 互換の統合開発環境 (IDE)。 Databricks では RStudio デスクトップ を推奨し、この記事の手順で使用します。

R 用 Databricks SDK の使用を開始する

1. Databricks ワークスペースの URL と個人用アクセストークンを R プロジェクトのスクリプトで使用できるようにします。 たとえば、R プロジェクトの .Renviron ファイルに以下を追加できます。 <your-workspace-url> を ワークスペース インスタンスの URL(https://1234567890123456.7.gcp.databricks.comなど) に置き換えます。<your-personal-access-token> を Databricks の個人用アクセストークン (dapi12345678901234567890123456789012など) に置き換えます。

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

   Databricks個人用アクセストークンを作成するには、ワークスペース ユーザー向けの個人用アクセストークンDatabricksの手順に従ってください。

   Databricks ワークスペースの URL と個人用アクセストークンを指定するその他の方法については、GitHub の Databricks SDK for R リポジトリでの 認証 に関するページを参照してください。

   重要

   .Renviron ファイルをバージョン管理システムに追加すると、Databricks personal アクセストークンなどの機密情報が公開される危険性があるため、追加しないでください。

2. R パッケージ用の Databricks SDK をインストールします。 たとえば、RStudio Desktop のコンソール ビュー ([表示] > [コンソールへのフォーカスの移動]) で、次のコマンドを 1 つずつ実行します。

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

   注

   R パッケージの Databricks SDK は CRAN では使用できません。

3. R 用 Databricks SDK を参照し、Databricks ワークスペース内のすべてのクラスターを一覧表示するコードを追加します。 たとえば、プロジェクトの main.r ファイルでは、コードは次のようになります。

   require(databricks)
   
   client <- DatabricksClient()
   
   list_clusters(client)[, "cluster_name"]
   

4. スクリプトを実行します。 たとえば、RStudio Desktop で、プロジェクトの main.r ファイルがアクティブなスクリプト エディターで、[ソース > ソース] または [ エコー付きソース] をクリックします。

5. クラスターのリストが表示されます。 たとえば、RStudio デスクトップでは、これは コンソール ビューにあります。

コード例

次のコード例は、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 = "n2-highmem-4",
  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)

ジョブの作成

このコード例では、指定したクラスターで指定したノートブックを実行するために使用できる 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 パッケージを使用して、メッセージをログに記録できます。 このパッケージは、複数のログレベルとカスタムログ形式をサポートします。 このパッケージを使用して、メッセージをコンソールまたはファイルに記録できます。 メッセージをログに記録するには、次の操作を行います。

1. logging パッケージをインストールします。たとえば、RStudio Desktop のコンソールビュー ( [表示] > [フォーカスをコンソールに移動] ) で、次のコマンドを実行します。

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

2. logging パッケージをブートストラップし、メッセージを記録する場所を設定し、ログレベルを設定します。 たとえば、次のコードは、 ERROR 以下のすべてのメッセージを results.log ファイルに記録します。

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

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

   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 テスト フレームワークを使用できます。 Databricks REST API エンドポイントを呼び出したり、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 ドキュメント

• 実行時間の長い操作

• ページ分割された応答