複製活動中的結構描述和資料類型對應

發行項
12/04/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用 (部分機器翻譯)！

本文描述 Azure Data Factory 複製活動如何執行從來源資料到接收器資料的結構描述對應和資料類型對應。

結構描述對應

預設對應

根據預設，複製活動會以區分大小寫的方式，依資料行名稱將來源資料對應至接收器。例如，如果接收器不存在，寫入檔案來源欄位名稱將會保存為接收器名稱。如果接收器已經存在，它必須包含從來源複製的所有資料行。這類預設對應支援彈性結構描述，以及從來源到接收器從執行到執行的結構描述漂移 - 來源資料存放區傳回的所有資料都可以複製到接收器。

如果您的來源是沒有標題列的文字檔案，則需要明確對應，因為來源不包含資料行名稱。

明確對應

您也可以指定明確對應，以根據需求自訂從來源到接收器的資料行/欄位對應。使用明確對應時，您只能將部分來源資料複製到接收器，或將來源資料對應至具有不同名稱的接收器，或重新調整表格式/階層式資料。複製活動：

從來源讀取資料，並判斷來源結構描述。
套用您定義的對應。
將資料寫入接收器。

深入了解：

表格式來源到表格式接收器
階層式來源到表格式接收器
表格式/階層式來源到階層式接收器

您可以在 [撰寫 UI] -> [複製活動] -> [對應] 索引標籤上設定對應，或以程式設計方式在 [複製活動] -> translator 屬性中指定對應。 translator ->mappings 陣列 -> 物件 ->source 和 sink 中支援下列屬性，其指向要對應資料的特定資料行/欄位。

屬性	描述	必要
NAME	來源或接收器資料行/欄位的名稱。套用表格式來源和接收器。	Yes
序數	資料行索引。從 1 開始。使用不含標題列的分隔文字時適用且為必要項目。	No
path	每個要擷取或對應的欄位 JSON 路徑運算式。適用階層式來源和接收器 (例如，Azure Cosmos DB、MongoDB 或 REST 連接器)。對於根物件底下的欄位，JSON 路徑開頭會是 root `$`；對於 `collectionReference` 屬性所選擇陣列內的欄位，JSON 路徑開頭會是不含 `$` 的陣列元素。	No
type	來源或接收器資料行的過渡期資料類型。一般而言，您不需要指定或變更此屬性。深入了解資料類型對應。	No
culture	來源或接收器資料行的文化特性。類型為 `Datetime` 或 `Datetimeoffset` 時適用。預設值為 `en-us`。一般而言，您不需要指定或變更此屬性。深入了解資料類型對應。	No
format	當類型為 `Datetime` 或 `Datetimeoffset` 時，所要使用的格式字串。有關如何格式化日期時間的資訊，請參閱自訂日期和時間格式字串。一般而言，您不需要指定或變更此屬性。深入了解資料類型對應。	No

除了 mappings 之外，translator 下也支援下列屬性：

屬性	描述	必要
collectionReference	適用從階層式來源 (例如 Azure Cosmos DB、MongoDB 或 REST 連接器) 複製資料時。如果您想要逐一查看陣列欄位內相同模式的物件並擷取資料，然後轉換為每個物件一個資料列，則請指定該陣列的 JSON 路徑，以執行交叉套用。	No

表格式來源到表格式接收器

例如，若要將資料從 Salesforce 複製到 Azure SQL Database，並明確對應三個資料行：

在複製活動 -> 對應索引標籤上，按一下 [匯入結構描述] 按鈕，以匯入來源和接收器結構描述。
對應所需的欄位，並排除/刪除其餘欄位。

將表格式對應到表格式

可以在複製活動承載中設定相同的對應 (請參閱 translator)：

{
    "name": "CopyActivityTabularToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "SalesforceSource" },
        "sink": { "type": "SqlSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "name": "Id" },
                    "sink": { "name": "CustomerID" }
                },
                {
                    "source": { "name": "Name" },
                    "sink": { "name": "LastName" }
                },
                {
                    "source": { "name": "LastModifiedDate" },
                    "sink": { "name": "ModifiedDate" }
                }
            ]
        }
    },
    ...
}

若要從沒有標題列的分隔文字檔案複製資料，資料行會以序數而非名稱表示。

{
    "name": "CopyActivityTabularToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "DelimitedTextSource" },
        "sink": { "type": "SqlSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "ordinal": "1" },
                    "sink": { "name": "CustomerID" }
                }, 
                {
                    "source": { "ordinal": "2" },
                    "sink": { "name": "LastName" }
                }, 
                {
                    "source": { "ordinal": "3" },
                    "sink": { "name": "ModifiedDate" }
                }
            ]
        }
    },
    ...
}

階層式來源到表格式接收器

將資料從階層式來源複製到表格式接收器時，複製活動支援下列功能：

從物件和陣列擷取資料。
交叉套用陣列中具有相同模式的多個物件，在此情況下，將一個 JSON 物件轉換成表格式結果中的多個記錄。

如需更進階的階層式到表格式轉換，您可以使用資料流程。

例如，如果您有具備下列內容的來源 MongoDB 文件：

{
    "id": {
        "$oid": "592e07800000000000000000"
    },
    "number": "01",
    "date": "20170122",
    "orders": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "name": "Seattle" } ]
}

而您想要將陣列內的資料 (order_pd 和 order_price) 壓平合併，並與一般根資訊 (編號、日期和城市) 交叉聯結，以下列格式 (具有標頭列) 複製到文字檔案：

orderNumber	orderDate	order_pd	order_price	市/鎮
01	20170122	P1	23	西雅圖
01	20170122	P2	13	西雅圖
01	20170122	P3	231	西雅圖

您可以在 Data Factory 撰寫 UI 上定義這類對應：

在複製活動 -> 對應索引標籤上，按一下 [匯入結構描述] 按鈕，以匯入來源和接收器結構描述。由於服務會在匯入結構描述時對前幾個物件取樣，如果有任何欄位未顯示，您可以將它新增至階層中的正確層 - 將滑鼠停留在現有的欄位名稱上，然後選擇新增節點、物件或陣列。
選取您要逐一查看和擷取資料的陣列。它會自動填入為集合參考。請注意，這類作業僅支援單一陣列。
將所需的欄位對應至接收器。服務會自動判斷階層式端的對應 JSON 路徑。

注意

對於標示為集合參考的陣列是空白且已選取核取方塊的記錄，會略過整個記錄。

使用 UI 將階層對應到表格式

您也可以切換至 [進階編輯器]，在此情況下，您可以直接查看和編輯欄位的 JSON 路徑。如果您選擇在此檢視中新增對應，請指定 JSON 路徑。

使用進階編輯器將階層對應到表格式

可以在複製活動承載中設定相同的對應 (請參閱 translator)：

{
    "name": "CopyActivityHierarchicalToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": { "type": "MongoDbV2Source" },
        "sink": { "type": "DelimitedTextSink" },
        "translator": {
            "type": "TabularTranslator",
            "mappings": [
                {
                    "source": { "path": "$['number']" },
                    "sink": { "name": "orderNumber" }
                },
                {
                    "source": { "path": "$['date']" },
                    "sink": { "name": "orderDate" }
                },
                {
                    "source": { "path": "['prod']" },
                    "sink": { "name": "order_pd" }
                },
                {
                    "source": { "path": "['price']" },
                    "sink": { "name": "order_price" }
                },
                {
                    "source": { "path": "$['city'][0]['name']" },
                    "sink": { "name": "city" }
                }
            ],
            "collectionReference": "$['orders']"
        }
    },
    ...
}

表格式/階層式來源到階層式接收器

使用者體驗流程類似於階層式來源到表格式接收器。

從表格式來源將資料複製到階層式接收器時，不支援寫入物件內的陣列。

將資料從階層式來源複製到階層式接收器時，您可以透過選取物件/陣列並對應至接收器，以額外保留整個圖層的階層，而不需碰觸內部欄位。

如需更進階的資料重新調整轉換，您可以使用資料流程。

參數化對應

如果您想要建立範本化管線以動態複製大量物件，請判斷是否可以利用預設對應，或您需要為個別物件定義明確對應。

如果需要明確對應，您可以：

在管線層級定義具有物件類型的參數，例如 mapping。

將對應參數化：在複製活動 -> 對應索引標籤上，選擇新增動態內容並選取上述參數。活動承載會如下所示：

{
    "name": "CopyActivityHierarchicalToTabular",
    "type": "Copy",
    "typeProperties": {
        "source": {...},
        "sink": {...},
        "translator": {
            "value": "@pipeline().parameters.mapping",
            "type": "Expression"
        },
        ...
    }
}

建構要傳入對應參數的值。它應該是 translator 定義的整個物件，請參閱明確對應一節中的範例。例如，針對表格式來源到表格式接收器複製，此值應該是 {"type":"TabularTranslator","mappings":[{"source":{"name":"Id"},"sink":{"name":"CustomerID"}},{"source":{"name":"Name"},"sink":{"name":"LastName"}},{"source":{"name":"LastModifiedDate"},"sink":{"name":"ModifiedDate"}}]}。

資料類型對應

複製活動會使用下列流程，將來源類型對應至接收器類型：

從來源原生資料類型轉換成 Azure Data Factory 和 Synapse 管線所使用的過渡期資料類型。
視需要自動轉換過渡期資料類型，以符合對應的接收器類型，同時適用預設對應和明確對應。
從過渡期資料類型轉換為接收器原生資料類型。

複製活動目前支援下列過渡期資料類型：Boolean、Byte、Byte array、Datetime、DatetimeOffset、Decimal、Double、GUID、Int16、Int32、Int64、SByte、Single、String、Timespan、UInt16、UInt32 和 UInt64。

從來源到接收器的過渡期類型之間支援下列資料類型轉換。

Source\Sink	布林值	位元組陣列	日期/時間	Decimal	浮點數	GUID	整數	String	TimeSpan
布林值
位元組陣列
日期/時間
Decimal
浮點數
GUID
整數
String
TimeSpan

(1) Date/Time 包含 DateTime 和 DateTimeOffset。

(2) 浮點數包括 Single 和 Double。

(3) 整數包括 SByte、Byte、Int16、UInt16、Int32、UInt32、Int64 和 UInt64。

注意

在表格式資料之間複製時，目前支援這類資料類型轉換。不支援階層式來源/接收器，這表示來源和接收器過渡期類型之間沒有系統定義的資料類型轉換。
此功能適用於最新的資料集模型。如果您沒有從 UI 看到此選項，請嘗試建立新的資料集。

資料類型轉換的複製活動中支援下列屬性 (在程式設計撰寫的 translator 區段下)：

屬性	描述	必要
typeConversion	啟用新的資料類型轉換體驗。由於回溯相容性，預設值為 false。針對從 2020 年 6 月底後透過 Data Factory 撰寫 UI 建立的新複製活動，預設會啟用此資料類型轉換，以獲得最佳體驗，而您可以在複製活動 -> 對應索引標籤上查看適用案例的下列類型轉換設定。若要以程式設計方式建立管線，您必須將 `typeConversion` 屬性明確設定為 true，才能啟用它。針對在此功能發行之前建立的現有複製活動，為了回溯相容性，您不會在撰寫 UI 上看到類型轉換選項。	No
typeConversionSettings	類型轉換設定的群組。 `typeConversion` 設定為 `true` 時適用。下列屬性全都位於此群組下。	No
在 `typeConversionSettings` 下
allowDataTruncation	在複製期間將來源資料轉換為不同類型的接收器時，允許資料截斷，例如從小數轉換為整數，以及從 DatetimeOffset 轉換為 Datetime。預設值為 True。	No
treatBooleanAsNumber	將布林值視為數字，例如 true 為 1。預設值為 False。	No
dateTimeFormat	在不具有時區位移和字串的日期之間轉換時，將字串格式化，例如 `yyyy-MM-dd HH:mm:ss.fff`。如需詳細資訊，請參閱自訂日期和時間格式字串。	No
dateTimeOffsetFormat	在具有時區位移和字串的日期之間轉換時，將字串格式化，例如 `yyyy-MM-dd HH:mm:ss.fff zzz`。如需詳細資訊，請參閱自訂日期和時間格式字串。	No
timeSpanFormat	在時間週期和字串之間轉換時，將字串格式化，例如 `dd\.hh\:mm`。如需詳細資訊，請參閱自訂 TimeSpan 格式字串。	No
culture	轉換類型時要使用的文化特性資訊，例如 `en-us` 或 `fr-fr`。	No

範例：

{
    "name": "CopyActivity",
    "type": "Copy",
    "typeProperties": {
        "source": {
        	"type": "ParquetSource"
        },
        "sink": {
            "type": "SqlSink"
        },
        "translator": {
            "type": "TabularTranslator",
            "typeConversion": true,
            "typeConversionSettings": {
                "allowDataTruncation": true,
                "treatBooleanAsNumber": true,
                "dateTimeFormat": "yyyy-MM-dd HH:mm:ss.fff",
                "dateTimeOffsetFormat": "yyyy-MM-dd HH:mm:ss.fff zzz",
                "timeSpanFormat": "dd\.hh\:mm",
                "culture": "en-gb"
            }
        }
	},
    ...
}

舊版模型

注意

因為回溯相容性，仍支援下列將來源資料行/欄位與接收器對應的模型。建議您使用結構描述對應中提及的新模型。撰寫 UI 已切換以產生新模型。

替代資料行對應 (舊版模型)

您可以指定複製活動 ->translator ->columnMappings 以在表格式資料之間對應。在此案例中，輸入和輸出資料集需要「結構」區段。資料行對應支援將來源資料集「結構」中的所有或一部分資料行，對應至接收資料集「結構」中的所有資料行。以下是會導致發生例外狀況的錯誤狀況：

來源資料存放區查詢結果在輸入資料集的「結構」區段中並未指定資料行名稱。
接收資料存放區 (如果含有預先定義的結構描述) 在輸出資料集的「結構」區段中並未指定資料行名稱。
接收資料集「結構」中的資料行數量多於或少於對應中所指定的數量。
重複的對應。

在下列範例中，輸入資料集有一個結構，且指向內部部署 Oracle 資料庫中的資料表。

{
    "name": "OracleDataset",
    "properties": {
        "structure":
         [
            { "name": "UserId"},
            { "name": "Name"},
            { "name": "Group"}
         ],
        "type": "OracleTable",
        "linkedServiceName": {
            "referenceName": "OracleLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SourceTable"
        }
    }
}

在此範例中，輸出資料集有一個結構，且指向 Salesforce 中的表格。

{
    "name": "SalesforceDataset",
    "properties": {
        "structure":
        [
            { "name": "MyUserId"},
            { "name": "MyName" },
            { "name": "MyGroup"}
        ],
        "type": "SalesforceObject",
        "linkedServiceName": {
            "referenceName": "SalesforceLinkedService",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "SinkTable"
        }
    }
}

下列 JSON 定義了管線中的複製活動。來自來源的資料行是使用轉譯程式 ->columnMappings 屬性來對應至接收器中的資料行。

{
    "name": "CopyActivity",
    "type": "Copy",
    "inputs": [
        {
            "referenceName": "OracleDataset",
            "type": "DatasetReference"
        }
    ],
    "outputs": [
        {
            "referenceName": "SalesforceDataset",
            "type": "DatasetReference"
        }
    ],
    "typeProperties":    {
        "source": { "type": "OracleSource" },
        "sink": { "type": "SalesforceSink" },
        "translator":
        {
            "type": "TabularTranslator",
            "columnMappings":
            {
                "UserId": "MyUserId",
                "Group": "MyGroup",
                "Name": "MyName"
            }
        }
    }
}

如果您正在使用 "columnMappings": "UserId: MyUserId, Group: MyGroup, Name: MyName" 的語法指定資料行對應，則仍會依原狀支援該對應。

替代結構描述對應 (舊版模型)

您可以指定複製活動 ->translator ->schemaMapping 以在階層式資料與表格式資料之間對應，例如，從 MongoDB/REST 複製到文字檔，以及從 Oracle 複製至 Azure Cosmos DB for MongoDB。複製活動的 translator 區段支援下列屬性：

屬性	描述	必要
type	複製活動轉譯程式的類型屬性必須設定為：TabularTranslator	Yes
schemaMapping	機碼值組的集合，表示從來源端到接收器端的對應關聯性。 - Key：代表來源。針對表格式來源，請如資料集結構中所定義指定資料行名稱；針對階層式來源，請為每個欄位指定要擷取和對應的 JSON 路徑運算式。 - Value：代表接收器。針對表格式接收器，請如資料集結構中所定義指定資料行名稱；針對階層式接收器，請為每個欄位指定要擷取和對應的 JSON 路徑運算式。如果是階層式資料，對於根物件底下的欄位，JSON 路徑開頭會是 root $；對於 `collectionReference` 屬性所選擇陣列內的欄位，JSON 路徑開頭會是陣列元素。	Yes
collectionReference	如果您想要逐一查看陣列欄位內相同模式的物件並擷取資料，然後轉換為每個物件一個資料列，則請指定該陣列的 JSON 路徑，以執行交叉套用。只有在階層式資料是來源時，才支援這個屬性。	No

範例：從 MongoDB 複製到 Oracle：

例如，如果您有具備下列內容的 MongoDB 文件：

{
    "id": {
        "$oid": "592e07800000000000000000"
    },
    "number": "01",
    "date": "20170122",
    "orders": [
        {
            "prod": "p1",
            "price": 23
        },
        {
            "prod": "p2",
            "price": 13
        },
        {
            "prod": "p3",
            "price": 231
        }
    ],
    "city": [ { "name": "Seattle" } ]
}

您想要壓平合併陣列內的資料 (order_pd 和 order_price)，將內容複製到下列格式的 Azure SQL 資料表，並與一般根資訊 (編號、日期和城市) 交叉聯結︰

orderNumber	orderDate	order_pd	order_price	市/鎮
01	20170122	P1	23	西雅圖
01	20170122	P2	13	西雅圖
01	20170122	P3	231	西雅圖

如下列複製活動 JSON 範例所示，設定結構描述對應規則：

{
    "name": "CopyFromMongoDBToOracle",
    "type": "Copy",
    "typeProperties": {
        "source": {
            "type": "MongoDbV2Source"
        },
        "sink": {
            "type": "OracleSink"
        },
        "translator": {
            "type": "TabularTranslator",
            "schemaMapping": {
                "$.number": "orderNumber",
                "$.date": "orderDate",
                "prod": "order_pd",
                "price": "order_price",
                "$.city[0].name": "city"
            },
            "collectionReference":  "$.orders"
        }
    }
}

請參閱其他複製活動文章：

複製活動概觀

共用方式為

複製活動中的結構描述和資料類型對應

結構描述對應

預設對應

明確對應

表格式來源到表格式接收器

階層式來源到表格式接收器

表格式/階層式來源到階層式接收器

參數化對應

資料類型對應

舊版模型

替代資料行對應 (舊版模型)

替代結構描述對應 (舊版模型)

意見反應

其他資源

共用方式為

複製活動中的結構描述和資料類型對應

結構描述對應

預設對應

明確對應

表格式來源到表格式接收器

階層式來源到表格式接收器

表格式/階層式來源到階層式接收器

參數化對應

資料類型對應

舊版模型

替代資料行對應 (舊版模型)

替代結構描述對應 (舊版模型)

相關內容

意見反應

其他資源