使用 Azure Databricks 個人訪問權杖進行驗證（舊版）

Azure Databricks 的個人存取權杖（PAT）讓你在工作空間層級認證資源和 API。 你可以將它們儲存在環境變數或 Azure Databricks 設定檔。 每個 PAT 僅對一個工作區有效，而且使用者最多可以為每個工作區建立 600 個 PAT。 Azure Databricks 會自動撤銷 90 天內未使用的 PAT。

這很重要

Databricks 建議在可能的情況下使用 OAuth 取代 PAT 來進行使用者帳號驗證，因為 OAuth 提供更強的安全性。 想了解如何使用 OAuth 與 Databricks 使用者帳號進行認證，請參見 授權使用者存取 OAuth 的 Azure Databricks。

你不能用個人存取權杖來自動化Azure Databricks 帳號層級功能。 相反地，請使用 Azure Databricks 帳號管理員的 Microsoft Entra ID 令牌。 Azure Databricks 帳號管理員可以是使用者或服務主體。 如需詳細資訊，請參閱：

為工作區使用者建立個人存取權杖

要為你的 Azure Databricks Workspace 使用者建立個人存取權杖，請執行以下操作：

  1. 在你的Azure Databricks工作區，點擊頂欄的使用者名稱，選擇Settings。
  2. 按一下 開發人員。
  3. 在 [存取權杖] 旁，按一下 [管理]。
  4. 點選 產生新的權杖。
  5. 輸入一個名稱，幫助你日後辨識這個代幣。
  6. 以天為單位設定令牌的存留期。 請參閱 設定新個人存取權杖的最大壽命。
  7. 選擇一個範疇類型並新增 API 範圍。 選擇 BI Tools，以連接 Databricks SQL 倉庫（如 Tableau 或 Power BI）的工具，或選擇 Other APIS 手動選擇範圍。 請參見 Scoped 個人存取令牌。
  8. 若要為此權杖啟用自動範圍設定，請開啟 自動範圍權杖。 Auto-scoping 會自動將令牌的範圍縮小至其所使用的 API，並在觀察期間暫時套用 all-apis 範圍。 此選項僅在管理員啟用工作區自動範圍預覽時出現，且自動範圍僅適用於壽命超過 30 天的代幣。 請參閱 自動識別個人存取令牌。
  9. 點選 「」 生成 「」。
  10. 將顯示的權杖複製到安全位置，然後按一下「完成」。 安全地保存令牌，不要共享它。 如果您遺失了它，則必須建立一個新的令牌。

如果您無法建立或使用權杖，您的工作區系統管理員可能已停用權杖或未授與您權限。 請參閱您的工作區管理員或以下內容：

範圍化個人存取令牌

有範圍的個人存取權杖限制了權杖對特定 API 操作的權限。 你不是授予完整工作空間存取權，而是指派一個或多個 API 範圍，例如 sql、 unity-catalog、 ， scim限制 token 可呼叫的 REST API 操作。

警告

authentication 範圍的標記可以創建具有任何範圍的新標記。 只授予需要管理其他代幣的代幣範圍。

要在工作區介面中建立有範圍的權杖，請選擇範圍類型，並在產生新權杖時新增 API 範圍。 選擇 BI Tools，以連接 Databricks SQL 倉庫（如 Tableau 或 Power BI）的工具，或選擇 Other APIS 手動選擇範圍。

欲了解完整的範圍及其相關 API 操作，請參見 API 範圍。

個人存取權杖的自動範圍設定

自動範圍限定會自動將權杖的權限縮限為僅限其實際使用的 API。 Azure Databricks 會觀察該 token 在 30 天內的 API 使用情況，然後套用推斷出的權限範圍。 自動範圍界定是每個權杖執行一次。 在觀察期間，令牌保留完整的工作區存取權（即 all-apis 範圍）。 Azure Databricks 會在強制執行前 7 天發送提醒郵件，並在推斷範圍應用時發送強制執行郵件。

自動範圍控制

  • 工作區預覽（管理員控制）：管理員可從帳號主控台或工作區 預覽 頁面啟用或停用整個工作區的自動範圍界定預覽。 請參閱 管理 Azure Databricks 預覽。
  • 每個權杖設定（autoscope_enabled）：當預覽啟用時，每個權杖會在建立時個別選擇啟用或停用。

自動範圍設定僅適用於存續期超過 30 天的代幣。 這包括啟用自動範圍功能的新代幣，以及現有的長期存續代幣。 對於現有符合資格的代幣，30 天觀察期從管理員啟用預覽時開始。 Azure Databricks 會在該期間結束時套用推斷出的範圍，並在強制執行前 7 天發送提醒郵件，與新建立的自動範圍權杖相同。

選擇退出自動設定範圍

  • 在強制執行前，針對單一權杖：在工作區介面（設定>開發者>存取權杖>管理，然後點選 更新權杖）或使用權杖 API（請參閱 更新個人存取權杖的範圍）將權杖設為特定範圍。 設定特定範圍會永久停止對該權杖進行自動設定範圍。 將標記重新設回 all-apis 作用域（空的 scopes 陣列）是一種 no-op，且不會停止自動套用作用域。 若要保留一個具有完整 all-apis 存取權且永遠不會自動套用範圍的權杖，請建立一個停用自動套用範圍的新權杖。
  • 整個工作區：請管理員在 Previews 頁面上關閉自動範圍界定預覽功能。 請參閱 管理 Azure Databricks 預覽。

強制執行完成後，該權杖的自動套用範圍不會再次執行，因此你可以自由設定其範圍，包括將範圍設回 all-apis。

備註

工作區介面的選擇退出只適用於你擁有的權杖。 若要停用服務主體的權杖，請改為使用 PATCH /api/2.0/token/{token_id_sha256} 要求來設定其範圍。

要檢視你的權杖自動範圍狀態及推斷範圍，請參閱 檢視權杖自動範圍狀態。

建立服務主體的個人存取權杖

服務主體可以為自己建立個人存取權杖。

  1. 執行下列命令以產生存取權杖：

    databricks tokens create \
  --lifetime-seconds <lifetime-seconds> \
  -p <profile-name>

    取代下列值：

    • <lifetime-seconds>：代幣存留期（以秒為單位），例如 86400 為 1 天。 預設為工作區上限 （通常為 730 天）。
    • <profile-name>：具有身份驗證資訊的配置設定檔。 預設為 DEFAULT。

  2. 請從回應中複製token_value，這是您的服務主體的存取權杖。 安全地保存令牌，不要共享它。 如果您遺失了它，則必須建立一個新的令牌。

如果您無法建立或使用權杖，您的工作區系統管理員可能已停用權杖或未授與您權限。 請參閱您的工作區管理員或以下內容：

執行個人存取權杖驗證

要設定Azure Databricks個人存取憑證驗證，請設定以下相關環境變數，.databrickscfg 欄位、Terraform 欄位或 Config 欄位：

  • Azure Databricks 主機被指定為目標 Azure Databricks 工作區專用的 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
  • Azure Databricks 個人存取權杖，用於 Azure Databricks 使用者帳戶。

要執行 Azure Databricks 個人存取權杖認證，請根據您的程式碼整合以下內容，依據參與的工具或 SDK：

環境

若要使用特定Azure Databricks認證類型的環境變數，請參見 授權存取Azure Databricks資源或工具或 SDK 的文件。 另請參閱 統一鑑別的環境變數和欄位， 以及 鑑別方法優先順序。

設定下列環境變數：

  • DATABRICKS_HOST，設定為 Azure Databricks 工作區專用 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
  • 將 DATABRICKS_TOKEN設定為令牌字串。

個人檔案

在您的 檔案中建立或識別一個 Azure Databricks .databrickscfg，並包含以下欄位。 如果您建立設定檔，請將占位符替換成適當的值。 若要使用該設定檔搭配工具或 SDK，請參見 授權存取Azure Databricks資源或工具或 SDK 的文件。 另請參閱 統一鑑別的環境變數和欄位， 以及 鑑別方法優先順序。

在您的 .databrickscfg 檔案中設定下列值。 此時，主機為 Azure Databricks 每個工作區的 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net：

[<some-unique-configuration-profile-name>]
host  = <workspace-url>
token = <token>

您可以使用 Databricks CLI 來設定這些值，而不是手動設定值：

備註

以下程序使用 Databricks CLI建立一個名為 的 Azure Databricks DEFAULT。 如果已具有 DEFAULT 組態設定檔，此程序將覆寫現有的 DEFAULT 組態設定檔。

若要檢查您是否已經有組 DEFAULT 態設定檔，以及若要檢視此設定檔的設定是否存在，請使用 Databricks CLI 來執行命令 databricks auth env --profile DEFAULT。

若要使用除 DEFAULT 以外的名稱建立組態設定檔，請將下列 DEFAULT 命令中 --profile DEFAULT 的 databricks configure 部分取代為其他組態設定檔名稱。

  1. 使用 Databricks CLI建立一個名為 的 Azure Databricks DEFAULT，使用個人存取權杖認證Azure Databricks。 若要這樣做，請執行下列命令：

    databricks configure --profile DEFAULT

  2. 對於提示 Databricks Host，請輸入你的 Azure Databricks 工作區專屬 URL，例如 。

  3. 對於提示 Personal Access Token，請輸入你工作區的 Azure Databricks 個人存取權杖。

CLI

針對 Databricks CLI，執行 databricks configure 命令。 在提示中，輸入下列設定：

  • Azure Databricks 主機被指定為目標 Azure Databricks 工作區專用的 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
  • Azure Databricks 個人存取權杖，用於 Azure Databricks 使用者帳戶。

欲了解更多資訊，請參閱 個人存取權杖認證（舊有）。

連線

備註

以下 Databricks Connect 版本支援 Azure Databricks 個人存取令牌認證：

  • 對於 Python，Databricks Connect 適用於 Databricks Runtime 13.3 LTS 及以上版本。
  • 針對 Scala，適用於 Databricks Runtime 13.3 LTS 和更新版本的 Databricks Connect。

對於 Databricks Connect，請使用 Databricks CLI 在 .databrickscfg 檔案中設定 Azure Databricks 的 工作區層級操作，依照 設定檔章節 所指定。

以下程序會建立一個名為 DEFAULT 的 Azure Databricks 配置檔，覆蓋任何現有的 DEFAULT 設定檔。 若要檢查是否存在 DEFAULT 設定檔，請執行 databricks auth env --profile DEFAULT。 如果存在，請使用不同的設定檔名稱。

  1. 執行以下指令建立一個名為 DEFAULT 的Azure Databricks設定檔，使用個人存取權杖認證。

    databricks configure \
  --configure-cluster \
  --profile DEFAULT

  2. 對於提示 Databricks Host，請輸入你的 Azure Databricks 工作區專屬 URL，例如 。

  3. 針對提示的 個人存取權杖，請輸入您的工作區個人存取權杖。

  4. 在可用叢集清單中，選擇你工作空間中的目標 Azure Databricks 叢集。 您可以輸入叢集顯示名稱的任何部分，以篩選可用叢集的清單。

使用 Azure Databricks REST API 來發行個人存取權杖

Azure Databricks 提供一個 REST 端點/api/2.0/token/create 來發出 PAT。 如需 API 詳細 數據，請參閱建立使用者令牌 。

在下列範例中，設定這些值：

  • <databricks-instance>：您的 Databricks 工作區網址。 例如： dbc-abcd1234-5678.cloud.databricks.com 。
  • <your-existing-access-token>：現有的有效 PAT （字串），具有建立新權杖的許可權。
  • <lifetime-seconds>：令牌的存留期以秒為單位。
  • <scopes>： 指派給權杖的範圍清單，或空陣列（[]）以授予完整工作空間存取權（範圍 all-apis ）。 請參見 Scoped 個人存取令牌。
curl -X POST https://<databricks-instance>/api/2.0/token/create \
-H "Authorization: Bearer <your-existing-access-token>" \
-H "Content-Type: application/json" \
-d '{
  "lifetime_seconds": <lifetime-seconds>,
  "scopes": [
    "sql",
    "authentication"
  ],
  "autoscope_enabled": true
}'

如果成功，這將產生類似於以下的回應數據：

{
  "token_value": "<your-newly-issued-pat>",
  "token_info": {
    "token_id": "<token-id>",
    "creation_time": <creation-timestamp>,
    "expiry_time": <expiry-timestamp>,
    "comment": "<comment>",
    "scopes": ["authentication", "sql"],
    "last_accessed_time": 0
  }
}

在後續對 Databricks REST APIs 的請求中，將回應中的新令牌提供於授權標頭。 例如：

# This example uses a simple GET. For POST or other REST verbs, you may need to provide additional parameters.
curl -X GET "https://<databricks-instance>/api/2.0/<path-to-endpoint>" \
     -H "Authorization: Bearer <your-new-pat>"

import requests

headers = {
    'Authorization': 'Bearer <your-new-pat>'
}
# This example is for an HTTP GET operation.
response = requests.get('https://<databricks-instance>/api/2.0/<path-to-endpoint>', headers=headers)

更新個人存取權杖的範圍

若帶有範疇的權杖缺少進行 API 呼叫所需的範疇，請求將失敗，並返回一個錯誤以指明缺失的範疇。 要更新權杖的範圍，請使用 REST 端點 /api/2.0/token/<token_id>。 呼叫標記必須具有 authentication 範圍，以允許管理其他標記。 使用欄位 update_mask 指定要更新哪些標記欄位。

curl -X PATCH https://<databricks-instance>/api/2.0/token/<token_id> \
-H "Authorization: Bearer <your-existing-access-token>" \
-H "Content-Type: application/json" \
-d '{
  "token": {
    "scopes": ["sql", "unity-catalog"]
  },
  "update_mask": "scopes"
}'

要授予令牌完整工作區存取權（範圍 all-apis ），請設 scopes 為空陣列（"scopes": []）。 字串 all-apis 並非被接受的範圍值。

備註

Azure Databricks 建議指派特定範圍，而非授予 all-apis 存取權。 請參閱 自動識別個人存取令牌。

範圍變更可能需要長達十分鐘才能生效。

要查看所有可用的示波器，請使用 GET /api/2.0/token-scopes。

  • 上次更新時間：