使用 Azure Data Factory 複製和轉換 Azure Cosmos DB (SQL API) 中的資料

適用於:Azure Data Factory Azure Synapse Analytics

本文概述如何使用 Azure Data Factory 中的複製活動,從 Azure Cosmos DB (SQL API) 複製資料或將資料複製到該處,以及如何使用資料流程來轉換 Azure Cosmos DB (SQL API) 中的資料。 若要深入了解,請閱讀 Azure Data FactorySynapse Analytics 的介紹文章。

注意

此連接器僅支援 Cosmos DB SQL API。 針對 MongoDB API,請參閱適用於 MongoDB 的 Azure Cosmos DB API 連接器。 目前不支援其他 API 類型。

支援的功能

此 Azure Cosmos DB (SQL API) 連接器支援下列活動:

針對複製活動,此 Azure Cosmos DB (SQL API) 連接器支援:

  • 使用 Azure 資源驗證的金鑰、服務主體或受控識別,在 Azure Cosmos DB SQL API 中來回複製資料。
  • 寫入 Azure Cosmos DB 作為 insertupsert
  • 依原樣匯入和匯出 JSON 文件,或從表格式資料集複製資料或將資料複製到其中。 範例包括 SQL 資料庫和 CSV 檔案。 若要依原樣將文件複製到 JSON 檔案或另一個 Azure Cosmos DB 集合或複製其中的文件,請參閱匯入和匯出 JSON 文件

Data Factory 和 Synapse 管線可與 Azure Cosmos DB 大量執行工具程式庫整合,可在寫入至 Azure Cosmos DB 時提供最理想的效能。

提示

資料移轉影片會引導您完成將資料從 Azure Blob 儲存體複製到 Azure Cosmos DB 的步驟。 此影片也會說明在一般情況下將資料擷取到 Azure Cosmos DB 的效能調整考量。

開始使用

若要透過管線執行複製活動,您可以使用下列其中一個工具或 SDK:

使用 UI 建立連結至 Azure Cosmos DB 的服務

使用下列步驟,在 Azure 入口網站 UI 中建立連結至 Azure Cosmos DB 的服務。

  1. 瀏覽至 Azure Data Factory 或 Synapse 工作區中的 [管理] 索引標籤,並選取 [連結服務],然後按一下 [新增]:

  2. 搜尋 Azure Cosmos DB (SQL API),然後選取 Azure Cosmos DB (SQL API) 連接器。

    Select Azure Cosmos DB (SQL API) connector.

  3. 設定服務詳細資料、測試連線,然後建立新的連結服務。

    Screenshot of linked service configuration for Azure Cosmos DB.

連接器設定詳細資料

下列各節提供屬性的相關詳細資料,您可使用這些屬性來定義 Azure Cosmos DB (SQL API) 專屬的實體。

連結服務屬性

Azure Cosmos DB (SQL API) 連接器支援下列驗證類型。 如需詳細資訊,請參閱對應章節:

金鑰驗證

屬性 描述 必要
type type 屬性必須設定為 CosmosDb.。
connectionString 指定連線到 Azure Cosmos DB 資料庫所需的資訊。
注意:您必須在連接字串中指定資料庫資訊,如後續範例所示。
您也可以將帳戶金鑰放在 Azure Key Vault 並從連接字串中提取 accountKey 組態。 請參閱下列範例和在 Azure Key Vault 中儲存認證一文中的更多詳細資料。
connectVia 用來連線到資料存放區的整合執行階段。 您可以使用 Azure Integration Runtime 或自我裝載整合執行階段 (如果您的資料存放區位於私人網路中)。 如果未指定此屬性,則會使用預設的 Azure Integration Runtime。

範例

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

範例:在 Azure Key Vault 中儲存帳戶金鑰

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;Database=<Database>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

服務主體驗證

注意

目前在資料流程中不支援服務主體驗證。

若要使用服務主體驗證,請遵循下列步驟。

  1. 遵循使用 Azure AD 租用戶註冊應用程式中的步驟,在 Azure Active Directory (Azure AD) 中註冊應用程式實體。 請記下以下的值,您可以使用這些值來定義連結服務:

    • 應用程式識別碼
    • 應用程式金鑰
    • 租用戶識別碼
  2. 將適當的權限授與服務主體。 請參閱檔案和目錄的存取控制清單,了解 Cosmos DB 中權限運作方式的範例。 更具體來說,請建立角色定義,並透過服務主體物件識別碼將角色指派給服務主體。

以下是連結服務支援的屬性:

屬性 描述 必要
type 類型屬性必須設為:CosmosDb Yes
accountEndpoint 指定 Azure Cosmos DB 的帳戶端點 URL。
[資料庫] 指定資料庫的名稱。
servicePrincipalId 指定應用程式的用戶端識別碼。
servicePrincipalCredentialType 用於服務主體驗證的認證類型。 允許的值為 ServicePrincipalKeyServicePrincipalCert Yes
servicePrincipalCredential 服務主體認證。
當您使用 ServicePrincipalKey 作為認證類型時,請指定應用程式的金鑰。 將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
當您使用 ServicePrincipalCert 作為認證時,請在 Azure Key Vault 中參考憑證。
tenant 指定您的應用程式所在租用戶的資訊 (網域名稱或租用戶識別碼)。 將滑鼠游標暫留在 Azure 入口網站右上角,即可加以擷取。
azureCloudType 針對服務主體驗證,請指定要註冊 Azure Active Directory 應用程式的 Azure 雲端環境類型。
允許的值為 AzurePublicAzureChinaAzureUsGovernmentAzureGermany。 預設會使用服務的雲端環境。
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。

範例:使用服務主體金鑰驗證

您也可以將服務主體金鑰儲存在 Azure Key Vault 中。

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

範例:使用服務主體憑證驗證

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

系統指派的受控識別驗證

注意

目前在資料流程中不支援系統指派的受控識別驗證。

Data Factory 或 Synapse 管線可與代表此特定服務執行個體的 Azure 資源的系統指派受控識別建立關聯。 您可以直接將此受控識別用於 Cosmos DB 驗證,類似於使用您自己的服務主體。 這可以讓這個指定的資源存取 Cosmos DB,或從 Cosmos DB 來回複製資料。

若要使用 Azure 資源的系統指派受控識別驗證,請遵循下列步驟。

  1. 複製與服務一起產生的受控識別物件識別碼,藉此擷取系統指派受控識別資訊

  2. 將適當的權限授與系統指派的受控識別。 請參閱檔案和目錄的存取控制清單,了解 Cosmos DB 中權限運作方式的範例。 更具體來說,請建立角色定義,並將角色指派給系統指派的受控識別。

以下是連結服務支援的屬性:

屬性 描述 必要
type 類型屬性必須設為:CosmosDb Yes
accountEndpoint 指定 Azure Cosmos DB 的帳戶端點 URL。
[資料庫] 指定資料庫的名稱。
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。

範例︰

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

使用者指派的受控識別驗證

注意

目前在資料流程中不支援使用者指派的受控識別驗證。

資料處理站或 Synapse 管線可與代表此特定服務執行個體的使用者指派受控識別建立關聯。 您可以直接將此受控識別用於 Cosmos DB 驗證,類似於使用您自己的服務主體。 這可以讓這個指定的資源存取 Cosmos DB,或從 Cosmos DB 來回複製資料。

若要使用 Azure 資源的使用者指派受控識別驗證,請遵循下列步驟。

  1. 建立一或多個使用者指派的受控識別,並將適當的權限授與使用者指派的受控識別。 請參閱檔案和目錄的存取控制清單,了解 Cosmos DB 中權限運作方式的範例。 更具體來說,請建立角色定義,並將角色指派給使用者指派的受控識別。

  2. 將一或多個使用者指派的受控識別指派給 Data Factory,並為每個使用者指派的受控識別建立認證

以下是連結服務支援的屬性:

屬性 描述 必要
type 類型屬性必須設為:CosmosDb Yes
accountEndpoint 指定 Azure Cosmos DB 的帳戶端點 URL。
[資料庫] 指定資料庫的名稱。
認證 將使用者指派的受控識別指定為認證物件。
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。

範例︰

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

資料集屬性

如需定義資料集的區段和屬性完整清單,請參閱資料集和連結服務

以下是針對 Azure Cosmos DB (SQL API) 資料集支援的屬性:

屬性 描述 必要
type 資料集的類型屬性必須設為 CosmosDbSqlApiCollection Yes
collectionName Azure Cosmos DB 文件集合的名稱。 Yes

如果您使用 "DocumentDbCollection" 類型的資料集,系統仍會依原樣支援複製和查閱活動,以提供回溯相容性,但資料流程則不支援。 建議您未來使用新的模型。

範例

{
    "name": "CosmosDbSQLAPIDataset",
    "properties": {
        "type": "CosmosDbSqlApiCollection",
        "linkedServiceName":{
            "referenceName": "<Azure Cosmos DB linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [],
        "typeProperties": {
            "collectionName": "<collection name>"
        }
    }
}

複製活動屬性

本節提供 Azure Cosmos DB (SQL API) 來源和接收端所支援的屬性清單。 如需可用來定義活動的區段和屬性完整清單,請參閱管線

將 Azure Cosmos DB (SQL API) 當作來源

若要從 Azure Cosmos DB (SQL API) 複製資料,請將複製活動中的來源類型設定為 DocumentDbCollectionSource

複製活動的 [來源] 區段支援下列屬性:

屬性 描述 必要
type 複製活動來源的類型屬性必須設為 CosmosDbSqlApiSource
查詢 指定 Azure Cosmos DB 查詢來讀取資料。

範例:
SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"


如果未指定,則會執行此 SQL 陳述式:select <columns defined in structure> from mycollection
preferredRegions 從 Cosmos DB 擷取資料時所要連線的慣用區域清單。 No
pageSize 查詢結果的每頁文件數目。 預設值為 "-1",表示可使用的服務端動態頁面大小上限為 1000。 No
detectDatetime 是否要從文件中的字串值偵測日期時間。 允許的值為:true (預設值)、false

如果您使用 "DocumentDbCollectionSource" 類型來源,仍會依原樣支援以提供回溯相容性。 建議您未來使用新的模型,可提供更豐富的功能從 Cosmos DB 複製資料。

範例

"activities":[
    {
        "name": "CopyFromCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cosmos DB SQL API input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbSqlApiSource",
                "query": "SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"",
                "preferredRegions": [
                    "East US"
                ]
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

從 Cosmos DB 複製資料時,除非您想要依原樣匯出 JSON 文件,否則最佳做法是在複製活動中指定對應。 服務會接受您在活動上指定的對應 - 如果資料列的資料行沒有值,系統就會為資料行值提供 null 值。 如果您未指定對應,則服務會使用資料中的第一個資料列來推斷結構描述。 如果第一個資料列不包含完整的結構描述,某些資料行會因活動作業而遺失。

將 Azure Cosmos DB (SQL API) 當作接收端

若要將資料複製到 Azure Cosmos DB (SQL API),請將複製活動中的接收類型設定為 DocumentDbCollectionSink

複製活動的 [接收] 區段支援下列屬性:

屬性 描述 必要
type 複製活動接收的類型屬性必須設為 CosmosDbSqlApiSink
writeBehavior 描述如何將資料寫入至 Azure Cosmos DB。 允許的值:insertupsert

如果存在具有相同識別碼的文件,upsert 的行為會用來取代文件;否則會插入文字。

附註:如果未在原始文件中或藉由資料行對應來指定識別碼,則服務會自動為文件產生識別碼。 這表示您必須確定,為了讓 upsert 如預期般運作,您的文件具有識別碼。

(預設值為 insert)
writeBatchSize 服務會使用 Azure Cosmos DB 大量執行工具程式庫將資料寫入至 Azure Cosmos DB。 writeBatchSize 屬性可控制服務提供給程式庫的文件大小。 您可以嘗試增加 writeBatchSize 值來改善效能,而如果您的文件大小很大,請嘗試增加此值 - 請參閱以下祕訣。 No
(預設值為 10,000)
disableMetricsCollection 此服務會收集 Cosmos DB RU 等計量,以取得複製效能最佳化和建議。 如果您擔心此行為,請指定 true 將其關閉。 否 (預設值為 false)
 maxConcurrentConnections 活動執行期間,建立與資料存放區的並行連線上限。 僅在想要限制並行連線時,才需要指定值。  No

提示

若要以原樣匯入 JSON 文件,請參閱匯入或匯出 JSON 文件一節;若要從表格式資料複製,請參閱從關聯式資料庫移轉至 Cosmos DB

提示

Cosmos DB 會將單一要求的大小限制為 2MB。 公式為要求大小 = 單一文件大小 * 寫入批次大小。 如果您遇到指出「要求大小太大。」的錯誤,請在複製接收組態中縮小 writeBatchSize

如果您使用 "DocumentDbCollectionSink" 類型的來源,仍會依原樣支援,以提供回溯相容性。 建議您未來使用新的模型,可提供更豐富的功能從 Cosmos DB 複製資料。

範例

"activities":[
    {
        "name": "CopyToCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Document DB output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "CosmosDbSqlApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

結構描述對應

若要將資料從 Azure Cosmos DB 複製到表格式接收,或執行反向操作,請參閱結構描述對應

對應資料流程屬性

在對應資料流中轉換資料時,您可以在 Cosmos DB 中讀取和寫入集合。 如需詳細資訊,請參閱對應資料流程中的來源轉換接收轉換

注意

對應資料流不支援 Azure Cosmos DB 無伺服器。

來源轉換

您可以在來源轉換的 [來源選項] 索引標籤中找到 Azure Cosmos DB 的專屬設定。

包含系統資料行:如果為 true,則 id_ts 及其他系統資料行將會包含在 CosmosDB 的資料流程中繼資料中。 更新集合時,請務必包含此項,以便擷取現有的資料列識別碼。

頁面大小:查詢結果的每頁文件數目。 預設值為 "-1",表示最多可使用 1000 個服務動態頁面。

輸送量:為您想套用至 CosmosDB 集合的 RU 數目設定一個選用值,以供讀取作業期間此資料流程每次執行之用。 最小值為 400。

慣用的區域:為此流程選擇慣用的讀取區域。

變更摘要:如果為 true,您將從 Azure Cosmos DB 變更摘要取得資料,這是容器變更的持續性記錄,會以上次自動執行的發生順序排列。 當您將它設為 true 時,請勿同時將 [推斷漂移資料行類型] 和 [允許結構描述漂移] 設為 true。 如需詳細資訊,請參閱 Azure Cosmos DB 變更摘要

從頭開始:如果為 true,您將在首次執行中取得完整快照集資料的初始載入,接著在下一次執行中擷取變更的資料。 如果為 false,則會在第一次執行時略過初始載入,接著在下一次執行時擷取變更的資料。 設定會與 Cosmos DB 參考中的相同設定名稱一致。 如需詳細資訊,請參閱 Azure Cosmos DB 變更摘要

接收轉換

您可以在接收轉換的 [設定] 索引標籤中找到 Azure Cosmos DB 的專屬設定。

Update 方法: 決定您的資料庫目的地所允許的作業。 預設僅允許插入。 若要更新、upsert 或刪除資料列,必須使用 alter-row 轉換來標記這些動作的資料列。 對於更新、更新插入和刪除,必須設定索引鍵資料行,以決定要改變哪一個資料列。

集合動作:判斷是否要在寫入之前重新建立目的地集合。

  • 無:集合不會執行任何動作。
  • 重新建立:集合會遭到捨棄並重新建立

批次大小:一個整數,表示每個批次中有多少物件寫入 Cosmos DB 集合。 通常,從預設批次大小開始就已足夠。 若要進一步微調此值,請注意:

  • Cosmos DB 會將單一要求的大小限制為 2MB。 公式為「要求大小 = 單一文件大小 * 批次大小」。 如果您遇到指出「要求大小太大」的錯誤,請減少批次大小值。
  • 批次大小越大,服務可以達成的輸送量就越高,同時請確定您配置足夠的 RU 來支援工作負載。

分割區索引鍵:輸入代表集合的分割區索引鍵的字串。 範例: /movies/title

輸送量:為您想套用至 CosmosDB 集合的 RU 數目設定一個選用值,以供此資料流程每次執行之用。 最小值為 400。

寫入輸送量預算:一個整數,表示您想要為此資料流程寫入作業配置的 RU,佔配置給集合的總輸送量的一部分。

查閱活動屬性

若要了解關於屬性的詳細資料,請參閱查閱活動

匯入和匯出 JSON 文件

您可以使用 Azure Cosmos DB (SQL API) 連接器輕鬆地:

  • 在兩個 Azure Cosmos DB 集合之間依原樣複製文件。
  • 將 JSON 文件從各種來源,包括從 Azure Blob 儲存體、Azure Data Lake Store 及服務支援的其他檔案型存放區匯入到 Azure Cosmos DB。
  • 將 JSON 文件從 Azure Cosmos DB 集合匯出至各種檔案型存放區。

若要達成無從驗證結構描述的複製:

  • 當您使用複製資料工具時,請選取 [依原樣匯出到 JSON 檔案或 Cosmos DB 集合] 選項。
  • 當您使用活動製作時,請選擇 JSON 格式搭配作為來源或接收的對應檔案存放區。

從關聯式資料庫移轉至 Cosmos DB

從關聯式資料庫 (例如 SQL Server) 移轉至 Azure Cosmos DB 時,複製活動可以輕鬆地將表格式資料從來源對應至 Cosmos DB 中壓平合併的 JSON 文件。 在某些情況下,建議您重新設計資料模型,並根據 Azure Cosmos DB 中的資料模型化 為 NoSQL 使用案例進行最佳化;例如,若要將資料反正規化,可以在一個 JSON 文件中內嵌所有相關的子項目。 針對這類情況,請參閱此文章,其中會逐步解說如何使用複製活動來達成此目的。

Azure Cosmos DB 變更摘要

Azure Data Factory 可以從 Azure Cosmos DB 變更摘要取得資料,做法是在對應資料流來源轉換中將其啟用。 使用此連接器選項,您可以讀取變更摘要,並在將轉換資料載入您選擇的目的地資料集之前套用轉換。 您不需要使用 Azure 函式來讀取變更摘要,然後再寫入自訂轉換。 您可以使用此選項將資料從一個容器移至另一個容器、為合適的目的準備變更摘要驅動的材質檢視,或根據變更摘要將容器備份或復原自動化,並使用 Azure Data Factory 的視覺化拖放功能來啟用更多這類的使用案例。

請確定管線和活動名稱保持不變,如此 ADF 便可以為您記錄檢查點,以便自動取得上次執行的變更資料。 如果您變更管線名稱或活動名稱,檢查點便會重設,這會導致您在下次執行時得從頭開始,或是取得從現在開始的變更。

偵錯管線時,此功能的運作方式相同。 請注意,當您在偵錯執行期間重新整理瀏覽器時,將會重設檢查點。 在您對偵錯執行的管線結果感到滿意之後,您可以繼續發佈並觸發管線。 當您第一次觸發已發佈的管線時,會自動從頭重新開始,或是取得從現在開始的變更。

在監視區段中,您隨時有機會重新執行管線。 重新執行時,一律會從所選管線執行的前一個檢查點擷取變更的資料。

下一步

如需複製活動支援做為來源和接收器的資料存放區清單,請參閱支援的資料存放區