Azure Databricks 配置文件

Azure Databricks 配置文件将 .databrickscfg 身份验证设置存储在文件中。通过配置文件，可以在不同的工作区、环境或身份验证方法之间轻松切换，而无需更改代码。

工具、SDK、脚本和应用可以引用配置文件，以使用 Azure Databricks 进行身份验证。实现统一身份验证的所有工具和 SDK 都支持配置文件。

什么是配置文件？

配置文件是文件中包含以下项的命名节 .databrickscfg ：

身份验证凭据，例如令牌或服务主体凭据
Azure Databricks 工作区或帐户 URL
验证方法特定的可选设置

在单个 .databrickscfg 文件中创建多个配置档案，以管理开发、测试和生产等不同工作区或环境的连接。

创建配置文件

使用 Databricks CLI 或手动编辑 .databrickscfg 文件来创建配置文件。

使用 CLI 创建配置文件

为交互式用户身份验证创建配置文件的最简单方法是使用 Databricks CLI：

databricks auth login --host <workspace-url>

CLI 将打开 Web 浏览器以完成身份验证流。登录后，CLI 会将凭据保存为配置文件。

手动创建配置文件

手动创建配置文件：

创建在主目录中命名 .databrickscfg 的文件：
- Unix、Linux、macOS：~/.databrickscfg
- Windows：%USERPROFILE%\.databrickscfg
添加具有以下格式的配置文件：
```
[<profile-name>]
<field-name> = <field-value>
```
替换占位符：
- <profile-name>：唯一名称，例如 DEFAULT， DEVELOPMENT或 PRODUCTION
- <field-name> 和 <field-value>：用于您的身份验证方法的身份验证字段

例如，对于 OAuth 计算机到计算机（M2M）身份验证， .databrickscfg 文件如下所示：

[DEFAULT]
host          = https://<workspace-url>
client_id     = <client-id>
client_secret = <client-secret>

创建多个个人资料

在同一 .databrickscfg 文件中定义多个配置文件来管理不同的工作区或环境。每个配置文件必须具有唯一名称。

[DEFAULT]
host          = https://production-workspace-url
client_id     = <production-client-id>
client_secret = <production-client-secret>

[DEVELOPMENT]
host          = https://dev-workspace-url
client_id     = <dev-client-id>
client_secret = <dev-client-secret>

[STAGING]
host          = https://staging-workspace-url
client_id     = <staging-client-id>
client_secret = <staging-client-secret>

合并身份验证类型

在配置文件中，将多个身份验证方法定义在各自独立的配置档案中。如果要对不同的工作流或工具使用不同的凭据，这非常有用。例如，可以使用云原生身份验证进行交互式使用，使用 OAuth 凭据实现自动化：

[DEFAULT]
host = https://<workspace-url>

[SERVICE_PRINCIPAL]
azure_workspace_resource_id = /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/workspaces/<workspace-name>
azure_tenant_id             = <tenant-id>
azure_client_id             = <client-id>
azure_client_secret         = <client-secret>

有关身份验证类型及其必填字段的详细信息，请参阅 Databricks 统一身份验证。

使用配置文件

创建配置文件后，请在您的工具和代码中引用该文件。如果未指定配置文件名称，Azure Databricks 工具和 SDK 会自动使用该 DEFAULT 配置文件。

若要使用其他 DEFAULT配置文件，请指定配置文件名称：

使用 Databricks CLI：

databricks workspace list --profile DEVELOPMENT

使用环境变量：

export DATABRICKS_CONFIG_PROFILE=DEVELOPMENT
databricks workspace list

使用 Python SDK：

from databricks.sdk import WorkspaceClient

# Specify profile in code
w = WorkspaceClient(profile="DEVELOPMENT")

# Or use environment variable DATABRICKS_CONFIG_PROFILE

最佳做法

使用默认配置文件来减少在最常用工作场所指定配置文件名称的需求。
使用描述性配置文件名称，例如 PRODUCTION、 DEVELOPMENT 或 STAGING，而不是泛泛的名称。
.databrickscfg通过设置受限文件权限来保护文件（仅用户可读）。
不要提交 .databrickscfg 到版本控制。将其添加到 .gitignore 文件。
应使用服务主体用于生产环境负载，而不是个人访问令牌。
定期轮换凭据并相应地更新用户简介。

Troubleshooting

如果找不到配置文件，请验证以下内容：

该文件 .databrickscfg 位于主目录中。
你使用确切的配置文件名称。
该文件未命名 .databrickscfg.txt 或类似内容。

如果身份验证失败，请验证以下内容：

凭据是最新的且尚未过期。
host URL 正确。
您具有您正在尝试进行的操作所需的权限。

使用 Databricks CLI 测试配置文件：

# Inspect a specific profile
databricks auth env --profile DEVELOPMENT

# List all profiles
databricks auth profiles

有关详细信息，请参阅测试配置文件。

了解详细信息

Last updated on 2025-12-08