Databricks CLI 的驗證

注意

此資訊適用於處於公開預覽狀態 的 Databricks CLI 0.205 版和更新版本。 若要尋找 Databricks CLI 版本請執行 databricks -v。

本文說明如何設定 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。

注意

Databricks CLI 會 實作 Databricks 用戶端統一驗證 標準，這是驗證的合並且一致的原型和程序設計方法。 這種方法有助於使用 Azure Databricks 更集中且可預測的方式來設定和自動化驗證。 它可讓您設定 Azure Databricks 驗證一次，然後在多個 Azure Databricks 工具和 SDK 之間使用該設定，而不需要進一步的驗證組態變更。 如需此標準的詳細資訊，請參閱 Databricks 用戶端整合驗證。

下列各節提供如何設定 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 驗證

若要建立個人存取令牌，請執行下列動作：

1. 在 Azure Databricks 工作區中，按兩下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取 [設定 ]。
2. 按兩下 [ 開發人員]。
3. 按兩下 [存取令牌] 旁的 [管理]。
4. 按一下 [產生新權杖]。
5. （選擇性）輸入批注，協助您在未來識別此令牌，並變更令牌的預設存留期 90 天。 若要建立沒有存留期的令牌（不建議），請將 [ 存留期（天）] 方塊保留空白（空白）。
6. 按一下 [產生]。
7. 將顯示的令牌複製到安全的位置，然後按兩下 [ 完成]。

注意

請務必將複製的令牌儲存在安全的位置。 請勿與其他人共享複製的令牌。 如果您遺失複製的令牌，就無法重新產生完全相同的令牌。 相反地，您必須重複此程式來建立新的令牌。 如果您遺失複製的令牌，或您認為令牌已遭入侵，Databricks 強烈建議您按兩下存取令牌頁面上令牌旁邊的垃圾桶 （Revoke） 圖示，立即從工作區中刪除該令牌。

如果您無法在工作區中建立或使用令牌，這可能是因為您的工作區系統管理員已停用令牌，或未授與您建立或使用令牌的許可權。 請參閱您的工作區管理員或下列專案：

• 啟用或停用工作區的個人存取令牌驗證
• 個人存取令牌許可權

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

注意

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

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

1. 使用 Databricks CLI 來執行下列命令：

   databricks configure
   

2. 如需提示 Databricks Host，請輸入您的 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。

3. 針對提示 個人存取令牌，輸入工作區的 Azure Databricks 個人存取令牌。

   輸入 Azure Databricks 個人存取令牌之後，會將對應的組態配置檔新增至您的 .databrickscfg 檔案。 如果 Databricks CLI 在其預設位置找不到此檔案，它會先為您建立此檔案，然後將此組態配置檔新增至新檔案。 此檔案的預設位置位於 ~ Unix、Linux 或 macOS 上的 [使用者首頁] 資料夾中，或 Windows %USERPROFILE% 上的 [使用者首頁] 資料夾。

4. 您現在可以使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks clusters list -p <configuration-profile-name>。

OAuth 計算機對電腦 （M2M） 驗證

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

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

1. 完成 OAuth M2M 驗證設定指示。 請參閱 使用服務主體向 Azure Databricks 進行驗證

2. 使用檔案.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，以及 %USERPROFILE% 適用於 Windows。

3. 使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   提示

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

OAuth 使用者對電腦 （U2M） 驗證

您可以使用 OAuth 驗證，而不是使用 令牌驗證向 Azure Databricks 進行驗證。 OAuth 提供比 Azure Databricks 個人存取令牌更快的到期時間，並提供更好的伺服器端會話失效和範圍界定。 由於 OAuth 存取令牌在不到一小時內到期，因此可降低不小心將令牌簽入原始檔控制的風險。 另 請參閱 OAuth 使用者對電腦 （U2M） 驗證。

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

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

   在下列命令中，取代下列佔位元：

   • 以您的 Azure Databricks https://accounts.azuredatabricks.net取代 <account-console-url> 。
   • 將 取代 <account-id> 為您的 Azure Databricks 帳戶標識碼。 請參閱 尋找您的帳戶標識碼。

   databricks auth login --host <account-console-url> --account-id <account-id>
   

2. Databricks CLI 會提示您將帳戶控制台 URL 和帳戶標識符儲存在本機作為 Azure Databricks 組態配置檔。 按 Enter 以接受建議的配置檔名稱，或輸入新或現有配置檔的名稱。 任何具有相同名稱的現有配置檔，會使用此帳戶控制台 URL 和帳戶標識碼覆寫。

   若要取得任何現有設定檔的清單，請在個別終端機或命令提示字元中執行 命令 databricks auth profiles。 若要檢視特定設定檔的現有設定，請執行 命令 databricks auth env --profile <profile-name>。

3. 在網頁瀏覽器中，完成登入 Azure Databricks 帳戶的畫面指示。

4. 若要檢視目前的 OAuth 令牌值和即將到期的時間戳，請執行 命令 databricks auth token --host <account-console-url> --account-id <account-id>。

5. 呼叫任何 Azure Databricks 工作區層級 命令之前，您必須先執行下列命令，在本機起始 OAuth 令牌管理。 您必須針對您要針對每個要執行命令的工作區，個別執行此命令。

   在下列命令中，將 取代 <workspace-url> 為您的 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。

   databricks auth login --host <workspace-url>
   

6. Databricks CLI 會提示您將工作區 URL 儲存為 Azure Databricks 組態配置檔。 按 Enter 以接受建議的配置檔名稱，或輸入新或現有配置檔的名稱。 任何具有相同名稱的現有配置檔，會使用此工作區 URL 覆寫。

   若要取得任何現有設定檔的清單，請在個別終端機或命令提示字元中執行 命令 databricks auth profiles。 若要檢視特定設定檔的現有設定，請執行 命令 databricks auth env --profile <profile-name>。

7. 在您的網頁瀏覽器中，完成登入 Azure Databricks 工作區的畫面指示。

8. 若要檢視目前的 OAuth 令牌值和即將到期的時間戳，請執行 命令 databricks auth token --host <workspace-url>。

9. 使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   提示

   您可以按 Tab 或 --profile -p 來顯示現有可用組態配置檔的清單，以從中選擇，而不是手動輸入組態配置檔名稱。

Azure 受控識別驗證

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

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

1. 建立或識別 Azure VM，並在其上安裝 Databricks CLI，然後將受控識別指派給 Azure VM 和目標 Azure Databricks 帳戶、工作區或兩者。 請參閱 設定及使用 Azure Databricks 自動化的 Azure 受控識別驗證。

2. 在 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 資源識別碼，而不是host與工作區 URL 一起指定azure_workspace_resource_id。 在此情況下，目標身分識別必須至少有 Azure 資源的參與者或擁有者許可權。

   注意

   檔案的預設位置 .databrickscfg 位於使用者的主目錄中。 這 ~ 適用於Linux和macOS，以及 %USERPROFILE% 適用於 Windows。

3. 在 Azure VM 上，使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱來設定 Databricks 要使用的設定檔，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   提示

   您可以按 Tab 或 --profile -p 來顯示現有可用組態配置檔的清單，以從中選擇，而不是手動輸入組態配置檔名稱。

Microsoft Entra ID 服務主體驗證

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

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

1. 使用檔案.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 資源識別符，而不是host與工作區 URL 一起指定azure_workspace_resource_id。 在此情況下，目標Microsoft Entra ID 服務主體必須至少有 Azure 資源的參與者或擁有者許可權。

   注意

   檔案的預設位置 .databrickscfg 位於使用者的主目錄中。 這 ~ 適用於Linux和macOS，以及 %USERPROFILE% 適用於 Windows。

2. 使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   提示

   您可以按 Tab 或 --profile -p 來顯示現有可用組態配置檔的清單，以從中選擇，而不是手動輸入組態配置檔名稱。

Azure CLI 驗證

Azure CLI 驗證會使用 Azure CLI 來驗證已登入的實體。 另 請參閱 Azure CLI 驗證。

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

1. 在本機安裝 Azure CLI。

2. 執行 命令，使用 Azure CLI 來登入 Azure Databricks az login 。 請參閱 使用 Azure Databricks 用戶帳戶的 Azure CLI 登入。

3. 使用檔案.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，以及 %USERPROFILE% 適用於 Windows。

4. 使用 Databricks CLI 的 --profile 或 -p 選項，後面接著組態設定檔的名稱，作為 Databricks CLI 命令呼叫的一部分，例如 databricks account groups list -p <configuration-profile-name> 或 databricks clusters list -p <configuration-profile-name>。

   提示

   您可以按 Tab 或 --profile -p 來顯示現有可用組態配置檔的清單，以從中選擇，而不是手動輸入組態配置檔名稱。

評估的驗證順序

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

1. 針對從套件組合工作目錄執行的任何命令（套件組合根目錄和任何巢狀路徑），專案套件組合設定檔內的欄位值。 （套件組合設定檔案不支援直接包含存取認證值。
2. 環境變數的值，如本文中所列，以及 客戶端統一驗證的環境變數和字段。
3. 檔案中的 .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 組態配置檔，以尋找包含 host 具有相符工作區 URL 之字段的配置檔。 Databricks CLI 會尋找相符 host 的欄位，然後使用該配置檔的 token 域值。