在 Power BI Desktop 中连接腾讯云 DLC
下载
聚焦模式
字号
本文档是腾讯云数据湖计算（DLC）与 Power BI Desktop 的连接指南。内容涵盖环境准备、账号鉴权配置、数据加载模式（支持写 SQL 取数）以及常见问题排查，助您快速打通 Power BI 从而实现数据的可视化分析。
说明：
准备工作
开始前，请从 DLC 团队处获取以下两个核心文件
dlc-spark-odbc-1.0.0-win64.msi ODBC 驱动（系统级安装包）DlcODBCNative.mez Power BI 自定义连接器
安装 ODBC 驱动
1. 双击打开 “dlc-spark-odbc-1.0.0-win64.msi”。
2. 在弹出的用户账户控制（UAC）提示框中，单击 Yes（是） 。
3. 按照安装向导指示，依次单击 Next（下一步），直至安装完成。
静默安装（IT 批量部署用）：
msiexec /i "dlc-spark-odbc-1.0.0-win64.msi" /qn /norestart /l*v install.log
说明：
该驱动为后台系统组件，安装完成后不会生成桌面快捷方式或开始菜单图标。
无需创建 ODBC 数据源（DSN），连接器会直接按驱动名调用。
如需卸载，请选择控制面板 > 程序和功能，找到 DLC Spark ODBC Driver 后卸载。
验证（可选）
安装完成后，在 PowerShell 中执行以下命令验证驱动是否注册成功。
Get-ItemProperty "HKLM:\\SOFTWARE\\ODBC\\ODBCINST.INI\\DLC Spark ODBC Driver"
返回结果中的 Driver 字段指向
C:\\Program Files\\Tencent\\DLC Spark ODBC Driver\\dlcodbc64.dll，表示驱动已安装成功。部署 Power BI 连接器
ODBC 驱动负责与 DLC 服务端通信，自定义连接器（.mez 文件）负责在 Power BI Desktop 的数据源列表中展示 DLC，两者需配套使用。
1. 把 DlcODBCNative.mez 复制到下面这个目录（如果目录不存在请手动创建）：
%USERPROFILE%\\Documents\\Power BI Desktop\\Custom Connectors\\完整示例路径：
C:\\Users\\<您的用户名>\\Documents\\Power BI Desktop\\Custom Connectors\\DlcODBCNative.mez说明：
这个步骤不需要管理员权限，是用户级的部署。
开启自定义连接器加载
1. 打开 Power BI Desktop。单击菜单栏 File（文件） > Options and Settings（选项和设置）> Option（选项）。
2. 左侧选择 GLOBAL（全局） > Security（安全性）。
3. 找到“数据扩展 区域”，选择： (Not Recommended) Allow any extension to load without validation or warning（（不推荐）允许任何扩展加载，且不发出警告或验证。）
4. 单击 OK（确定）。
5. 完全关闭并重新打开 Power BI Desktop，使连接器生效。
说明：
该选项是 Power BI Desktop 加载自定义连接器的必要条件。未开启时，获取数据列表中不会出现 DLC 数据源。
连接到 DLC
配置身份提供商与角色
本步骤用于配置 OIDC 单点登录所需的 Provider ID 与 Role ARN。
Provider ID（身份提供商）
1. 登录 腾讯云访问管理，选择左侧导航栏中的角色 > 角色 SSO，单击新建提供商。
2. 提供商类型选择 OIDC 后，按照要求填写以下字段：
身份提供商名称：自定义名称，例如 dlc_connect。
身份提供商 URL：在 Microsoft Entra 管理中心，展开 Entra ID，单击 Enterprise apps > Endpoints，从右侧面板复制 OpenID Connect metadata document 链接。在浏览器中打开该链接，搜索 issuer，将其对应的 URL 填入此处。
客户端 ID：填写 DLC 团队提供的应用客户端 ID，例如 49cf9f95-f2a1-49c5-889f-f138e3077c96。
身份提供商公钥：在上一步打开的 OpenID Connect metadata document 页面中，复制 jwks_uri 对应的链接并在浏览器中打开，将页面全部内容复制填入此处。
3. 单击下一步，确认信息无误后单击完成。
创建成功后，身份提供商列表中会出现新建的提供商，其名称即为连接时需要填写的 Provider ID。
Role ARN（角色）
1. 在访问管理控制台中，选择左侧导航栏中的角色，单击新建角色，选择身份提供商。
2. 在输入角色载体信息页面，完成以下配置后单击下一步。
身份提供商类型：选择 OIDC。
身份提供商：选择上一步创建的身份提供商，例如 dlc_connect。
设置使用条件：将键 (Key) 设置为 oidc:aud，值 (Value) 设置为对应的客户端 ID（49cf9f95-f2a1-49c5-889f-f138e3077c96）。同时注意移除默认或原有的 oidc:sub 条件项
3. 配置角色策略 (Configure role policy)：在搜索框中搜索并勾选 QCloudDLCFullaccess 策略。勾选后点击 下一步 (Next)。
4. 配置角色标签 (Configure role tags)：此项为可选配置（非强制），填写对应角色名称之后，直接点击 下一步 (Next)。
5. 审阅与创建 (Review)：在 角色名称 栏中填写对应的名称（示例：powerbi_usage）。在确认配置信息无误后，点击 完成 创建角色。
创建成功后，返回角色列表页并单击该角色进入详情页，复制 RoleArn 供后续步骤使用。
连接 DLC 数据源
1. 在 Power BI Desktop 主界面，单击获取数据 > 更多。
2. 在搜索框中输入 DLC，选中 DLC 数据源，单击连接。
说明：
填写连接信息
弹出的对话框需要填写下面这些字段。带 ‘是’ 的为必填，其他可以留空使用默认值。
字段 | 是否必填 | 应该填什么 | 在哪里找到 | 示例 |
Host | 是 | DLC 服务器的 IP 或域名 | DLC 控制台 > 数据引擎 > 连接信息 | 193.***.***.*** |
Port | 是 | 端口号，留空使用默认 | 同上 | 10009 |
Engine | 是 | 你要使用的计算引擎名称 | DLC 控制台 > 数据引擎列表 | testcaryzguo |
Resource Group | 是 | 资源组名称 | DLC 控制台 > 资源组 | default-rg-flicozfwoi |
Role ARN | 否 | CAM 角色资源标识 | 联系 IT 管理员获取 | qcs::cam::uin/***:roleName/dlc_conn_2 |
Provider ID | 否 | CAM 身份提供商 ID | 联系 IT 管理员获取 | dlc_conn_*** |
高级选项（可选）
点开高级选项还有两个字段：
字段 | 应该填什么 | 默认值 |
Catalog | DLC 目录名 | 留空 = DataLakeCatalog |
Database | 默认数据库（库名） | 留空 = 显示该 Catalog 下全部库 |
建议：第一次连接时，Catalog 和 Database 先留空，进入导航器查看当前账号能访问到的目录结构，再决定下一次是否要填具体值来缩小范围。
填好后单击确定(OK)。
选择登录方式
第一次连接会弹出登录页面，提供两种方式：
方式 A：使用组织账户登录（推荐）
适用于使用企业邮箱直接登录、无需维护密钥的场景。
1. 在登录页面左侧选择组织账户，单击登录。
2. 在浏览器弹窗中输入企业邮箱与密码，完成多因素认证（MFA）。
3. 返回 Power BI Desktop，单击连接。
如果目前还没有 DLC 访问权限，浏览器登录后会报 AADSTS50105 之类的错误，请联系 IT 管理员把对应账号加入 DLC 应用授权列表。在使用方式 A 的时候需要取消 Use updated sign-in experience for data sources（对数据源使用更新的登录体验）
方式 B：使用服务账号密钥登录
适用于使用专用服务账号、报表发布后需无人值守定时刷新，或无法使用组织账户登录的场景。
1. 在登录页面左侧选择 Basic（基本）。
2. 用户名填写由引擎名称与资源组名称组成的字符串，格式为 {Engine}&{ResourceGroup}，例如 testengine&default-rg-xxxxxxxx。
{Engine} & {ResourceGroup}
3. 密码填写 DLC 访问密钥的 SecretId 与 SecretKey。
4. 单击连接。
说明：
用户名中的分隔符为英文半角 &，不能使用空格或全角字符 ＆。
加载数据到报表
登录成功后进入导航器，数据按 Catalog（目录）> Database（数据库）> Table（数据表） 三层结构组织。
Catalog（目录）└── Database（库）└── Table（表）
1. 在左侧展开目标 Catalog，例如 DataLakeCatalog。
2. 展开目标 Database。
3. 勾选需要的 Table，支持多选。右侧会显示数据预览。
4. 确认无误后，单击下方按钮完成加载。
加载：将数据直接导入报表。
转换数据：进入 Power Query 编辑器，完成数据清洗后再加载。
导航器中可正常预览表数据，且报表字段列表中出现对应字段，表示连接成功。
编写自定义 SQL (可选)
如果无需通过导航器选表，希望直接使用 SQL 语句提取数据，可采用以下任意一种方式。
方式 1：在 Power Query 编辑器中编写 SQL
1. 在导航器中单击 Transform Data（转换数据），进入 Power Query 编辑器。
2. 在 Power Query 编辑器顶栏中，单击 Advanced Editor（高级编辑器）。
3. 将代码修改为以下形式，并替换为实际的连接参数。
letSource = DLC.Query("193.112.237.177", // Host"10009", // Port"testcaryzguo", // Engine"default-rg-flicozfwoi", // Resource Group"qcs::cam::uin/100018379117:roleName/dlc_conn_2","dlc_conn_2",[Catalog = "DataLakeCatalog"]),Result = Source("SELECT * FROM your_db.your_table LIMIT 100")inResult
方式 2：建立连接时直接键入本机 SQL
在 Power BI Desktop 中，通过 Get Data (获取数据) > DLC 建立连接时，可在高级选项中勾选 使用 Native Query（本机查询）并直接输入 SQL 语句。
说明：
SQL 语法兼容 Apache Spark 与 Apache Kyuubi，支持 LIMIT n、SELECT ... FROM catalog.database.table 以及标准聚合函数等。
选择数据连接模式
DLC 连接器支持 Power BI 的两种核心数据连接模式，可根据业务场景灵活选择：
对比维度 | Import（导入模式） | DirectQuery（直连模式） |
工作方式 | 数据从 DLC 一次性加载并保存在本地 .pbix 文件中 | 每次浏览或操作报表时，实时向 DLC 发起查询 |
性能 | 报表交互响应快 | 响应速度取决于 DLC 引擎的计算能力与负载 |
数据新鲜度 | 需手动或定时刷新后才能更新数据 | 数据实时同步，始终保持最新 |
文件大小 | 较大 | 较小 |
适用场景 | 数据量较小（千万行以内），对交互响应速度要求较高 | 数据量较大，需要实时获取最新数据 |
说明：
连接器默认采用 Import 模式。如需切换为 DirectQuery 模式，可在导航器数据加载阶段进行勾选设置。
常见问题
Q1：获取数据中搜索不到 DLC 数据源怎么办？
请依次排查以下事项：
1. 安装 ODBC 驱动的 MSI 安装是否成功？控制面板 → 程序与功能里应该能看到 DLC Spark ODBC Driver
2. 部署 Power BI 连接器的 .mez 文件是否复制到 %USERPROFILE%\\Documents\\Power BI Desktop\\Custom Connectors\\ 了？
3. 允许 Power BI 加载自定义连接器的安全设置（数据扩展 > 允许任何扩展加载）是否勾选？
4. 是否完整重启了 Power BI Desktop（不是最小化）？
5. 是否使用 64 位 Power BI Desktop？
# ODBC 驱动是否注册Get-ItemProperty "HKLM:\\SOFTWARE\\ODBC\\ODBCINST.INI\\DLC Spark ODBC Driver"# .mez 是否到位Test-Path "$env:USERPROFILE\\Documents\\Power BI Desktop\\Custom Connectors\\DlcODBCNative.mez"
Q2：单击“连接”后长时间没反应怎么办？
DLC 引擎需要时间冷启动，首次连接可能需要 1–3 分钟。如果超过 5 分钟仍无响应：
在 DLC 控制台确认引擎处于"运行中"。
检查本机网络能否访问 Host:Port（命令行 Test-NetConnection 193.***.***.*** -Port 10009）。
Q3：组织账户登录浏览器后报错怎么办？
错误码 | 含义 | 怎么办 |
AADSTS50105 | 账号未授权访问 DLC 应用 | 联系 IT 管理员加入授权列表 |
AADSTS65001 | 用户未同意权限 | 让管理员授予租户级同意 |
AADSTS50011 | 重定向 URI 不匹配 | 反馈给 DLC 团队 |
Q4：报错"令牌已过期"或定时刷新失败怎么办？
access_token 默认有效期较短。对于需要长期定时刷新的报表，建议改用第 2.3 节的"基本"方式登录，密码填长期有效的 DLC 服务账号密钥。
Q5：查询很慢 / 内存爆掉怎么办？
在 SQL 里加入 LIMIT n 或 WHERE 条件减少返回行数。
用 SELECT col1, col2 只取需要的列，避免 SELECT *。
数据量超过千万行优先考虑 DirectQuery 模式 。
Q6：中文显示乱码怎么办？
确认 Power BI Desktop 是 64 位版本。如仍乱码，请联系 DLC 支持团队，并提供以下信息：
出现乱码的字段名 + 一行示例
DLC 控制台中该字段的实际内容截图
Q7：日期时间字段差 8 小时怎么办？
DLC 默认按 UTC 存储时间。在 Power Query 编辑器中右键单击该列，选择转换 > 时区 > 转换为本地时间即可。
Q8：怎么把报表发布到 Power BI 服务并定时刷新？
Q9：导航中看不到数据表怎么办？
现象 | 原因 | 解决 |
导航器呈现空白 | 高级选项中填写的 Catalog 名称有误 | 断开并退出当前连接，将 Catalog 栏位留空后重新尝试连接。 |
只看到一两张表 | 高级选项中填写的 Database 限定了查询范围 | 将 Database 栏位留空，即可加载全部数据库与表视图。 |
提示"键与表中任何行均不匹配" | 填写的 Catalog 或 Database 名称不存在 | 登录 DLC 控制台 核对实际的 Catalog 与 Database 名称（请特别注意区分大小写）。 |
文档反馈