使用Azure Databricks个人访问令牌进行身份验证（旧版）

Azure Databricks个人访问令牌（PAT）允许你在工作区级别对资源和 API 进行身份验证。可以将它们存储在环境变量或Azure Databricks 配置配置文件中。每个 PAT 仅对一个工作区有效，用户可以为每个工作区创建最多 600 个 PAT。 Azure Databricks 自动撤销在 90 天内未使用的 PAT。

重要

如果可能，Databricks 建议使用 OAuth 而不是 PAT 进行身份验证，因为 OAuth 提供更强的安全性。若要了解如何通过 Databricks 用户使用 OAuth 进行身份验证，请参阅使用 OAuth 授权用户访问 Azure Databricks。

您无法使用个人访问令牌自动执行 Azure Databricks 帐户级别功能。请改用Azure Databricks帐户管理员的Microsoft Entra ID令牌。 Azure Databricks帐户管理员可以是用户或服务主体。有关详细信息，请参阅：

管理用户
服务主体
组。

为工作区用户创建个人访问令牌

若要为Azure Databricks工作区用户创建个人访问令牌，请执行以下操作：

在Azure Databricks工作区中，单击顶部栏中的用户名，然后选择 Settings。
单击“开发人员”。
在“访问令牌”旁边，单击“管理”。
单击“生成新令牌”。
输入有助于稍后标识此令牌的名称。
设置令牌的生存期（以天为单位）。请参阅设置新个人访问令牌的最大生存期。
选择范围类型并添加 API 范围。对于连接到 Tableau 或 Power BI 等 Databricks SQL 仓库的工具，请选择 BI 工具，或选择其他 API手动选择范围。请参阅范围内个人访问令牌。
要为此令牌启用自动限定范围，请开启“自动限定令牌范围”。自动限定作用域会自动缩小令牌的作用域至其所使用的 API，并在观察期间暂时应用 all-apis 作用域。该选项仅在管理员启用了工作区自动范围预览时出现，且自动范围仅适用于寿命超过30天的令牌。请参阅个人访问令牌的自动确定范围。
单击“生成”按钮。
将显示的令牌复制到安全位置，然后单击“ 完成”。安全地保存令牌，不共享该令牌。如果丢失该令牌，则必须创建新的令牌。

如果无法创建或使用令牌，则工作区管理员可能已禁用令牌或未授予你权限。请与工作区管理员联系，或参阅以下内容：

作用域内的个人访问令牌

限定作用域的个人访问令牌将令牌的权限限制为特定的 API 操作。无需授予完全工作区访问权限，而是分配一个或多个 API 范围，例如 sql， unity-catalog或 scim限制令牌可以调用的 REST API 操作。

警告

具有authentication作用域的令牌可以生成具备任意作用域的新令牌。仅将此范围授予需要管理其他令牌的令牌。

若要在工作区 UI 中创建作用域令牌，请在生成新令牌时选择范围类型并添加 API 范围。对于连接到 Tableau 或 Power BI 等 Databricks SQL 仓库的工具，请选择 BI 工具，或选择其他 API手动选择范围。

有关范围及其关联的 API 操作的完整列表，请参阅 API 范围。

个人访问令牌的自动确定范围

自动确定范围会自动将令牌的权限收窄为仅限其实际使用的 API。 Azure Databricks 会观察令牌在 30 天内的 API 使用情况，然后应用推断出的作用域。自动限定范围将针对每个令牌运行一次。在观察期间，令牌保留完整的工作区访问权限（范围 all-apis ）。 Azure Databricks 会在强制执行前 7 天发送提醒电子邮件，并在应用推理的范围时发送强制执行通知电子邮件。

自动限定范围控制

工作区预览（受管理员控制）：管理员从帐户控制台或工作区“预览”页面中为整个工作区启用或禁用自动限定范围预览。请参阅 Manage Azure Databricks 预览版。
按令牌设置（autoscope_enabled）：当预览被启用时，每个令牌在创建时单独选择加入或退出。

自动限定范围仅适用于生存期超过 30 天的令牌。这包括启用自动限定范围的新令牌以及现有的长存令牌。对于已有的合格令牌，30天观察期从管理员启用预览时开始。 Azure Databricks 在该期间结束时应用推理的范围，并在强制执行前 7 天发送提醒电子邮件，计划与新创建的自动限定范围的令牌相同。

选择退出自动限定范围

一个令牌（强制执行前）：在工作区 UI（设置>开发人员>访问令牌>管理，然后单击“更新令牌”）中将令牌设置为特定范围，或者使用令牌 API 设置（请参阅更新个人访问令牌的范围）。设置特定范围会永久停止为此令牌自动限定范围。将令牌重新设置为 all-apis 范围（空 scopes 数组）无需任何操作，因此不会停止自动限定范围。要保留一个具有完全 all-apis 访问权限且永不自动限定范围的令牌，可以创建一个禁用自动限定范围的新令牌。
整个工作区：请管理员在“预览”页面上关闭自动限定范围预览。请参阅 Manage Azure Databricks 预览版。

强制执行完成后，自动设定作用域不会对此令牌再次运行，因此你可以自由设置其作用域，包括回到 all-apis。

注意

工作区 UI 选择退出仅适用于拥有的令牌。要禁用服务主体的令牌，请改为使用 PATCH /api/2.0/token/{token_id_sha256} 请求设置其作用域。

要查看令牌的自动限定范围状态和推断的范围，请参阅查看令牌自动限定范围状态。

为服务主体创建个人访问令牌

服务主体可以自行创建个人访问令牌。

运行以下命令以生成访问令牌：
```
databricks tokens create \
  --lifetime-seconds <lifetime-seconds> \
  -p <profile-name>
```
请替换以下值：
- <lifetime-seconds>：令牌生存期（以秒为单位），例如 86400（1 天）。默认为工作区最大值（通常为 730 天）。
- <profile-name>：包含身份验证信息的配置文件。默认为 DEFAULT。
从响应中复制token_value，这就是你的服务主体的访问令牌。安全地保存令牌，不共享该令牌。如果丢失该令牌，则必须创建新的令牌。

如果无法创建或使用令牌，则工作区管理员可能已禁用令牌或未授予你权限。请与工作区管理员联系，或参阅以下内容：

执行个人访问令牌身份验证

若要配置Azure Databricks个人访问令牌身份验证，请设置以下关联的环境变量、.databrickscfg 字段、Terraform 字段或 Config 字段：

Azure Databricks 主机，指定为目标 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
Azure Databricks用户帐户的个人访问令牌。

若要执行Azure Databricks个人访问令牌身份验证，请根据参与的工具或 SDK 在代码中集成以下内容：

环境

若要在工具或 SDK 中使用特定的 Azure Databricks 身份验证-类型的环境变量，请参阅授权访问Azure Databricks资源或工具或 SDK 的文档。另请参阅环境变量和字段，了解统一身份验证和身份验证方法优先级。

设置以下环境变量：

DATABRICKS_HOST，设置为 Azure Databricks per-workspace URL，例如https://adb-1234567890123456.7.azuredatabricks.net。
DATABRICKS_TOKEN，设置为令牌字符串。

配置文件

使用文件中的以下字段创建或标识 Azure Databricks .databrickscfg。如果创建配置文件，请将占位符替换为相应值。若要将配置文件与工具或 SDK 配合使用，请参阅授权访问 Azure Databricks 资源或该工具或 SDK 的文档。另请参阅环境变量和字段，了解统一身份验证和身份验证方法优先级。

在 .databrickscfg 文件中设置以下值。在这种情况下，主机是 Azure Databricks per-workspace 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 部分替换为其他配置文件名称。

使用 Databricks CLI创建Azure Databricks 配置配置文件名为 DEFAULT，该配置文件使用Azure Databricks个人访问令牌身份验证。为此，请运行以下命令：
```
databricks configure --profile DEFAULT
```
对于提示Databricks 主机，请输入 Azure Databricks 按工作区 URL，例如https://adb-1234567890123456.7.azuredatabricks.net。
对于提示“Personal Access Token”，请输入工作区的 Azure Databricks 个人访问令牌。

CLI

对于 Databricks CLI，请运行 databricks configure 命令。在出现提示时，输入以下设置：

Azure Databricks 主机，指定为目标 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
Azure Databricks用户帐户的个人访问令牌。

有关详细信息，请参阅个人访问令牌身份验证（旧版）。

连接

注意

以下 Databricks Connect 版本支持Azure Databricks个人访问令牌身份验证：

对于 Python，Databricks Connect for Databricks Runtime 13.3 LTS 及更高版本。
对于 Scala，为 Databricks Connect for Databricks Runtime 13.3 LTS 及更高版本。

对于 Databricks Connect，可以使用 Databricks CLI 按照.databrickscfg所述为 Azure Databricks 工作区级别操作设置文件中的值。

以下过程创建名为 DEFAULT 的Azure Databricks配置文件，该配置文件覆盖任何现有的 DEFAULT 配置文件。若要检查 DEFAULT 配置文件是否存在，请运行 databricks auth env --profile DEFAULT。如果已经存在，请使用其他配置文件名称。

运行以下命令，创建一个名为 DEFAULT 的Azure Databricks配置文件，该配置文件使用个人访问令牌身份验证。
```
databricks configure \
  --configure-cluster \
  --profile DEFAULT
```
对于提示Databricks 主机，请输入 Azure Databricks 按工作区 URL，例如https://adb-1234567890123456.7.azuredatabricks.net。
对于提示 个人访问令牌，请输入工作区的个人访问令牌。
在可用群集列表中，选择您工作区中的目标 Azure Databricks 群集。可以键入群集显示名称的任何部分来筛选可用群集的列表。

使用 Azure Databricks REST API 颁发个人访问令牌

Azure Databricks 提供可颁发 PAT 的 REST 终结点 /api/2.0/token/create。请参阅 “创建用户令牌 ”了解 API 详细信息。

在以下示例中，设置以下值：

<databricks-instance>：Databricks 工作区 URL。例如，dbc-abcd1234-5678.cloud.databricks.com。
<your-existing-access-token>：有权创建新令牌的现有有效 PAT（字符串）。
<lifetime-seconds>：令牌的生存期（以秒为单位）。
<scopes>：一组要分配给令牌的作用域，或一个空数组（[]），用于授予完整的工作区访问权限（all-apis 作用域）。请参阅范围内个人访问令牌。

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 API 的后续调用的授权标头中提供响应中的新令牌。例如：

# 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。

反馈

此页面是否有帮助？

上次更新时间为 2026-10-16