通过

Databricks CLI 的身份验证

  • 项目

注意

此信息适用于 Databricks CLI 0.205 及更高版本，这些版本为公共预览版。 若要查找你的 Databricks CLI 的版本，请运行 databricks -v。

本文介绍如何在 Databricks CLI 与 Azure Databricks 帐户和工作区之间设置身份验证。 请参阅什么是 Databricks CLI？。

本文假定你已安装 Databricks CLI。 请参阅安装或更新 Databricks CLI。

在运行 Databricks CLI 命令之前，必须在 Databricks CLI 与 Azure Databricks 帐户、工作区或这些对象的组合之间设置身份验证，具体取决于要运行的 CLI 命令的类型。

必须在运行时对相关资源的 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 和 Azure Databricks 之间设置身份验证的信息：

Azure Databricks 个人访问令牌身份验证

Azure Databricks 个人访问令牌身份验证使用 Azure Databricks 个人访问令牌对目标 Azure Databricks 实体（例如 Azure Databricks 用户帐户）进行身份验证。 请参阅 Azure Databricks 个人访问令牌身份验证。

注意

无法使用 Azure Databricks 个人访问令牌身份验证通过 Azure Databricks 帐户进行身份验证，因为 Azure Databricks 帐户级别命令不使用 Azure Databricks 个人访问令牌进行身份验证。 若要使用 Azure Databricks 帐户进行身份验证，请考虑改用以下身份验证类型之一：

若要创建个人访问令牌，请执行以下操作：

  1. 在 Azure Databricks 工作区中，单击顶部栏中的 Azure Databricks 用户名，然后从下拉列表中选择“设置”。
  2. 单击“开发人员”。
  3. 在“访问令牌”旁边，单击“管理”。
  4. 单击“生成新令牌”。
  5. （可选）输入有助于将来识别此令牌的注释，并将令牌的默认生存期更改为 90 天。 若要创建没有生存期的令牌（不建议），请将“生存期(天)”框留空（保留空白）。
  6. 单击“生成” 。
  7. 将显示的令牌复制到安全位置，然后单击“完成”。

注意

请务必将复制的令牌保存到安全的位置。 请勿与他人共享复制的令牌。 如果丢失了复制的令牌，你将无法重新生成完全相同的令牌， 而必须重复此过程来创建新令牌。 如果丢失了复制的令牌，或者认为令牌已泄露，Databricks 强烈建议通过单击“访问令牌”页上令牌旁边的垃圾桶（撤销）图标立即从工作区中删除该令牌。

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

若要配置和使用 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.databricks.azure.cn。

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

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 资源 ID，而不是指定 host 和工作区 URL。 在这种情况下，目标标识必须至少对 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 资源 ID，而不是指定 host 和工作区 URL。 在这种情况下，目标 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 文件内的配置文件中搜索包含 host 字段并具有匹配工作区 URL 的配置文件。 Databricks CLI 查找匹配的 host 字段，然后使用该配置文件的 token 字段值。