Databricks CLI 的驗證

注意

此資訊適用於 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 驗證

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

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

注意

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

注意：如果您無法在工作區中建立或使用 PAT，這可能是因為您的工作區系統管理員已停用權杖，或未授與您建立或使用權杖的權限。 請諮詢您的工作區系統管理員或參閱下列主題：

• 為工作區啟用或停用個人存取權杖驗證
• 個人存取權杖權限

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

注意

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

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

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

   databricks configure
   

2. 對於提示 Databricks 主機，輸入 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 存取權杖會在不到一小時內到期，因此可降低不小心將權杖簽入原始檔控制的風險。 另請參閱使用 OAuth (OAuth M2M) 透過服務主體對 Azure Databricks 的存取進行驗證。

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

1. 完成 OAuth M2M 驗證設定指示。 請參閱使用 OAuth (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 的 ~，以及適用於 Windows 的 %USERPROFILE%。

3. 可以使用 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 驗證，則執行下列動作：

1. 在呼叫任何 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>
   

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 個別工作區網址，例如 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>。

   提示

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

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_workspace_resource_id 與 Azure 資源識別碼，而不是 host 與工作區網址。 在此情況下，目標身分識別必須至少對 Azure 資源擁有參與者或擁有者權限。

   注意

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

3. 在 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 驗證。 您還必須執行下列工作：

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_workspace_resource_id 與 Azure 資源識別碼，而不是 host 與工作區網址。 在此情況下，目標 Microsoft Entra ID 服務主體必須至少對 Azure 資源擁有參與者或擁有者權限。

   注意

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

2. 可以使用 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 驗證，必須執行下列動作：

1. 已在本機安裝 Azure CLI。

2. 執行 az login 命令，使用 Azure CLI 來登入 Azure Databricks。 請參閱使用 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 的 ~，以及適用於 Windows 的 %USERPROFILE%。

4. 可以使用 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 工作區或帳戶進行驗證時，它會依下列順序搜尋下列位置的這些設定。

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 檔案內的組態設定檔，以尋找包含具有相符工作區 URL 之 host 欄位的設定檔。 Databricks CLI 會尋找相符的 host 欄位，然後使用該設定檔的 token 欄位值。