Databricks CLI 的驗證

發行項
11/16/2024

注意

此資訊適用於 Databricks CLI 0.205 版和更新版本。 Databricks CLI 處於公開預覽狀態。

Databricks CLI 使用受限於 Databricks 授權和 Databricks 隱私權注意事項，包括任何使用量數據布建。

本文介紹了如何設定 Databricks CLI 與 Azure Databricks 帳戶和工作區之間的驗證。請參閱什麼是 Databricks CLI？。

本文假設您已安裝 Databricks CLI。請參閱安裝或更新 Databricks CLI。

執行 Databricks CLI 命令之前，您必須根據想要執行的 CLI 類型，設定 Databricks CLI 與 Azure Databricks 帳戶、工作區或這些命令的組合之間的驗證。

您必須在執行階段向相關資源驗證 Databricks CLI，才能在 Azure Databricks 帳戶或工作區內執行 Azure Databricks 自動化命令。根據您是否想要呼叫 Azure Databricks 工作區層級命令和/或 Azure Databricks 帳戶層級命令，您必須向 Azure Databricks 工作區和/或帳戶進行驗證。如需 Azure Databricks 工作區層級和帳戶層級 CLI 命令群組的清單，請執行命令 databricks -h。如需 Databricks CLI 命令涵蓋的 Azure Databricks 工作區層級與帳戶層級 REST API 作業清單，請參閱 Databricks REST API。

如需有關具體使用 Azure DevOps 對 Databricks 進行 Microsoft Entra 驗證的資訊，請參閱使用 Databricks 上的 Azure DevOps 進行驗證。

下列各節提供如何設定 Databricks CLI 與 Azure Databricks 之間驗證的相關資訊：

Azure Databricks 個人存取權杖驗證
OAuth 機器對機器 (M2M) 驗證
OAuth 使用者對機器 (U2M) 驗證
Azure 受控識別驗證
Microsoft Entra ID 服務主體驗證
Azure CLI 驗證
評估的驗證順序

Azure Databricks 個人存取權杖驗證

Azure Databricks 個人存取權杖驗證會使用 Azure Databricks 個人存取權杖來驗證目標 Azure Databricks 實體，例如 Azure Databricks 使用者帳戶。請參閱 Azure Databricks 個人存取權杖驗證。

注意

您無法使用 Azure Databricks 個人存取權杖驗證來向 Azure Databricks 帳戶進行驗證，因為 Azure Databricks 帳戶層級命令不會使用 Azure Databricks 個人存取權杖進行驗證。若要使用 Azure Databricks 帳戶進行驗證，考慮改用下列其中一種驗證類型：

OAuth 機器對機器 (M2M) 驗證
OAuth 使用者對機器 (U2M) 驗證
Azure 受控識別驗證
Microsoft Entra ID 服務主體驗證
Azure CLI 驗證

若要建立個人存取令牌，請遵循適用於工作區使用者的 Azure Databricks 個人存取令牌中的步驟。

注意

下列程序會建立名稱為 DEFAULT 的 Azure Databricks 組態設定檔。如果您已經有要使用的 DEFAULT 組態設定檔，請略過此程序。否則，此程序會覆寫您現有的 DEFAULT 組態設定檔。若要檢視任何現有組態設定檔的名稱和主機，請執行 databricks auth profiles 命令。

若要使用 DEFAULT 以外的名稱建立組態設定檔，請將 --profile <configuration-profile-name> 或 -p <configuration-profile-name> 新增至下列 databricks configure 命令的結尾，並將 <configuration-profile-name> 取代為新的組態設定檔名稱。

若要設定及使用 Azure Databricks 個人存取權杖驗證，請執行下列動作：

使用 Databricks CLI 執行下列命令：
```
databricks configure
```
對於提示 Databricks 主機，輸入 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
對於提示個人存取權杖，輸入工作區的 Azure Databricks 個人存取權杖。

輸入 Azure Databricks 個人存取權杖之後，會將對應的組態設定檔新增至您的 .databrickscfg 檔案。如果 Databricks CLI 在其預設位置找不到此檔案，會先為您建立此檔案，然後將此組態設定檔新增至新檔案。此檔案的預設位置位於 Unix、Linux 或 macOS 上的 ~ (使用者首頁) 資料夾，或 Windows 上的 %USERPROFILE% (使用者首頁) 資料夾。
您現在可以使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks clusters list -p <configuration-profile-name>。

OAuth 機器對機器 (M2M) 驗證

您可以使用 OAuth 驗證，而不是使用 Azure Databricks 個人存取權杖驗證向 Azure Databricks 進行驗證。 OAuth 提供比 Azure Databricks 個人存取權杖更快的到期時間，並提供更好的伺服器端工作階段失效和範圍界定。由於 OAuth 存取權杖會在不到一小時內到期，因此可降低不小心將權杖簽入原始檔控制的風險。另請參閱使用 OAuth (OAuth M2M) 透過服務主體對 Azure Databricks 的存取進行驗證。

若要設定及使用 OAuth M2M 驗證，則執行下列動作：

完成 OAuth M2M 驗證設定指示。請參閱使用 OAuth (OAuth M2M) 透過服務主體對 Azure Databricks 的存取進行驗證
使用 .databrickscfg 檔案中的下列欄位，建立或識別 Azure Databricks 組態設定檔。如果您建立設定檔，請將預留位置取代為適當的值。

針對帳戶層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host          = <account-console-url>
account_id    = <account-id>
client_id     = <service-principal-client-id>
client_secret = <service-principal-oauth-secret>
```
針對工作區層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-oauth-secret>
```
注意

.databrickscfg 檔案的預設位置位於使用者的主目錄中。這是適用於 Linux 和 macOS 的 ~，以及適用於 Windows 的 %USERPROFILE%。
可以使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

提示

在 --profile 或 -p 之後按 Tab 以顯示現有可用組態設定檔的清單，以從中選擇，而不是手動輸入組態設定檔名稱。

OAuth 使用者對機器 (U2M) 驗證

您可以使用 OAuth 驗證，而不是使用權杖驗證向 Azure Databricks 進行驗證。 OAuth 提供比 Azure Databricks 個人存取權杖更快的到期時間，並提供更好的伺服器端工作階段失效和範圍界定。由於 OAuth 存取權杖會在不到一小時內到期，因此可降低不小心將權杖簽入原始檔控制的風險。另請參閱使用 OAuth (OAuth U2M) 透過使用者帳戶對 Azure Databricks 的存取進行驗證。

若要設定及使用 OAuth U2M 驗證，則執行下列動作：

在呼叫任何 Azure Databricks 帳戶層級命令之前，您必須執行下列命令，在本機起始 OAuth 權杖管理。您必須針對要執行命令的每個帳戶，單獨執行此命令。如果您不想呼叫任何帳戶層級作業，請直接跳到步驟 5。

在下列命令中，取代下列預留位置：
- 將 <account-console-url> 取代為您的 Azure Databricks https://accounts.azuredatabricks.net。
- 將 <account-id> 取代為您的 Azure Databricks 帳戶識別碼。請參閱尋找您的帳戶識別碼。
```
databricks auth login --host <account-console-url> --account-id <account-id>
```
Databricks CLI 會提示您將帳戶主控台 URL 和帳戶識別碼儲存在本機作為 Azure Databricks 組態設定檔。按 Enter 以接受建議的設定檔名稱，或輸入新或現有設定檔的名稱。任何具有相同名稱的現有設定檔，會使用此帳戶主控台 URL 和帳戶識別碼覆寫。

若要取得任何現有設定檔的清單，請在個別的終端機或命令提示字元中，執行 databricks auth profiles 命令。若要檢視特定設定檔的現有設定，請執行 databricks auth env --profile <profile-name> 命令。
在網頁瀏覽器中，完成畫面上的指示，登入 Azure Databricks 帳戶。
若要檢視目前的 OAuth 權杖值和即將到期時間戳記，請執行命令 databricks auth token --host <account-console-url> --account-id <account-id>。
在呼叫任何 Azure Databricks 工作區層級命令之前，您必須執行下列命令，在本機起始 OAuth 權杖管理。您必須針對要執行命令的每個工作區，單獨執行此命令。

在下列命令中，將 <workspace-url> 取代為您的 Azure Databricks 個別工作區網址，例如 https://adb-1234567890123456.7.azuredatabricks.net。
```
databricks auth login --host <workspace-url>
```
Databricks CLI 會提示您將工作區 URL 儲存在本機作為 Azure Databricks 組態設定檔。按 Enter 以接受建議的設定檔名稱，或輸入新或現有設定檔的名稱。對於任何具有相同名稱的現有設定檔，會使用此工作區 URL 覆寫。

若要取得任何現有設定檔的清單，請在個別的終端機或命令提示字元中，執行 databricks auth profiles 命令。若要檢視特定設定檔的現有設定，請執行 databricks auth env --profile <profile-name> 命令。
在網頁瀏覽器中，完成畫面上的指示，登入 Azure Databricks 工作區。
若要檢視目前的 OAuth 權杖值和即將到期時間戳記，請執行命令 databricks auth token --host <workspace-url>。
可以使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

提示

可以在 --profile 或 -p 之後按 Tab 以顯示現有可用組態設定檔的清單，以從中選擇，而不是手動輸入組態設定檔名稱。

Azure 受控識別驗證

Azure 受控識別驗證會使用 Azure 資源受控識別 (先前稱為受控服務識別 (MSI)) 進行驗證。請參閱什麼是 Azure 資源受控識別？。另請參閱 Azure 受控識別驗證。

若要建立 Azure 使用者指派的受控識別，請執行下列動作：

建立或識別 Azure VM，並在其上安裝 Databricks CLI，然後將受控識別指派給 Azure VM 和目標 Azure Databricks 帳戶和/或工作區。請參閱設定及使用 Azure Databricks 自動化的 Azure 受控識別驗證。
在 Azure VM 上，使用 .databrickscfg 檔案中的下列欄位，建立或識別 Azure Databricks 組態設定檔。如果您建立設定檔，請將預留位置取代為適當的值。

針對帳戶層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host            = <account-console-url>
account_id      = <account-id>
azure_client_id = <azure-managed-identity-application-id>
azure_use_msi   = true
```
針對工作區層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host            = <workspace-url>
azure_client_id = <azure-managed-identity-application-id>
azure_use_msi   = true
```
針對工作區層級命令，如果尚未將目標身分識別新增至工作區，則請指定 azure_workspace_resource_id 與 Azure 資源識別碼，而不是 host 與工作區網址。在此情況下，目標身分識別必須至少對 Azure 資源擁有參與者或擁有者權限。

注意

.databrickscfg 檔案的預設位置位於使用者的主目錄中。這是適用於 Linux 和 macOS 的 ~，以及適用於 Windows 的 %USERPROFILE%。
在 Azure VM 上，使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱來設定 Databricks 要使用的設定檔，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

提示

可以在 --profile 或 -p 之後按 Tab 以顯示現有可用組態設定檔的清單，以從中選擇，而不是手動輸入組態設定檔名稱。

Microsoft Entra ID 服務主體驗證

Microsoft Entra ID 服務主體驗證會使用 Microsoft Entra ID 服務主體的認證進行驗證。若要建立及管理 Azure Databricks 的服務主體，請參閱管理服務主體。另請參閱 MS Entra 服務主體驗證。

若要設定及使用 Microsoft Entra ID 服務主體驗證，必須在本機安裝 Azure CLI 驗證。您還必須執行下列工作：

使用 .databrickscfg 檔案中的下列欄位，建立或識別 Azure Databricks 組態設定檔。如果您建立設定檔，請將預留位置取代為適當的值。

針對帳戶層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host                = <account-console-url>
account_id          = <account-id>
azure_tenant_id     = <azure-service-principal-tenant-id>
azure_client_id     = <azure-service-principal-application-id>
azure_client_secret = <azure-service-principal-client-secret>
```
針對工作區層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host                = <workspace-url>
azure_tenant_id     = <azure-service-principal-tenant-id>
azure_client_id     = <azure-service-principal-application-id>
azure_client_secret = <azure-service-principal-client-secret>
```
針對工作區層級命令，如果尚未將目標 Microsoft Entra ID 服務主體新增至工作區，則請指定 azure_workspace_resource_id 與 Azure 資源識別碼，而不是 host 與工作區網址。在此情況下，目標 Microsoft Entra ID 服務主體必須至少對 Azure 資源擁有參與者或擁有者權限。

注意

.databrickscfg 檔案的預設位置位於使用者的主目錄中。這是適用於 Linux 和 macOS 的 ~，以及適用於 Windows 的 %USERPROFILE%。
可以使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

提示

可以在 --profile 或 -p 之後按 Tab 以顯示現有可用組態設定檔的清單，以從中選擇，而不是手動輸入組態設定檔名稱。

Azure CLI 驗證

Azure CLI 驗證會使用 Azure CLI 來對登入實體進行驗證。另請參閱 Azure CLI 驗證。

若要設定 Azure CLI 驗證，必須執行下列動作：

已在本機安裝 Azure CLI。
執行 az login 命令，使用 Azure CLI 來登入 Azure Databricks。請參閱使用 Azure Databricks 使用者帳戶的 Azure CLI 登入。
使用 .databrickscfg 檔案中的下列欄位，建立或識別 Azure Databricks 組態設定檔。如果您建立設定檔，請將預留位置取代為適當的值。

針對帳戶層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host       = <account-console-url>
account_id = <account-id>
```
針對工作區層級命令，請在您的 .databrickscfg 檔案中設定下列值：
```
[<some-unique-configuration-profile-name>]
host = <workspace-url>
```
注意

.databrickscfg 檔案的預設位置位於使用者的主目錄中。這是適用於 Linux 和 macOS 的 ~，以及適用於 Windows 的 %USERPROFILE%。
可以使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

提示

可以在 --profile 或 -p 之後按 Tab 以顯示現有可用組態設定檔的清單，以從中選擇，而不是手動輸入組態設定檔名稱。

評估的驗證順序

每當 Databricks CLI 需要收集所需設定，以便嘗試向 Azure Databricks 工作區或帳戶進行驗證時，它會依下列順序搜尋下列位置的這些設定。

針對從套件組合工作目錄執行的任何命令 (套件組合根目錄和任何巢狀路徑)，專案套件組合設定檔內的欄位值。 (套件組合設定檔案不支援直接包含存取認證值。)
環境變數的值，如本文中以及用戶端統一驗證的環境變數和欄位中所列。
.databrickscfg 檔案中的組態設定檔欄位值，如本文先前所列。

每當 Databricks CLI 找到所需的設定時，就會停止在其他位置進行搜尋。例如：

Databricks CLI 需要 Azure Databricks 個人存取權杖的值。 DATABRICKS_TOKEN 環境變數已設定，而且 .databrickscfg 檔案也包含多個個人存取權杖。在此範例中，Databricks CLI 會使用 DATABRICKS_TOKEN 環境變數的值，而且不會搜尋 .databrickscfg 檔案。
databricks bundle deploy -t dev 命令需要 Azure Databricks 個人存取權杖的值。 DATABRICKS_TOKEN 環境變數未設定，而且 .databrickscfg 檔案包含多個個人存取權杖。專案的套件組合設定檔包含 dev 環境宣告，可透過其 profile 欄位參考名為 DEV 的組態設定檔。在此範例中，Databricks CLI 會搜尋名為 .databrickscfg 的設定檔 DEV 檔案，並使用該設定檔 token 欄位的值。
databricks bundle run -t dev hello-job 命令需要 Azure Databricks 個人存取權杖的值。 DATABRICKS_TOKEN 環境變數未設定，而且 .databrickscfg 檔案包含多個個人存取權杖。專案的套件組合設定檔包含 dev 環境宣告，可透過其 host 欄位參考特定的 Azure Databricks 工作區 URL。在此範例中，Databricks CLI 會搜尋 .databrickscfg 檔案內的組態設定檔，以尋找包含具有相符工作區 URL 之 host 欄位的設定檔。 Databricks CLI 會尋找相符的 host 欄位，然後使用該設定檔的 token 欄位值。

共用方式為