配置和使用 Azure Synapse Link for Azure Cosmos DB(预览版)Configure and use Azure Synapse Link for Azure Cosmos DB (preview)

Azure Synapse Link for Azure Cosmos 是一种云原生混合事务和分析处理 (HTAP) 功能,可用于在 Azure Cosmos DB 中对操作数据运行准实时分析。Synapse Link for Azure Cosmos DB is a cloud-native hybrid transactional and analytical processing (HTAP) capability that enables you to run near real-time analytics over operational data in Azure Cosmos DB. Synapse Link 在 Azure Cosmos DB 和 Azure Synapse Analytics 之间建立紧密的无缝集成。Synapse Link creates a tight seamless integration between Azure Cosmos DB and Azure Synapse Analytics.

重要

若要使用 Azure Synapse Link,请确保在支持的区域之一预配 Azure Cosmos 帐户和 Azure Synapse Analytics 工作区。To use Azure Synapse Link, ensure you provision your Azure Cosmos account & Azure Synapse Analytics workspace in one of the supported regions. Azure Synapse Link 当前在以下 Azure 区域中提供:中国东部、中国北部 2、中国北部、中国东部 2。Azure Synapse Link is currently available in the following Azure regions: China East, China North 2, China North, China East 2.

使用以下步骤,通过 Azure Synapse Link for Azure Cosmos 运行分析查询:Use the following steps to run analytical queries with the Synapse Link for Azure Cosmos DB:

Azure 门户Azure portal

  1. 登录到 Azure 门户Sign into the Azure portal.

  2. 创建新的 Azure 帐户,或选择现有的 Azure Cosmos 帐户。Create a new Azure account, or select an existing Azure Cosmos account.

  3. 导航到你的 Azure Cosmos 帐户,打开“功能”**** 窗格。Navigate to your Azure Cosmos account and open the Features pane.

  4. 从“功能”列表选择“Synapse Link”****。Select Synapse Link from the features list.

    查找 Synapse Link 预览功能

  5. 接下来,它会提示你在帐户上启用 Synapse Link。Next it prompts you to enable synapse link on your account. 选择“启用”。Select Enable.

    查找 Synapse Link 预览功能

  6. 你的帐户现已启用,可以使用 Synapse Link。Your account is now enabled to use Synapse Link. 接下来,了解如何创建启用了分析存储的容器,以便自动开始将操作数据从事务性存储复制到分析存储。Next see how to create analytical store enabled containers to automatically start replicating your operational data from the transactional store to the analytical store.

Azure 资源管理器模板Azure Resource Manager template

Azure 资源管理器模板为 SQL API 创建启用了 Synapse Link 的 Azure Cosmos 帐户。The Azure Resource Manager template creates a Synapse Link enabled Azure Cosmos account for SQL API. 此模板在一个区域中创建一个 Core (SQL) API 帐户,其中包含配置了启用分析 TTL 的容器和一个选择使用手动或自动缩放吞吐量的选项。This template creates a Core (SQL) API account in one region with a container configured with analytical TTL enabled, and an option to use manual or autoscale throughput. 若要部署此模板,请在自述文件页上单击“部署到 Azure”****。To deploy this template, click on Deploy to Azure on the readme page.

使用分析存储创建 Azure Cosmos 容器Create an Azure Cosmos container with analytical store

创建容器时,可以在 Azure Cosmos 容器上启用分析存储。You can turn on analytical store on an Azure Cosmos container while creating the container. 可以使用 Azure 门户,或在创建容器期间使用 Azure Cosmos DB SDK 配置 analyticalTTL 属性。You can use the Azure portal or configure the analyticalTTL property during container creation by using the Azure Cosmos DB SDKs.

备注

目前,可以为新**** 容器(在新帐户和现有帐户中)启用分析存储。Currently you can enable analytical store for new containers (both in new and existing accounts).

Azure 门户Azure portal

  1. 登录到 Azure 门户Azure Cosmos 资源管理器Sign in to the Azure portal or the Azure Cosmos explorer.

  2. 导航到你的 Azure Cosmos 帐户,打开“数据资源管理器”**** 选项卡。Navigate to your Azure Cosmos account and open the Data Explorer tab.

  3. 选择“新容器”****,并输入数据库、容器、分区键和吞吐量详细信息的名称。Select New Container and enter a name for your database, container, partition key and throughput details. 打开“分析存储”**** 选项。Turn on the Analytical store option. 启用分析存储后,它将创建一个容器,该容器的 AnalyicalTTL 属性设置为默认值 -1(无限保留期)。After you enable the analytical store, it creates a container with AnalyicalTTL property set to the default value of -1 (infinite retention). 此分析存储保留所有记录的历史版本。This analytical store that retains all the historical versions of records.

    查找 Synapse Link 预览功能

  4. 如果你以前未在此帐户上启用 Synapse Link,系统将提示你执行此操作,因为它是创建启用了分析存储的容器的先决条件。If you have previously not enabled Synapse Link on this account, it will prompt you to do so because it's a pre-requisite to create an analytical store enabled container. 如果系统提示,请选择“启用 Synapse Link”****。If prompted, select Enable Synapse Link.

  5. 选择“确定”****,创建启用了分析存储的 Azure Cosmos 容器。Select OK, to create an analytical store enabled Azure Cosmos container.

.NET SDK.NET SDK

以下代码使用 .NET SDK 创建具有分析存储的容器。The following code creates a container with analytical store by using the .NET SDK. 将分析 TTL 属性设置为所需的值。Set the analytical TTL property to the required value. 有关允许值的列表,请参阅分析 TTL 支持的值一文:For the list of allowed values, see the analytical TTL supported values article:

// Create a container with a partition key, and analytical TTL configured to  -1 (infinite retention)
string containerId = "myContainerName";
int analyticalTtlInSec = -1;
ContainerProperties cpInput = new ContainerProperties()
            {
Id = containerId,
PartitionKeyPath = "/id",
AnalyticalStorageTimeToLiveInSeconds = analyticalTtlInSec,
};
 await this. cosmosClient.GetDatabase("myDatabase").CreateContainerAsync(cpInput);

Java V4 SDKJava V4 SDK

以下代码使用 Java V4 SDK 创建具有分析存储的容器。The following code creates a container with analytical store by using the Java V4 SDK. AnalyticalStoreTimeToLiveInSeconds 属性设置为所需的值:Set the AnalyticalStoreTimeToLiveInSeconds property to the required value:

// 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 SDKPython V4 SDK

Python 2.7 和 Azure Cosmos DB SDK 4.1.0 是所需的最低版本,此 SDK 仅与 SQL API 兼容。Python 2.7 and Azure Cosmos DB SDK 4.1.0 are the minimum versions required, and the SDK is only compatible with the SQL API.

第一步是确保至少使用 Azure Cosmos DB Python SDK 版本 4.1.0:The first step is to make sure that you are using at least version 4.1.0 of the Azure Cosmos DB Python SDK:

import azure.cosmos as cosmos

print (cosmos.__version__)

下一步是使用 Azure Cosmos DB Python SDK 创建具有分析存储的容器:The next step creates a container with analytical store by using the Azure Cosmos DB Python SDK:

# Azure Cosmos DB Python SDK, for SQL API only.
# Creating an analytical store enabled container.

import azure.cosmos.cosmos_client as cosmos_client
import azure.cosmos.exceptions as exceptions
from azure.cosmos.partition_key import PartitionKey

HOST = 'your-cosmos-db-account-URI'
KEY = 'your-cosmos-db-account-key'
DATABASE = 'your-cosmos-db-database-name'
CONTAINER = 'your-cosmos-db-container-name'

client = cosmos_client.CosmosClient(HOST,  KEY )
# setup database for this sample. 
# If doesn't exist, creates a new one with the name informed above.
try:
    db = client.create_database(DATABASE)

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

# Creating the container with analytical store enabled, using the name informed above.
# If a container with the same name exists, an error is returned.
#
# The 3 options for the analytical_storage_ttl parameter are:
# 1) 0 or Null or not informed (Not enabled).
# 2) -1 (The data will be stored in analytical store infinitely).
# 3) Any other number is the actual ttl, in seconds.

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')

更新分析存储生存时间Update the analytical store time to live

使用特定的 TTL 值启用分析存储后,可以在以后将其更新为其他有效值。After the analytical store is enabled with a particular TTL value, you can update it to a different valid value later. 可以使用 Azure 门户或 SDK 更新此值。You can update the value by using the Azure portal or SDKs. 有关各种分析 TTL 配置选项的信息,请参阅分析 TTL 支持的值一文。For information on the various Analytical TTL config options, see the analytical TTL supported values article.

Azure 门户Azure portal

如果通过 Azure 门户创建了已启用分析存储的容器,则它将包含默认为 -1 的分析 TTL。If you created an analytical store enabled container through the Azure portal, it contains a default analytical TTL of -1. 使用以下步骤来更新此值:Use the following steps to update this value:

  1. 登录到 Azure 门户Sign in to the Azure portal.

  2. 导航到你的 Azure Cosmos 帐户,打开“数据资源管理器”选项卡。****Navigate to your Azure Cosmos account and open the Data Explorer tab.

  3. 选择已启用分析存储的现有容器。Select an existing container that has analytical store enabled. 展开容器并修改以下值:Expand it and modify the following values:

    • 打开“规模和设置”窗口。****Open the Scale & Settings window.
    • 在“设置”**** 下,找到“分析存储生存时间”。Under Setting find,** Analytical Storage Time to Live**.
    • 选择“启用(无默认值)”或选择“启用”,然后设置一个 TTL 值**** ****Select On (no default) or select On and set a TTL value
    • 单击“保存”以保存更改。Click Save to save the changes.

.NET SDK.NET SDK

下面的代码演示如何使用 .NET SDK 更新分析存储的 TTL:The following code shows how to update the TTL for analytical store by using the .NET SDK:

// Get the container, update AnalyticalStorageTimeToLiveInSeconds 
ContainerResponse containerResponse = await client.GetContainer("database", "container").ReadContainerAsync();
// Update analytical store TTL
containerResponse.Resource. AnalyticalStorageTimeToLiveInSeconds = 60 * 60 * 24 * 180  // Expire analytical store data in 6 months;
await client.GetContainer("database", "container").ReplaceContainerAsync(containerResponse.Resource);

Java V4 SDKJava V4 SDK

下面的代码演示如何使用 Java V4 SDK 更新分析存储的 TTL:The following code shows how to update the TTL for analytical store by using the Java V4 SDK:

CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");

// Update analytical store TTL to expire analytical store data in 6 months;
containerProperties.setAnalyticalStoreTimeToLiveInSeconds (60 * 60 * 24 * 180 );  

// Update container settings
container.replace(containerProperties).block();

可以在 GitHub 上找到有关 Azure Synapse Link 入门的示例。You can find samples to get started with Azure Synapse Link on GitHub. 这些示例展示了物联网和零售场景的端到端解决方案。These showcase end-to-end solutions with IoT and Retail scenarios.

后续步骤Next steps

若要了解更多信息,请参阅下列文档:To learn more, see the following docs: