你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure Cosmos DB ODBC 驱动程序连接到 BI 和数据分析工具

  • 项目

适用范围： NoSQL

本文指导你安装和使用 Azure Cosmos DB ODBC 驱动程序来为 Azure Cosmos DB 数据创建规范化的表和视图。 可以使用 SQL 查询来查询规范化数据，或者将数据导入 Power BI 或其他 BI 和分析软件，以创建报表和可视化效果。

Azure Cosmos DB 是一个无架构数据库，可用于快速开发应用程序并对数据模型进行迭代，而不受限于严格的架构。 一个 Azure Cosmos DB 数据库可以包含各种结构的 JSON 文档。 若要分析或报告此数据，可能需要平展数据，使其可以装入架构。

ODBC 驱动程序将 Azure Cosmos DB 数据规范化为符合数据分析和报告需求的表与视图。 规范化的架构让你可以使用符合 ODBC 规范的工具来访问数据。 该架构对基础数据没有影响，因此不要求开发人员遵守它们。 ODBC 驱动程序可以帮助数据分析师和开发团队利用 Azure Cosmos DB 数据库。

可以针对规范化的表和视图执行 SQL 操作，包括按查询、插入、更新和删除操作分组。 该驱动程序符合 ODBC 3.8 规范，并支持 ANSI SQL-92 语法。

重要

请考虑使用 Azure Synapse Link for Azure Cosmos DB 为数据创建表和视图。 与 ODBC 驱动程序相比，Synapse Link 在大型数据集方面具有明显的性能优势。 还可将规范化 Azure Cosmos DB 数据连接到其他软件解决方案，例如 SQL Server Integration Services (SSIS)、QlikSense、Tableau 及其他分析软件、BI 和数据集成工具。 可以使用这些解决方案来分析、移动、转换 Azure Cosmos DB 数据以及创建包含这些数据的可视化效果。

重要

  • 目前只有 Azure Cosmos DB for NoSQL 支持使用 ODBC 驱动程序连接到 Azure Cosmos DB。
  • 当前的 ODBC 驱动程序不支持聚合下推，并且许多分析工存在一些已知问题。 在新版本发布之前，可使用以下替代方案之一：

安装 ODBC 驱动程序并连接到数据库

  1. 下载适用于环境的驱动程序：

    安装程序 支持的操作系统
    Microsoft Azure Cosmos DB ODBC 64-bit.msi（适用于 64 位 Windows） 64 位版本的 Windows 8.1 或更高版本，Windows 8、Windows 7。 64 位版本的 Windows Server 2012 R2、Windows Server 2012 和 Windows Server 2008 R2。
    Microsoft Azure Cosmos DB ODBC 32x64-bit.msi（适用于 32 位或 64 位 Windows） 64 位版本的 Windows 8.1 或更高版本、Windows 8、Windows 7、Windows XP 和 Windows Vista。 64 位版本的 Windows Server 2012 R2、Windows Server 2012、Windows Server 2008 R2 和 Windows Server 2003。
    Microsoft Azure Cosmos DB ODBC 32-bit.msi（适用于 32 位 Windows） 32 位的 Windows 8.1 或更高版本、Windows 8、Windows 7、Windows XP 和 Windows Vista。

  2. 在本地运行 .msi 文件，启动“Microsoft Azure Cosmos DB ODBC 驱动程序安装向导”。

  3. 使用默认输入完成安装向导。

  4. 安装驱动程序后，在 Windows 搜索框中键入“ODBC 数据源”，然后打开“ODBC 数据源管理器”。

  5. 确保“驱动程序”选项卡上列出了“Microsoft Azure DocumentDB ODBC 驱动程序”。

    “ODBC 数据源管理器”窗口的屏幕截图。

  6. 选择“用户 DSN”选项卡，然后选择“添加”以创建新的数据源名称 (DSN)。 还可以创建系统 DSN。

  7. 在“创建新数据源”窗口中选择“Microsoft Azure DocumentDB ODBC 驱动程序”，然后选择“完成”。

  8. 在“DocumentDB ODBC 驱动程序 DSN 设置”窗口中填写以下信息：

    域名服务器 (DNS) 设置窗口的屏幕截图。

    • 数据源名称：ODBC DSN 的易记名称。 此名称对于此 Azure Cosmos DB 帐户是唯一的。
    • 说明：数据源的简短说明。
    • 主机：Azure Cosmos DB 帐户的 URI。 可以从 Azure 门户上 Azure Cosmos DB 帐户中的“密钥”页获取此信息。
    • 访问密钥：Azure 门户上 Azure Cosmos DB“密钥”页中的主要或辅助读写或只读密钥。 如果你使用 DSN 进行只读数据处理和报告，则最好使用只读密钥。

    为了避免身份验证错误，请在 Azure 门户中使用复制按钮复制 URI 和密钥。

    Azure Cosmos DB“密钥”页的屏幕截图。

    • 加密以下对象的访问密钥：根据此计算机的用户选择最合适的选项。

  9. 选择“测试”，确保可以连接到 Azure Cosmos DB 帐户。

  10. 选择“高级选项”并设置以下值：

    • REST API 版本：选择操作的 REST API 版本。 默认值为“2015-12-16”。

      如果容器的大型分区键需要 REST API 版本 2018-12-31，请键入“2018-12-31”，然后按照本过程末尾的步骤操作。

    • 查询一致性：选择操作的一致性级别。 默认值为“会话”。

    • 重试次数：输入当初始请求因服务速率限制而未能完成时，重试操作的次数。

    • 架构文件：如果你未选择架构文件，驱动程序将扫描每个容器的第一页数据以确定每个会话的容器架构（称为容器映射）。 此过程可能会导致使用 DSN 的应用程序启动时间变长。 最好将架构文件关联到 DSN。

      • 如果你已有架构文件，请选择“浏览”，导航到该文件，选择“保存”，然后选择“确定”。

      • 如果你没有架构文件，请选择“确定”，然后按照下一部分所述的步骤创建架构定义。 创建架构后，返回此“高级选项”窗口以添加架构文件。

在选择“确定”完成并关闭“DocumentDB ODBC 驱动程序 DSN 设置”窗口后，新的用户 DSN 将显示在“ODBC 数据源管理器”窗口的“用户 DSN”选项卡上。

显示“用户 DSN”选项卡上新用户 DSN 的屏幕截图。

编辑 Windows 注册表以支持 REST API 版本 2018-12-31

如果容器的大分区键需要 REST API 版本 2018-12-31，请按照以下步骤更新 Windows 注册表以支持此版本。

  1. 在 Windows“开始”菜单中，键入“regedit”以查找并打开“注册表编辑器”。

  2. 在注册表编辑器中，导航到路径 Computer\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI。

  3. 创建与 DSN 同名的新子项，例如“Contoso Account ODBC DSN”。

  4. 导航到新的“Contoso Account ODBC DSN”子项，然后右键单击以添加新的字符串值：

    • 值名称：IgnoreSessionToken

    • 值数据：1

    显示 Windows 注册表编辑器设置的屏幕截图。

创建架构定义

可以使用两种类型的采样方法来创建架构：容器映射或表分隔符映射。 一个采样会话可以使用两种采样方法，但每个容器只能使用一种采样方法。 要使用哪种方法取决于数据的特征。

  • 容器映射检索容器页上的数据以确定数据结构，并将容器转置为 ODBC 端上的表。 如果容器中的数据是同构的，此采样方法十分快速高效。

  • 表分隔符映射为异构数据提供更可靠的采样。 此方法将采样范围限定为一组属性和相应值。

    例如，如果某个文档包含“Type”属性，可将采样范围限定为此属性的值。 采样的最终结果是指定的每个 Type 值的一组表。 如果 Type = Car，则会生成 Car 表；如果 Type = Plane，则会生成 Plane 表。

若要定义架构，请执行以下步骤。 对于表分隔符映射方法，需要执行额外的步骤来定义架构的属性和值。

  1. 在“ODBC 数据源管理器”窗口的“用户 DSN”选项卡上，选择你的 Azure Cosmos DB 用户 DSN 名称，然后选择“配置”。

  2. 在“DocumentDB ODBC 驱动程序 DSN 设置”窗口中，选择“架构编辑器”。

    显示“DSN 设置”窗口中“架构编辑器”按钮的屏幕截图。

  3. 在“架构编辑器”窗口中选择“新建”。

  4. “生成架构”窗口会显示 Azure Cosmos DB 帐户中的所有集合。 选中要采样的容器旁边的复选框。

  5. 若要使用容器映射方法，请选择“采样”。

    或者，若要使用表分隔符映射，请执行以下步骤来定义采样范围的属性和值。

    1. 在 DSN 的“映射定义”列中选择“编辑”。

    2. 在“映射定义”窗口中的“映射方法”下，选择“表分隔符”。

    3. 在“属性”框中，键入要将采样范围限定到的文档中某个分隔符属性的名称，例如“City”。 按 Enter。

    4. 如果要将采样范围限定为输入的属性的特定值，请选择该属性，在“值”框中输入一个值（例如“Seattle”），然后按 Enter 键。 可为属性添加多个值。 在输入值时，请确保选择正确的属性。

    5. 输入属性和值后，选择“确定”。

    6. 在“生成架构”窗口中选择“采样”。

  6. 在“设计视图”选项卡中调整架构。 “设计视图”显示数据库、架构和表。 表视图显示与列名称（例如“SQL 名称”和“源名称”）关联的属性集。

    对于每个列，在适用的情况下可以修改“SQL 名称”、“SQL 类型”、“SQL 长度”、“标度”、“精度”和“可为 Null”。

    如果想要从查询结果中排除某个列，可将对应的“隐藏列”设置为 true。 标记为“隐藏列 = true”的列不会返回供选择和投影，不过它们仍是架构的一部分。 例如，可以隐藏以“_”开头的所有 Azure Cosmos DB 系统必需属性。 “id”列是唯一一个不能隐藏的字段，因为它是规范化架构中的主键。

  7. 完成架构定义后，选择“文件”>“保存”，导航到要保存到的目录，然后选择“保存”。

  8. 若要将此架构与 DSN 配合使用，请在“DocumentDB ODBC 驱动程序 DSN 设置”窗口中选择“高级选项”。 选中“架构文件”框，导航到保存的架构，选择“确定”，然后再次选择“确定”。 保存架构文件会将 DSN 连接的范围修改为架构定义的数据和结构。

创建视图

（可选）在采样过程中，可以在“架构编辑器”中定义和创建视图。 这些视图相当于 SQL 视图。 这些视图是只读的，其范围限定为定义的 Azure Cosmos DB SQL 查询的选择和投影。

按照以下步骤为数据创建视图：

  1. 在“架构编辑器”窗口的“采样视图”选项卡上，选择要采样的容器，然后在“视图定义”列中选择“添加”。

    在驱动程序中创建视图的屏幕截图。

  2. 在“视图定义”窗口中，选择“新建”。 输入视图的名称（例如“EmployeesfromSeattleView”），然后选择“确定”。

  3. 在“编辑视图”窗口中输入一个 Azure Cosmos DB 查询，例如：

    SELECT c.City, c.EmployeeName, c.Level, c.Age, c.Manager FROM c WHERE c.City = "Seattle"

  4. 选择“确定” 。

    在创建视图时添加查询的屏幕截图。

可以创建任意数量的视图。 定义视图后，选择“采样”以采样数据。

重要

视图定义中的查询文本不应包含换行符。 否则，在预览视图时，我们会收到一般性错误。

使用 SQL Server Management Studio 进行查询

设置 Azure Cosmos DB ODBC 驱动程序用户 DSN 后，可以通过设置链接服务器连接从 SQL Server Management Studio (SSMS) 查询 Azure Cosmos DB。

  1. 安装 SQL Server Management Studio 并连接到服务器。

  2. 在 SSMS 查询编辑器中，通过运行以下命令为数据源创建链接服务器对象。 请将 DEMOCOSMOS 替换为你的链接服务器名称，将 SDS Name 替换为你的数据源名称。

    USE [master]
GO

EXEC master.dbo.sp_addlinkedserver @server = N'DEMOCOSMOS', @srvproduct=N'', @provider=N'MSDASQL', @datasrc=N'SDS Name'

EXEC master.dbo.sp_addlinkedsrvlogin @rmtsrvname=N'DEMOCOSMOS', @useself=N'False', @locallogin=NULL, @rmtuser=NULL, @rmtpassword=NULL

GO

若要查看新的链接服务器名称，请刷新链接服务器列表。

显示 SSMS 中链接服务器的屏幕截图。

若要查询链接的数据库，请输入 SSMS 查询。 在此示例中，查询从名为 customers 的容器的表中选择：

SELECT * FROM OPENQUERY(DEMOCOSMOS, 'SELECT *  FROM [customers].[customers]')

执行查询。 结果应类似于以下输出：

attachments/  1507476156    521 Bassett Avenue, Wikieup, Missouri, 5422   "2602bc56-0000-0000-0000-59da42bc0000"   2015-02-06T05:32:32 +05:00 f1ca3044f17149f3bc61f7b9c78a26df
attachments/  1507476156    167 Nassau Street, Tuskahoma, Illinois, 5998   "2602bd56-0000-0000-0000-59da42bc0000"   2015-06-16T08:54:17 +04:00 f75f949ea8de466a9ef2bdb7ce065ac8
attachments/  1507476156    885 Strong Place, Cassel, Montana, 2069       "2602be56-0000-0000-0000-59da42bc0000"   2015-03-20T07:21:47 +04:00 ef0365fb40c04bb6a3ffc4bc77c905fd
attachments/  1507476156    515 Barwell Terrace, Defiance, Tennessee, 6439     "2602c056-0000-0000-0000-59da42bc0000"   2014-10-16T06:49:04 +04:00      e913fe543490432f871bc42019663518
attachments/  1507476156    570 Ruby Street, Spokane, Idaho, 9025       "2602c156-0000-0000-0000-59da42bc0000"   2014-10-30T05:49:33 +04:00 e53072057d314bc9b36c89a8350048f3

在 Power BI Desktop 中查看数据

可以使用 DSN 通过任何符合 ODBC 规范的工具连接到 Azure Cosmos DB。 此过程说明如何连接到 Power BI Desktop 以创建 Power BI 可视化效果。

  1. 在 Power BI Desktop 中，选择“获取数据” 。

    显示 Power BI Desktop 中的“获取数据”的屏幕截图。

  2. 在“获取数据”窗口中，选择“其他”>“ODBC”，然后选择“连接”。

    显示在 Power BI“获取数据”中选择 ODBC 数据源的屏幕截图。

  3. 在“从 ODBC”窗口中选择创建的 DSN，然后选择“确定”。

    显示在 Power BI“获取数据”中选择 DSN 的屏幕截图。

  4. 在“使用 ODBC 驱动程序访问数据源”窗口中，选择“默认或自定义”，然后选择“连接”。

  5. 在“导航器”窗口的左侧窗格中展开数据库和架构，然后选择表。 结果窗格包含使用创建的架构的数据。

    在 Power BI“获取数据”中选择表的屏幕截图。

  6. 若要可视化 Power BI Desktop 中的数据，请选中表名称旁边的复选框，然后选择“加载”。

  7. 在 Power BI Desktop 中，选择屏幕左侧的“数据”选项卡以确认数据是否已导入。

  8. 选择屏幕左侧的“报表”选项卡，从功能区中选择“新建视觉对象”，然后自定义视觉对象。

疑难解答

  • 问题：尝试连接时会出现以下错误：

    [HY000]: [Microsoft][Azure Cosmos DB] (401) HTTP 401 Authentication Error: {"code":"Unauthorized","message":"The input authorization token can't serve the request. Please check that the expected payload is built as per the protocol, and check the key being used. Server used the following payload to sign: 'get\ndbs\n\nfri, 20 jan 2017 03:43:55 gmt\n\n'\r\nActivityId: 9acb3c0d-cb31-4b78-ac0a-413c8d33e373"}

    解决方法：确保从 Azure 门户复制的“主机”和“访问密钥”值正确，然后重试。

  • 问题：尝试创建 Azure Cosmos DB 链接服务器时，SSMS 中出现以下错误：

    Msg 7312, Level 16, State 1, Line 44

Invalid use of schema or catalog for OLE DB provider "MSDASQL" for linked server "DEMOCOSMOS". A four-part name was supplied, but the provider does not expose the necessary interfaces to use a catalog or schema.

    解决方法：Azure Cosmos DB 链接服务器不支持四部分命名。

后续步骤