設定及使用適用於 Azure Cosmos DB 的 Azure Synapse Link

發行項
08/15/2024

適用於：NoSQL MongoDB Gremlin

適用於 Azure Cosmos DB 的 Azure Synapse Link 是雲端原生的混合式交易和分析處理 (HTAP) 功能，可讓您對 Azure Cosmos DB 中的作業資料執行近即時分析。 Synapse Link 會在 Azure Cosmos DB 與 Azure Synapse Analytics 之間建立緊密順暢的整合。

重要

Microsoft Fabric 中的鏡像 (預覽版) 現在可在 NoSql API 中取得。這項功能提供 Azure Synapse Link 的所有功能，具有更佳的分析效能、能夠將資料資產與 Fabric OneLake 整合，並以 Delta Parquet 格式開啟對 OneLake 資料的存取權。如果您考慮使用 Azure Synapse Link，建議您嘗試鏡像以評估您組織的整體適合度。若要開始使用鏡像，請按一下這裡。

Azure Synapse Link 可用於 Azure Cosmos DB SQL API，或可用於適用於 Mongo DB 的 Azure Cosmos DB API 帳戶。其為 Gremlin API 預覽版，並透過 CLI 命令啟用。使用下列步驟，利用 Azure Cosmos DB 的 Azure Synapse Link 來執行分析查詢：

啟用適用於 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 Cosmos DB 帳戶的 Azure Synapse Link

使用 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，在適用於 NoSQL 的 Azure Cosmos DB API 或 MongoDB 帳戶中啟用 Synapse Link。

Azure CLI

進行建立或更新作業時均可使用 --enable-analytical-storage true。同時，您必須選擇表示法結構描述類型。針對 API for NoSQL 帳戶，您可以搭配值 FullFidelity 或 WellDefined 來使用 --analytical-storage-schema-type。針對 API for MongoDB 帳戶，請一律使用 --analytical-storage-schema-type FullFidelity。

使用 Azure CLI 為適用於 Gremlin API 的 Azure Synapse Link 帳戶啟用 Synapse Link。

適用於 Gremlin API 的 Synapse Link 目前處於預覽狀態。您可以使用 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

進行建立或更新作業時均可使用 EnableAnalyticalStorage true。同時，您必須選擇表示法結構描述類型。針對 API for NoSQL 帳戶，您可以搭配值 FullFidelity 或 WellDefined 來使用 --analytical-storage-schema-type。針對 API for MongoDB 帳戶，請一律使用 -AnalyticalStorageSchemaType FullFidelity。

Azure Resource Manager 範本

此 Azure Resource Manager 範本會針對 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/秒，但可用的 RU/秒總數仍會影響程序的效能。您可以暫時增加環境的可用 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

下列選項會透過使用 Azure CLI 並設定 --analytical-storage-ttl 屬性，來在容器中啟用 Synapse Link。

使用 Azure CLI 為適用於 Gremlin API 的 Azure Synapse Link 圖表啟用 Synapse Link

適用於 Gremlin API 的 Synapse Link 目前處於預覽狀態。您可以使用 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

下列選項會透過使用 Azure CLI 並設定 -AnalyticalStorageTtl 屬性，來在容器中啟用 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 資料。

透過最佳做法改善效能

自訂資料分割

自訂資料分割可讓您依照欄位來分割分析存放區資料，這些欄位通常會在分析查詢中用來作為篩選條件，進而改善查詢效能。 若要深入了解，請參考自訂資料分割簡介與如何設定自訂資料分割文章。

針對適用於 Cosmos DB 的 Azure Synapse Link 的 Synapse SQL 無伺服器最佳做法

針對您的 SQL 無伺服器查詢使用這個 (英文) 強制最佳做法。

開始使用 Azure Synapse Link - 樣本

您可以在 GitHub 上找到開始使用 Azure Synapse Link 的樣本。這些範例會向您展示 IoT 和零售情節的端對端解決方案。您也可以在 MongoDB 資料夾下方的相同存放庫中找到與 Azure Cosmos DB for MongoDB 相對應的樣本。

下一步

若要深入了解，請參閱下列文件：

查看訓練課程模組，了解如何設定適用於 Azure Cosmos DB 的 Azure Synapse Link。
Azure Cosmos DB 分析存放區概觀。
關於適用於 Azure Cosmos DB 的 Synapse Link 常見問題。
Azure Synapse Analytics 中的 Apache Spark。
Azure Synapse Analytics 中的無伺服器 SQL 集區執行階段支援。

共用方式為

設定及使用適用於 Azure Cosmos DB 的 Azure Synapse Link

啟用適用於 Azure Cosmos DB 帳戶的 Azure Synapse Link

Azure 入口網站

命令列工具

Azure CLI

使用 Azure CLI 為適用於 Gremlin API 的 Azure Synapse Link 帳戶啟用 Synapse Link。

PowerShell

Azure Resource Manager 範本

為您的容器啟用 Azure Synapse Link

Azure 入口網站

新增容器

現有容器

命令列工具

Azure CLI

使用 Azure CLI 為適用於 Gremlin API 的 Azure Synapse Link 圖表啟用 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 中的資料

透過最佳做法改善效能

自訂資料分割

針對適用於 Cosmos DB 的 Azure Synapse Link 的 Synapse SQL 無伺服器最佳做法

開始使用 Azure Synapse Link - 樣本

下一步

意見反應

其他資源