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

配置和使用适用于Azure Cosmos DB 的 Azure Synapse Link

项目
08/15/2024

适用对象： NoSQL MongoDB Gremlin

Azure Synapse Link for Azure Cosmos DB 是一种云原生混合事务和分析处理 (HTAP) 功能，可用于对 Azure Cosmos DB 中的操作数据运行准实时分析。 Synapse Link 在 Azure Cosmos DB 和 Azure Synapse Analytics 之间建立紧密的无缝集成。

重要

Microsoft Fabric 中的镜像现已推出预览版，可用于 NoSql API。此功能提供 Azure Synapse Link 的所有功能，具有更好的分析性能，能够将数据资产与 Fabric OneLake 统一，并支持开放访问 OneLake 中 Delta Parquet 格式的数据。如果考虑使用 Azure Synapse Link，建议尝试镜像以评估它在组织中的整体适合情况。若要开始使用镜像，请单击此处。

Azure Synapse Link 可用于 Azure Cosmos DB SQL API 帐户或 Azure Cosmos DB API for Mongo DB 帐户。它在 Gremlin API 中以预览版提供，可通过 CLI 命令激活。使用以下步骤，通过 Azure Synapse Link for Azure Cosmos DB 运行分析查询：

为 Azure Cosmos DB 帐户启用 Azure Synapse Link
为容器启用 Azure Synapse Link
将 Azure Cosmos DB 数据库连接到 Azure Synapse 工作区
使用 Azure Synapse Analytics 查询分析存储
使用最佳做法提高性能
使用 Azure Synapse 无服务器 SQL 池在 Power BI 中分析和可视化数据

还可查看培训模块，了解如何为 Azure Cosmos DB 配置 Azure Synapse Link。

启用 Azure Synapse Link for Azure Cosmos DB 帐户

若要使用 Synapse Link，第一步是为 Azure Cosmos DB 数据库帐户启用它。

注意

如果要将客户管理的密钥用于 Azure Synapse Link，必须在 Azure Key Vault 访问策略中配置帐户的托管标识，然后才能在你的帐户上启用 Synapse Link。若要了解详细信息，请参阅如何使用 Azure Cosmos DB 帐户的托管标识配置客户管理的密钥一文。

注意

如果要对 API for NoSQL 帐户使用完全保真架构，则无法使用 Azure 门户来启用 Synapse Link。在你的帐户中启用 Synapse Link 后便无法更改此选项，必须使用 Azure CLI 或 PowerShell 进行设置。有关详细信息，请查看分析存储架构表示文档。

注意

需要“参与者”角色才能在帐户级别启用 Synapse Link。并且至少需要为“操作员”才能在容器或集合中启用 Synapse Link。

Azure 门户

登录 Azure 门户。
创建新的 Azure 帐户，或选择现有的 Azure Cosmos DB 帐户。
导航到你的 Azure Cosmos DB 帐户，打开左侧窗格的“集成”下的“Azure Synapse Link”。
选择“启用”。此过程可能需要 1 到 5 分钟才能完成。
你的帐户现已启用，可以使用 Synapse Link。接下来，了解如何创建启用了分析存储的容器，以便自动开始将操作数据从事务性存储复制到分析存储。

注意

启用 Synapse Link 不会自动启用分析存储。在 Cosmos DB 帐户上启用 Synapse Link 后，启用容器上的分析存储，开始使用 Synapse Link。

注意

还可使用左侧导航菜单“集成”部分中的“Power BI”和“Synapse Link”窗格为帐户启用 Synapse Link。

命令行工具

使用 Azure CLI 或 PowerShell 在 Azure Cosmos DB API for NoSQL 或 MongoDB 帐户中启用 Synapse Link。

Azure CLI

对于“create”或“update”操作，请使用 --enable-analytical-storage true 。你还需要选择表示形式架构类型。对于 API for NoSQL 帐户，可将 --analytical-storage-schema-type 与值 FullFidelity 或 WellDefined 一起使用。对于 API for MongoDB 帐户，请始终使用 --analytical-storage-schema-type FullFidelity。

使用 Azure CLI 为 Azure Synapse Link for Gremlin API 帐户启用 Synapse Link。

Synapse Link for Gremlin API 现为预览版。可以使用 Azure CLI 在新图形或现有图形中启用 Synapse Link。使用下面的 CLI 命令为 Gremlin API 帐户启用 Synapse Link：

az cosmosdb create --capabilities EnableGremlin --name MyCosmosDBGremlinDatabaseAccount --resource-group MyResourceGroup --enable-analytical-storage true

对于现有的 Gremlin API 帐户，请将 create 替换为 update。

PowerShell

对于“create”或“update”操作，请使用 EnableAnalyticalStorage true 。你还需要选择表示形式架构类型。对于 API for NoSQL 帐户，可将 --analytical-storage-schema-type 与值 FullFidelity 或 WellDefined 一起使用。对于 API for MongoDB 帐户，请始终使用 -AnalyticalStorageSchemaType FullFidelity。

Azure 资源管理器模板

此 Azure 资源管理器模板会为 SQL API 创建启用了 Synapse Link 的 Azure Cosmos DB 帐户。此模板在一个区域中创建一个 Core (SQL) API 帐户，其中包含配置了启用分析 TTL 的容器和一个选择使用手动或自动缩放吞吐量的选项。若要部署此模板，请在自述文件页上单击“部署到 Azure”。

为容器启用 Azure Synapse Link

第二步是为容器或集合启用 Synapse Link。这是通过将 analytical TTL 属性设置为 -1 以实现无限保留或设置为正整数（即要在分析存储中保留的秒数）来实现的。此设置之后可更改。有关详细信息，请参阅分析 TTL 支持的值一文。

在现有的 SQL API 容器上启用 Azure Synapse Link 时，请注意以下详细信息：

分析存储自动同步过程的相同性能隔离适用于初始同步，并且对 OLTP 工作负载没有性能影响。
容器与分析存储的初始同步总时间会因数据量和文档复杂性而异。此过程可能需要几秒钟到几天的时间。请使用 Azure 门户监视迁移进度。
容器或数据库帐户的吞吐量也会影响初始同步总时间。尽管在此迁移中不使用 RU/s，但可用的总 RU/s 会影响进程的性能。可临时增加环境的可用 RU，以加快该过程。
在现有容器上启用了 Synapse Link 时，你无法查询该容器的分析存储。 OLTP 工作负载不会受到影响，你可以继续正常读取数据。初始同步开始后引入的数据将通过常规分析存储自动同步过程合并到分析存储中。

注意

现在，可以使用 Azure CLI 或 PowerShell 在现有 MongoDB API 集合上启用 Synapse Link。

Azure 门户

新建容器

登录到 Azure 门户或 Azure Cosmos DB 资源管理器。
导航到你的 Azure Cosmos DB 帐户，打开“数据资源管理器”选项卡。
选择“新容器”，并输入数据库、容器、分区键和吞吐量详细信息的名称。打开“分析存储”选项。启用分析存储后，它将创建一个容器，该容器的 analytical TTL 属性设置为默认值 -1（无限保留期）。此分析存储保留所有记录的历史版本，并可在以后更改。
如果你以前未在此帐户上启用 Synapse Link，系统将提示你执行此操作，因为它是创建启用了分析存储的容器的先决条件。如果系统提示，请选择“启用 Synapse Link”。此过程可能需要 1 到 5 分钟才能完成。
选择“确定”，创建启用了分析存储的 Azure Cosmos DB 容器。
创建容器后，通过单击数据资源管理器中“文档”正下方的“设置”，验证分析存储是否已启用，并检查“分析存储生存时间”选项是否已启用。

现有容器

登录到 Azure 门户或 Azure Cosmos DB 资源管理器。
导航到你的 Azure Cosmos DB 帐户，打开“Azure Synapse Link”选项卡。
在“为容器启用 Azure Synapse Link”部分下，选择容器。
启用容器后，通过单击数据资源管理器中“文档”正下方的“设置”，验证分析存储是否已启用，并检查“分析存储生存时间”选项是否已启用。

注意

还可使用左侧导航菜单“集成”部分中的“Power BI”和“Synapse Link”窗格为帐户启用 Synapse Link。

命令行工具

Azure CLI

以下选项通过设置 --analytical-storage-ttl 属性使用 Azure CLI 在容器中启用 Synapse Link。

使用 Azure CLI 为 Azure Synapse Link for Gremlin API 图形启用 Synapse Link

Synapse Link for Gremlin API 现为预览版。可以使用 Azure CLI 在新图形或现有图形中启用 Synapse Link。使用下面的 CLI 命令为 Gremlin API 图形启用 Synapse Link：

az cosmosdb gremlin graph create --g MyResourceGroup --a MyCosmosDBGremlinDatabaseAccount --d MyGremlinDB --n MyGraph --analytical-storage-ttl –1

对于现有图形，请将 create 替换为 update。

PowerShell

以下选项通过设置 -AnalyticalStorageTtl 属性使用 Azure CLI 在容器中启用 Synapse Link。

Azure Cosmos DB SDK - 仅限 SQL API

.NET SDK

以下 .NET 代码通过设置 AnalyticalStoreTimeToLiveInSeconds 属性创建启用了 Synapse Link 的容器。若要更新现有容器，请使用 Container.ReplaceContainerAsync 方法。

CosmosClient cosmosClient = new CosmosClient(
    accountEndpoint: "<nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

// Create a container with a partition key, and analytical TTL configured to -1 (infinite retention)
ContainerProperties properties = new ContainerProperties()
{
    Id = "myContainerId",
    PartitionKeyPath = "/id",
    AnalyticalStoreTimeToLiveInSeconds = -1,
};
await cosmosClient.GetDatabase("myDatabase").CreateContainerAsync(properties);

Java V4 SDK

以下 Java 代码通过设置 setAnalyticalStoreTimeToLiveInSeconds 属性创建启用了 Synapse Link 的容器。若要更新现有容器，请使用 container.replace 类。

// Create a container with a partition key and  analytical TTL configured to  -1 (infinite retention) 
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");

containerProperties.setAnalyticalStoreTimeToLiveInSeconds(-1);

container = database.createContainerIfNotExists(containerProperties, 400).block().getContainer();

Python V4 SDK

以下 Python 代码通过设置 analytical_storage_ttl 属性创建启用了 Synapse Link 的容器。若要更新现有容器，请使用 replace_container 方法。

# Client
client = cosmos_client.CosmosClient(HOST,  KEY )

# Database client
try:
    db = client.create_database(DATABASE)

except exceptions.CosmosResourceExistsError:
    db = client.get_database_client(DATABASE)

# Creating the container with analytical store enabled
try:
    container = db.create_container(
        id=CONTAINER,
        partition_key=PartitionKey(path='/id', kind='Hash'),analytical_storage_ttl=-1
    )
    properties = container.read()
    print('Container with id \'{0}\' created'.format(container.id))
    print('Partition Key - \'{0}\''.format(properties['partitionKey']))

except exceptions.CosmosResourceExistsError:
    print('A container with already exists')

连接到 Synapse 工作区

使用连接到 Azure Synapse Link 中的说明，了解如何使用 Azure Synapse Link 从 Azure Synapse Analytics Studio 访问 Azure Cosmos DB 数据库。

使用 Azure Synapse Analytics 查询分析存储

使用适用于 Azure Synapse Analytics 的 Apache Spark 查询分析存储

参照使用 Spark 3 查询 Azure Cosmos DB 分析存储一文中的说明，了解如何使用 Synapse Spark 3 进行查询。这篇文章提供了一些示例，说明如何通过 Synapse 笔势与分析存储交互。右键单击某个容器时，即可看到这些笔势。借助笔势，可以快速生成代码，并根据需要进行调整。它们还适用于只需单击一下即可发现数据的功能。

对于 Spark 2 集成，请参照使用 Spark 2 查询 Azure Cosmos DB 分析存储一文中的说明。

在 Azure Synapse Analytics 中使用无服务器 SQL 池查询分析存储

利用无服务器 SQL 池，可以查询和分析启用了 Azure Synapse Link 的 Azure Cosmos DB 容器中的数据。可以以近乎实时的方式分析数据，而不会影响事务工作负载的性能。它提供熟悉的 T-SQL 语法，用于从分析存储中查询数据，并且通过 T-SQL 接口提供了到各种 BI 和即席查询工具的集成连接。若要详细了解，请参阅使用无服务器 SQL 池查询分析存储一文。

使用无服务器 SQL 池在 Power BI 中分析和可视化数据

你可以通过 Azure Cosmos DB 门户中的集成 BI 体验，使用 Synapse Link 生成 BI 仪表板，只需单击几下便可。若要了解详细信息，请参阅如何使用 Synapse Link 构建 BI 仪表板。此集成体验将在 Synapse 无服务器 SQL 池中为你的 Azure Cosmos DB 容器创建简单的 T-SQL 视图。你可以基于这些视图构建 BI 仪表板，这些视图使用直接查询实时查询 Azure Cosmos DB 容器，反映数据的最新更改。对事务工作负载没有任何性能或成本影响，也不存在管理 ETL 管道的复杂性。

如果要使用高级 T-SQL 视图和跨容器的联接，或在导入模式下生成 Power BI 仪表板，请参阅使用无服务器 SQL 池通过 Synapse Link 分析 Azure Cosmos DB 数据。

使用最佳做法提高性能

自定义分区

通过自定义分区，你可以在分析查询中对通常用作筛选器的字段上的分析存储数据进行分区，从而提高查询性能。 若要了解详细信息，请参阅自定义分区简介和如何配置自定义分区这两篇文章。

Azure Synapse Link for Cosmos DB 的 Synapse SQL 无服务器最佳做法

使用 SQL 无服务器查询的这项强制性最佳做法。

Azure Synapse Link 入门 - 示例

可以在 GitHub 上找到有关 Azure Synapse Link 入门的示例。这些示例展示了物联网和零售场景的端到端解决方案。也可以在 MongoDB 文件夹下的同一存储库中找到与 Azure Cosmos DB for MongoDB 对应的示例。

后续步骤

若要了解更多信息，请参阅下列文档：

请查看培训模块，了解如何为 Azure Cosmos DB 配置 Azure Synapse Link。
Azure Cosmos DB 分析存储概述。
有关 Azure Synapse Link for Azure Cosmos 的常见问题。
Azure Synapse Analytics 中的 Apache Spark。
Azure Synapse Analytics 中的无服务器 SQL 池运行时支持。

通过

配置和使用适用于Azure Cosmos DB 的 Azure Synapse Link

启用 Azure Synapse Link for Azure Cosmos DB 帐户

Azure 门户

命令行工具

Azure CLI

使用 Azure CLI 为 Azure Synapse Link for Gremlin API 帐户启用 Synapse Link。

PowerShell

Azure 资源管理器模板

为容器启用 Azure Synapse Link

Azure 门户

新建容器

现有容器

命令行工具

Azure CLI

使用 Azure CLI 为 Azure Synapse Link for Gremlin API 图形启用 Synapse Link

PowerShell

Azure Cosmos DB SDK - 仅限 SQL API

.NET SDK

Java V4 SDK

Python V4 SDK

连接到 Synapse 工作区

使用 Azure Synapse Analytics 查询分析存储

使用适用于 Azure Synapse Analytics 的 Apache Spark 查询分析存储

在 Azure Synapse Analytics 中使用无服务器 SQL 池查询分析存储

使用无服务器 SQL 池在 Power BI 中分析和可视化数据

使用最佳做法提高性能

自定义分区

Azure Synapse Link for Cosmos DB 的 Synapse SQL 无服务器最佳做法

Azure Synapse Link 入门 - 示例

后续步骤

反馈

其他资源