Databricks自動化における認証処理

[Authentication for Databricks automation \| Databricks on AWS](https://docs.databricks.com/dev-tools/auth.html) [2023/1/4時点]の翻訳です。

:::note warn
本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。
:::

Databricksにおいて、*認証*とは([ユーザー、サービスプリンシパル、グループ](https://docs.databricks.com/administration-guide/users-groups/index.html)などの)Databricksアイデンティティを検証することを意味します。Databricksでは、アイデンティティを検証するために(アクセストークンやユーザー名、パスワードなどの)*資格情報*を使用します。

Databricksが呼び出し元のアイデンティティを検証した後に、検証されたアイデンティティが指定された場所にあるリソースに対して十分な権限を有しているかどうかを特定するために、Databricksでは*承認*と呼ばれるプロセスを使用します。本書では承認の詳細については触れません。

ツールが自動化処理やAPIリクエストを行う際、Databricksでアイデンティティを認証する資格情報が含まれます。本書では、Databricksがリクエストの認証と承認に必要とする資格情報と関連情報を作成、格納、引き渡す際の典型的な方法を説明します。お使いのツール、スクリプト、アプリでサポートされている認証タイプ、関連情報、格納のメカニズムについてはプロバイダーのドキュメントを参照ください。

# Databricksパーソナルアクセストークン

Databricksのパーソナルアクセストークンは、特にDatabricksのワークスペースレベルのリソースとオペレーションを行う際には最もサポートが手厚いタイプの資格情報の一つです。資格情報および[環境変数](#環境変数)や[設定プロファイル](#設定プロファイル)のような関連情報に対する格納メカニズムの多くは、Databricksパーソナルアクセストークンを必要とします。一つのDatabricksワークスペースでは複数のパーソナルアクセストークンを設定することはできます、それぞれのパーソナルアクセストークンは単一のDatabricksワークスペースでのみ動作します。

- [ユーザーのパーソナルアクセストークン](#ユーザーのパーソナルアクセストークン)
- [サービスプリンシパルのパーソナルアクセストークン](#サービスプリンシパルのパーソナルアクセストークン)
- [パーソナルアクセストークンの管理](#パーソナルアクセストークンの管理)

## ユーザーのパーソナルアクセストークン

Databricksユーザー向けのDatabricksパーソナルアクセストークンを作成するには、以下の手順を実施します。

1. Databricksワークスペースでトップバーにある自身のDatabricksユーザー名をクリックし、ドロップダウンから**User Settings**を選択します。
1. **Access tokens**タブで**Generate new token**をクリックします。
1. (オプション)あとでトークンを識別できるようにコメントを入力し、デフォルト90日のトークンの有効期限を変更します。無期限のトークン(お勧めしません)を作成するには、**Lifetime (days)** のボックスを空にします。
1. **Generate**をクリックします。
1. 表示されたトークンをコピーし**Done**をクリックします。

:::note warn
**重要！**
コピーしたトークンはセキュアな場所に保存してください。コピーしたトークンを失くした場合、全く同じトークンを再生成することはできません。新規トークンを作成するためにこの手順を繰り返す必要があります。コピーしたトークンを失くした場合には、**Access tokens**タブで表示されるトークンの隣にある**X**をクリックすることで、即座にワークスペースからトークンを削除することをお勧めします。
:::

## サービスプリンシパルのパーソナルアクセストークン

DatabricksユーザーではなくDatabricksサービスプリンシパルのDatabricksパーソナルアクセストークンを作成するには、[Databricksオートメーションのためのサービスプリンシパル](https://qiita.com/taka_yayoi/items/265c1cbec8f00812e257)をご覧ください。

## パーソナルアクセストークンの管理

ワークスペース上のすべてのDatabricksパーソナルアクセストークンの有効化や無効化、ワークスペースで誰がトークンを使用できるのかのコントロール、ワークスペースにおけるトークンの最大有効期間の設定、ワークスペースにおけるその他のトークン管理オペレーションに関しては、[Databricksにおけるパーソナルアクセストークンの管理](https://qiita.com/taka_yayoi/items/712170ba2f2c2bdf5d24)をご覧ください。

# 環境変数

Databricksをサポートする製品やDatabricksと連携するいくつかのサードパーティ製品では、以下の固有の環境変数のいくつかをサポートしています。お使いのツール、スクリプト、アプリでどの環境変数がサポートされているのかに関しては、プロバイダーのドキュメントを参照してください。環境変数の作成、変更、削除に関してはオペレーティングシステムのドキュメントを参照してください。

| 環境変数 |
|:--|
| `DATABRICKS_ACCOUNT_ID` <br><br>DatabricksアカウントID。<br><br>[Databricks Terraformプロバイダー](https://qiita.com/taka_yayoi/items/691ee4909b0961de5ad1)でのみ適用されます。  |
| `DATABRICKS_ADDRESS`<br><br>DatabricksワークスペースのURL。<br><br>Databricksアカウントレベルのオペレーションにおいては、DatabricksアカウントコンソールのURLとなります。<br><br>サンプル:`https://dbc-a1b2345c-d6e7.cloud.databricks.com`、`https://accounts.cloud.databricks.com`<br><br>[Databricks Connect](https://qiita.com/taka_yayoi/items/a9781c0a871a5a4fcf2e)にのみ適用されます。  |
| `DATABRICKS_API_TOKEN`<br><br>Databricks[パーソナルアクセストークン](#databricksパーソナルアクセストークン)の値。<br><br>[Databricks Connect](https://qiita.com/taka_yayoi/items/a9781c0a871a5a4fcf2e)にのみ適用されます。  |
| `DATABRICKS_CLUSTER_ID` <br><br>DatabricksクラスターのID。<br><br>[Databricks Connect](https://qiita.com/taka_yayoi/items/a9781c0a871a5a4fcf2e)にのみ適用されます。 |
| `DATABRICKS_CONFIG_FILE` <br><br>Databricks[設定プロファイルのファイル](#設定プロファイル)へのフルパス。<br><br>デフォルト: Unix、Linux、macOSでは`~/.databrickscfg`、Windowsでは`%USERPROFILE%\.databrickscfg` |
| `DATABRICKS_CONFIG_PROFILE` <br><br>Databricks[設定プロファイルのファイル](#設定プロファイル)の名称。<br><br>デフォルト: `DEFAULT` |
| `DATABRICKS_DEBUG_HEADERS` <br><br>プロバイダーによるリクエストのデバッグHTTPヘッダーを出力するかどうか。<br><br>デフォルト: `false`<br><br>[Databricks Terraformプロバイダー](https://qiita.com/taka_yayoi/items/691ee4909b0961de5ad1)でのみ適用されます。|
| `DATABRICKS_DEBUG_TRUNCATE_BYTES`  <br><br>この制限を超えたHTTPリクエストやレスポンスtのJSONフィールドをこの長さに切り取ります。<br><br>デフォルト: `96`<br><br>[Databricks Terraformプロバイダー](https://qiita.com/taka_yayoi/items/691ee4909b0961de5ad1)でのみ適用されます。 |
| `DATABRICKS_DSN` <br><br>Databricks計算リソースに対するデータソース名(DSN)の接続文字列。<br><br> [Databricks SQL Driver for Go](https://docs.databricks.com/dev-tools/go-sql-driver.html)にのみ適用されます。|
| `DATABRICKS_HOST` <br><br>DatabricksワークスペースのURL。<br><br>Databricksアカウントレベルのオペレーションにおいては、DatabricksアカウントコンソールのURLとなります。<br><br>サンプル:`https://dbc-a1b2345c-d6e7.cloud.databricks.com`、`https://accounts.cloud.databricks.com` |
|  `DATABRICKS_ORG_ID` <br><br>Databricksワークスペースの組織ID。<br><br>[Databricks Connect](https://qiita.com/taka_yayoi/items/a9781c0a871a5a4fcf2e)にのみ適用されます。|
| `DATABRICKS_PASSWORD` <br><br>Databricksワークスペースユーザーのパスワード。 |
|  `DATABRICKS_PORT`<br><br>Databricksクラスターと通信するポート番号。<br><br>[Databricks Connect](https://qiita.com/taka_yayoi/items/a9781c0a871a5a4fcf2e)にのみ適用されます。 |
| `DATABRICKS_RATE_LIMIT` <br><br>秒間最大リクエスト数。<br><br>デフォルト: `15`<br><br>[Databricks Terraformプロバイダー](https://qiita.com/taka_yayoi/items/691ee4909b0961de5ad1)でのみ適用されます。 |
| `DATABRICKS_TOKEN` <br><br>Databricks[パーソナルアクセストークン](#databricksパーソナルアクセストークン)の値。 |
| `DATABRICKS_USERNAME` <br><br>Databricksワークスペースユーザーのユーザー名。 |
|  `DBSQLCLI_ACCESS_TOKEN`<br><br>Databricks[パーソナルアクセストークン](#databricksパーソナルアクセストークン)の値。<br><br>[Databricks SQL CLI](https://docs.databricks.com/dev-tools/databricks-sql-cli.html)にのみ適用されます。 |
| `DBSQLCLI_HOST_NAME`<br><br>Databricks SQLウェアハウスの**Server hostname**フィールドの値。 <br><br>例: `dbc-a1b2345c-d6e7.cloud.databricks.com`<br><br>[Databricks SQL CLI](https://docs.databricks.com/dev-tools/databricks-sql-cli.html)にのみ適用されます。 |
| `DBSQLCLI_HTTP_PATH` <br><br>Databricks SQLウェアハウスの**HTTP path**フィールドの値。 <br><br>例: `/sql/1.0/warehouses/1abc2d3456e7f890a`<br><br>[Databricks SQL CLI](https://docs.databricks.com/dev-tools/databricks-sql-cli.html)にのみ適用されます。 |
| `PERSONAL_ACCESS_TOKEN` <br><br>Databricks[パーソナルアクセストークン](#databricksパーソナルアクセストークン)の値。<br><br>[Apache Airflow integration with Databricks](https://docs.databricks.com/workflows/jobs/how-to-use-airflow-with-jobs.html)のみ適用されます。 |

# 設定プロファイル

Databricks*設定プロファイル*にはDatabricksが認証に必要とする設定とそのほかの上が格納されます。Databricks設定プロファイルは、使用するツール、スクリプト、アプリのDatabricks*設定プロファイルのファイル*に格納されます。お使いのツール、スクリプト、アプリでDatabricks設定プロファイルがサポートされているかどうかに関しては、プロバイダーのドキュメントを参照ください。

[Databricks CLI](https://docs.databricks.com/dev-tools/cli/index.html)を用いるか、あるいは手動で設定プロファイルのファイルを作成することができます。

- [設定プロファイルのファイルを作成するためにDatabricks CLIを使用](#設定プロファイルのファイルを作成するためにdatabricks-cliを使用)
- [手動で設定プロファイルのファイルを作成](#手動で設定プロファイルのファイルを作成)

## 設定プロファイルのファイルを作成するためにDatabricks CLIを使用

設定プロファイルのファイルを作成するためにDatabricks CLIを使用するには以下の手順を実施します。

:::note
**注意**
このアプローチでは、新規ファイルに`DEFAULT`という名前の設定プロファイルを持つ設定プロファイルのファイルを作成します。設定プロファイルのファイルがすでに存在する際には、ファイルの`DEFAULT`設定プロファイルは新規データで上書きされます。別の名称の設定プロファイルを作成するには、`databricks configure --token --profile DEV`というように、`--profile`オプションで新規設定プロファイル名を指定してください。
:::

1. Databricks CLIで以下のコマンドを実行します。

    ```bash:Bash
    databricks configure --token
    ```

1. プロンプトが表示されたら、`https://dbc-a1b2345c-d6e7.cloud.databricks.com`のような[ワークスペースインスタンスのURL](https://qiita.com/taka_yayoi/items/7127cabac70dd994fcba#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%82%BF%E3%83%B3%E3%82%B9%E5%90%8Durlid)を入力し、**Enter**を押します。
1. プロンプトが表示されたら、Databricks[パーソナルアクセストークン](#databricksパーソナルアクセストークン)を入力し、**Enter**を押します。

Databricks CLIが、Unix、Linux、macOSの場合は`~`フォルダ(ユーザーホーム)、Windowsの場合は`%USERPROFILE%`フォルダ(ユーザーホーム)に`.databrickscfg`というファイルが存在しない場合に作成します。Databricks CLIは`DEFAULT`という設定プロファイルが存在しない場合には作成し、この設定プロファイルに入力した情報を追加します。

## 手動で設定プロファイルのファイルを作成

手動でDatabricks設定プロファイルのファイルを作成するには、以下の手順を実行します。

1. Unix、Linux、macOSの場合は`~`フォルダ(ユーザーホーム)、Windowsの場合は`%USERPROFILE%`フォルダ(ユーザーホーム)に`.databrickscfg`というファイルをお好きなテキストエディタで作成します。ファイル名の先頭のドット(`.`)を忘れないようにしてください。このファイルに以下の内容を追加します。

    ```
    [<DEFAULT>]
    host = <your-workspace-url>
    token = <your-personal-access-token>
    ```

1. 上記の内容で、以下の値を置き換えてからファイルを保存します。

    - `<DEFAULT>`を`DEFAULT`、`DEV`、`PROD`のような一意なな設定プロファイルの名称で置き換えます。
    - `<your-workspace-url>`を`https://dbc-a1b2345c-d6e7.cloud.databricks.com`のような[ワークスペースインスタンスのURL](https://qiita.com/taka_yayoi/items/7127cabac70dd994fcba#%E3%83%AF%E3%83%BC%E3%82%AF%E3%82%B9%E3%83%9A%E3%83%BC%E3%82%B9%E3%81%AE%E3%82%A4%E3%83%B3%E3%82%B9%E3%82%BF%E3%83%B3%E3%82%B9%E5%90%8Durlid)で置き換えます。
    - `<your-personal-access-token>`をDatabricks[パーソナルアクセストークン](#databricksパーソナルアクセストークン)で置き換えます。

例えば、`.databrickscfg`ファイルは以下のようになります。

```
[DEFAULT]
host = https://dbc-a1b2345c-d6e7.cloud.databricks.com
token = dapi12345678901234567890123456789012
```

:::note
**ティップス**
以下のように同じ`.databrickscfg`ファイルに別々のプロファイル名を指定することで追加の設定プロファイルを作成することができます。

```
[DEFAULT]
host = https://dbc-a1b2345c-d6e7.cloud.databricks.com
token = dapi12345678901234567890123456789012

[DEV]
host = https://dbc-b2c3456d-e7f8.cloud.databricks.com
token = dapi23456789012345678901234567890123
```
:::

# ODBC DSN

ODBCにおいては、*データソース名(DSN)*はODBCデータソースに接続をリクエストするためにツール、スクリプト、アプリが使用するシンボル名となります。DSNにはODBCドライバーへのパス、ネットワークの詳細、認証資格情報、データベース詳細のような接続詳細情報が格納されます。お使いのツール、スクリプト、アプリでODBC DSNがサポートされているかどうかはプロバイダーのドキュメントを参照してください。

[Databricks ODBC Driver](https://www.databricks.com/spark/odbc-drivers-download)のインストールと設定、Databricks用ODBC DSNの作成方法に関しては、[ODBC driver](https://docs.databricks.com/integrations/jdbc-odbc-bi.html#odbc)をご覧ください。

# JDBC接続URL

JDBCにおいては、*接続URL*はJDBCデータソースに接続をリクエストするためにツール、スクリプト、アプリが使用するシンボル名となります。接続URLにはネットワークの詳細、認証資格情報、データベース詳細、JDBCドライバーの能力のような接続詳細情報が格納されます。お使いのツール、スクリプト、アプリでJDBC接続URLがサポートされているかどうかはプロバイダーのドキュメントを参照してください。

[Databricks JDBC Driver](https://www.databricks.com/spark/jdbc-drivers-download)のインストールと設定、Databricks用JDBC接続URLの作成方法に関しては、[JDBC driver](https://docs.databricks.com/integrations/jdbc-odbc-bi.html#jdbc)をご覧ください。


### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)