设置 Azure Databricks Excel 插件

注释

Azure Databricks Excel外接程序在Azure 政府或Azure中国区域不可用。

Azure Databricks Excel插件将您的Azure Databricks工作区连接到Microsoft Excel，将受管控的Lakehouse数据直接带入您的电子表格。 Windows 和 macOS 的 Excel 网页版和桌面版本完全支持该外接程序。

本页介绍可用于在Microsoft Excel中设置Azure Databricks Excel外接程序的两种方法。 此加载项使用单一登录（SSO）身份验证连接到 Azure Databricks 工作区，并支持 Unity 目录 进行数据管理和访问控制。

先决条件

在安装 Excel 外接程序之前，请验证是否具有以下各项：

  • 访问启用了 Unity Catalog 的 Azure Databricks 工作区。
  • 确保工作区管理员启用了 Excel 连接器预览。 请参阅 Manage Azure Databricks 预览版。
  • Excel 应连接的每个 Azure Databricks 工作区 URL。
  • 您拥有Azure Databricks SQL 访问权限，并且至少对SQL 仓库具有 CAN USE 权限。
  • 从工作区中的 Unity 目录表读取数据的权限。
  • 以下版本的Excel之一：
    • Mac 上的 Excel 2019 或更高版本
    • Windows 上的 Excel （Microsoft 365）
    • 网页版 Excel
    • Mac 上的 Excel （Microsoft 365）
  • 如果您使用防火墙或云安全平台，请将加载项文件中包含的 Azure Databricks 工作区 URL 加入允许列表。
  • 如果您的 Microsoft Entra 租户阻止了第三方应用的用户同意，Microsoft Entra 管理员必须先授权 Azure Databricks 单点登录企业应用，用户才能通过账户选择器登录。 如果用户直接输入工作区 URL 登录，则无需此操作。 登录时，请参阅 “需要管理员批准”消息。

设置加载项文件

注释

如果你是通过 Microsoft 市场部署加载项的管理员，请跳过本部分。 市场部署使用 PowerShell 配置工作区访问权限，而不是外接程序文件。 请参阅 通过 Microsoft Marketplace 部署。

外接程序文件是一个小连接器文件，它告知Excel如何安全地连接到Azure Databricks。 它充当数字握手，可确保外接程序加载正确，并在每次打开 Excel 时保持最新状态。

下载并设置外接程序文件以使用Azure Databricks Excel外接程序。 单个插件文件可以连接到多个 Azure Databricks 工作区。

  1. 下载Azure Databricks Excel 加载项文件：

    下载Excel 加载项文件

  2. 通过在 AppDomains 部分中将您的 工作区 URL 指定为 <AppDomain> 来编辑加载项文件。 工作区 URL 是用于在浏览器中访问 Azure Databricks 工作区的基本 URL。 若要在多个 Azure Databricks 工作区之间切换，请将每个工作区 URL 添加到外接程序文件。

    要用 自定义 URL 登录，请将自定义 URL 和关联的工作区 URL 分别作为独立 <AppDomain> 条目添加，如下示例所示。 登录可以重定向到任一URL。

    <AppDomains>
   <!-- DO NOT CHANGE -->
   <AppDomain>https://www.databricks.com</AppDomain>
   <AppDomain>https://login.databricks.com</AppDomain>
   <!-- ADD WORKSPACE URLS AS SHOWN BELOW; PUT EACH WORKSPACE URL IN ITS OWN <AppDomain> TAG  -->
   <!-- EXAMPLE -->
   // highlight-next-line
   <AppDomain>https://adb-<workspace1-id>.<random-number>.azuredatabricks.net</AppDomain>
   // highlight-next-line
   <AppDomain>https://adb-<workspace2-id>.<random-number>.azuredatabricks.net</AppDomain>
   <!-- TO USE A CUSTOM URL, ADD BOTH THE CUSTOM URL AND ITS ASSOCIATED WORKSPACE URL -->
   // highlight-next-line
   <AppDomain>https://<custom-url>.azuredatabricks.net</AppDomain>
</AppDomains>

    注释

    将工作区 URL 粘贴为纯文本，无需设置格式。 在大多数文本编辑器中，使用 Ctrl+Shift+V （Windows） 或 Command+Shift+V （macOS）。

  3. 保存所做的更改。 验证该文件的格式是否正确为 .xml 文件。

选项一：从 Microsoft 365 管理中心 部署

作为全局管理员，可以将 Azure Databricks Excel 外接程序部署到组织中的用户。 可以使用外接程序文件将外接程序部署为自定义应用，也可以从Microsoft市场安装它。

若要将Azure Databricks Excel外接程序安装为Microsoft 365 管理，必须具有 global admin 权限。 作为管理员，你可以确定组织中的哪些用户可以使用加载项。有关 Microsoft 365 上的全局管理员的详细信息，请参阅 Microsoft 文档。

点击这里访问 Microsoft 365 管理中心。

注释

Databricks 建议将Azure Databricks Excel外接程序部署为自定义应用。

部署为自定义应用

使用自定义清单文件部署外接程序。 下载并设置 先决条件中提供的外接程序文件。

  1. 在 Microsoft 365 管理中心，转到 “设置 > 集成应用 ”并单击 “加载项 ”链接。
  2. 单击“ 部署加载项 ”，然后单击“ 下一步”。
  3. 单击“ 上传自定义应用 ”作为部署新外接程序的选项。
  4. 选择上传清单的选项。 单击 “选择文件” 并上传加载项文件。
  5. 选择哪些用户应有权访问外接程序。
  6. 单击“部署”。

有关上传 Azure Databricks Excel 外接程序的详细步骤，请参阅 Microsoft文档。

从微软应用商店部署

从 Microsoft 市场安装加载项，并使用 PowerShell 配置工作区访问权限。 单独安装外接程序不会将其连接到Azure Databricks工作区。 按照以下所有步骤操作，包括使用 PowerShell 将你的工作区 URL 加入允许列表。

Prerequisites

  • PowerShell 安装在计算机上。
  • 你必须以管理员身份运行 Windows PowerShell。

安装加载项

  1. 在 Microsoft 365 管理中心 中，转到 Settings > 集成应用并单击Get Apps 链接。
  2. 搜索“适用于 Excel 的 Azure Databricks 外接程序”。
  3. 单击“立即获取”。
  4. 通过在“分配用户”下选择“仅我”，将加载项部署到自己。
  5. 单击“部署”。

有关从 Microsoft 市场部署 Azure Databricks Excel 外接程序的详细步骤，请参阅 Microsoft 文档。

配置工作区访问

安装加载项后，使用 PowerShell 将 Azure Databricks 工作区的 URL 列入允许名单。

注释

与 Office 365 管理中心的 PowerShell 连接可能会超时。如果命令失败，请通过运行 Connect-OrganizationAddInService重新打开 PowerShell 并重新连接。

  1. 打开 PowerShell，以管理员身份运行。 有关详细信息，请参阅 Microsoft 文档。

  2. 安装和导入Office 365集中式部署模块：

    Install-Module -Name O365CentralizedAddInDeployment
Import-Module O365CentralizedAddInDeployment

  3. 以管理员身份连接并登录到Office 365租户：

    Connect-OrganizationAddInService

  4. 确认已部署加载项。 适用于 Excel 的 Azure Databricks 外接程序应显示在列表中。

    Get-OrganizationAddIn

    如果未显示该加载项，可能需要重新部署，或者该加载项可能仍在部署中。

  5. 将 Azure Databricks 工作区 URL 加入允许列表。 将每个 <workspace-url> 替换为您要允许的工作区 URL。 可以根据需要包含任意数量的工作区 URL。 为了支持 自定义 URL，请同时包含自定义 URL 和相关的工作区 URL。

    Set-OrganizationAddInOverrides -ProductId d75dbea5-bf93-49b8-9a49-bdf4e9d6f052 `
  -AppDomains "https://adb-<workspace1-id>.<random-number>.azuredatabricks.net", "https://adb-<workspace2-id>.<random-number>.azuredatabricks.net", "https://<custom-url>.azuredatabricks.net"

    Azure Databricks 的产品 ID 为 d75dbea5-bf93-49b8-9a49-bdf4e9d6f052.

    即使工作区 URL 已成功加入允许列表，命令也可能返回 There was an error uploading the Add-In。 在再次执行命令之前，先完成下一步检查允许列表是否被应用。

  6. 确认允许列表设置是否正确。 您已加入允许列表的工作区 URL 应显示在 AppDomains 部分中。

    Get-OrganizationAddInOverrides -ProductId d75dbea5-bf93-49b8-9a49-bdf4e9d6f052

测试加载项

  1. 在Excel中，找到Azure Databricks加载项。
  2. 登录并连接到您已加入允许列表的工作区之一。

注释

允许列表的更改可能需要一些时间来同步。如果认证失败，请确认你正在连接到已加入允许列表的工作区。 如果工作簿正确，关闭 Excel，稍后再试。

部署到您的组织

  1. 在 Microsoft 365 管理中心中，转到 “设置 > 集成应用”。
  2. 选择已安装和配置的 Azure Databricks 外接程序。
  3. 单击“ 用户 ”选项卡并选择是部署到整个组织还是特定用户组。

注释

作为管理员，请将与已加入允许列表的工作区关联的账户名称分享给计划使用 Azure Databricks Excel 加载项的用户。 请参阅登录加载项。

选项二：作为个人用户部署

安装步骤因 Excel 平台而异。 下载并设置 先决条件中提供的外接程序文件。

Excel 网页版

若要安装和连接到 Excel 网页版中的 Excel 外接程序，请执行以下操作：

  1. 打开 Excel 网页版并创建或打开工作簿。
  2. 在“开始”选项卡下，单击“ 加载项>高级”。
  3. 单击“上传我的外接程序”。
  4. 上传外接程序文件。
  5. 单击“上载” 。
  6. 从 Add-ins 菜单中查找并单击Azure Databricks加载项。
  7. 登录到 Azure Databricks 帐户。 如果出现错误，请确保启用弹出对话框。
  8. 如果配置了多个工作区 URL，请选择所需的 Azure Databricks 帐户名称。 仅当 URL 位于同一帐户中时，才需要选择特定的工作区。 有关帐户名称的详细信息，请参阅 查找帐户 ID。

Excel桌面（Windows）

不要从 商店 标签页安装插件。这样安装的插件不会连接到你的工作区。 在Windows版Excel桌面中，从共享文件夹标签安装Excel插件：

  1. 创建在本地驱动器上命名 Manifest 的文件夹（例如， C:\Manifest）。
  2. 将外接程序文件复制到 C:\Manifest 该文件夹。
  3. 打开文件夹属性并共享文件夹：
    1. 右键单击 Manifest 文件夹，然后选择“ 属性”。
    2. 单击“共享共享>”，将自己添加为具有读取和写入权限的用户。
  4. 打开Excel桌面。
  5. 配置Excel以信任清单文件夹：
    1. 单击 “文件>选项>信任中心>信任中心设置”。
    2. 在边栏中，单击 “受信任的外接程序目录”。
    3. 在 目录 URL 中，输入外接程序文件所在的共享文件夹的路径（例如， \\YourComputerName\Manifest）。
    4. 单击“ 添加目录”。
    5. 选中 “在菜单中显示 ”复选框。
    6. 单击“确定”，以保存您的更改。
  6. 重启Excel桌面。
  7. 在首页标签下，点击 “插件>”更多插件“。
  8. 在共享文件夹下，选择Azure Databricks Add-in for Excel。
  9. 完成 Azure Databricks 帐户的登录过程。
  10. 如果配置了多个工作区 URL，请选择所需的 Azure Databricks 帐户名称。 仅当 URL 位于同一帐户中时，才需要选择特定的工作区。 有关帐户名称的详细信息，请参阅 查找帐户 ID。

Excel Desktop （macOS）

若要在 Excel Desktop for macOS 中安装 Excel 外接程序，请执行以下操作：

  1. 将外接程序文件复制到Microsoft Office 加载项文件夹中。 wef如果该文件夹不存在，请创建它。

    /Users/<your-username>/Library/Containers/com.microsoft.Excel/Data/Documents/wef

  2. 打开或重启Excel桌面。

  3. 在导航栏中，单击加载项>我的加载项。

  4. 单击 “Azure Databricks” 附加组件。

  5. 完成 Azure Databricks 帐户的登录过程。

  6. 如果配置了多个工作区 URL，请选择所需的 Azure Databricks 帐户名称。 仅当 URL 位于同一帐户中时，才需要选择特定的工作区。 有关帐户名称的详细信息，请参阅 查找帐户 ID。

登录外接程序

如果组织中的管理员已部署 Azure Databricks Excel 外接程序，请从 Excel 登录并连接到 Azure Databricks 工作区。

  1. 在 Excel 的“开始”选项卡下，单击 Azure Databricks 外接程序。

  2. 首次登录时，请使用以下选项之一连接工作区：

    • 输入工作区 URL（推荐）：输入你的 Azure Databricks 工作空间 URL。 此选项可让您通过工作区单点登录（SSO）登录。 要用 自定义 URL 登录，请确认自定义 URL 和关联的工作区 URL 都被添加到插件文件中。 参见 设置插件文件。
    • 使用账户选择器：点击 “选择账户选择器 ”打开 login.databricks.com，然后选择一个允许列出的账户和工作区。

  3. 点击登录并完成认证流程以获得Azure Databricks Excel插件的访问权限。

在你第一次登录后，插件会记住你的工作区。 在后续登录时，从下拉菜单中选择工作区，或使用上述任一选项连接到不同的工作区。

如果你使用 Microsoft Entra ID 认证并且出现“需要管理员批准”的提示，那么 Microsoft Entra 管理员必须先批准 Azure Databricks 企业应用，才能登录。 登录时，请参阅 “需要管理员批准”消息。

更改 Azure Databricks 工作区

如果外接程序文件指定了多个 Azure Databricks 工作区，则可以在这些工作区之间切换。 有关详细信息，请参阅 设置外接程序文件。

若要连接到其他 Azure Databricks 工作区，请执行以下操作：

  1. 在Azure Databricks外接程序窗格的右上角，单击计算选择器旁边的三点菜单。
  2. 单击“ 更改工作区”。
  3. 选择包含您工作区的账户，如果系统提示，请选择相应的工作区，然后登录。

故障排除

登录时出现“正在进行身份验证”消息

如果在尝试从外接程序登录到 Azure Databricks 时看到“正在进行身份验证”窗口，则工作区可能尚未正确添加到自定义外接程序文件中。 请验证是否在<AppDomains>下正确配置了工作区。

登录时出现“需要管理员批准”消息

从Excel 加载项登录到Azure Databricks工作区时，将显示以下“需要管理员批准”消息，因为Microsoft Entra租户阻止用户同意Azure Databricks应用程序。 这只适用于你用账户选择器登录时（;login.databricks.com）为避免这种情况，请在登录时直接输入你的工作区网址。 如果未授予管理员同意，Microsoft Entra ID即使具有直接工作区访问权限，仍会阻止登录流。

Excel 加载项中的需要管理员批准的消息

若要解决此问题，具有相应管理员角色的Microsoft Entra用户必须向Azure Databricks企业应用程序授予租户范围的管理员同意。

请让Microsoft Entra管理员访问以下链接。 将 {TENANT_ID} 替换为你的 Microsoft Entra 租户 ID：

https://login.microsoftonline.com/{TENANT_ID}/adminconsent?client_id=aaec40b0-c0ae-4211-a98b-6fc160abb71b

如果链接失败，管理员可以手动授予许可：

  1. 在 Microsoft Entra 管理中心 中，转到 Entra ID>Enterprise apps>All applications 并查找用于单一登录的Azure Databricks企业应用程序。 若要标识应用程序，请搜索应用程序 ID aaec40b0-c0ae-4211-a98b-6fc160abb71b。
  2. 为Azure Databricks企业应用请求的权限授予管理员许可：
    1. 在 “安全性”下，单击“ 权限”。
    2. 单击“ 授予管理员同意”。

有关详细说明，请参阅 Microsoft 文档。

无法使用资源

如果无法在 Azure Databricks 外接程序中使用 Azure Databricks 资源（如 SQL 仓库），请尝试以下方法之一，具体取决于所使用的 Excel 版本：

  • Excel 网页版：重启工作表或更改工作区，并重新登录到同一工作区。 请参阅 “更改 Azure Databricks 工作区”。
  • Excel Desktop：单击右上角的信息图标并选择 Reload重新加载加载项。

后续步骤

  • 上次更新时间为