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

適用於： Azure Data Factory Azure Synapse Analytics

提示

Data Factory in Microsoft Fabric 是下一代的 Azure Data Factory，擁有更簡單的架構、內建 AI 及新功能。如果你是資料整合新手，建議先從 Fabric Data Factory 開始。現有的 ADF 工作負載可升級至 Fabric，以存取資料科學、即時分析與報告等新能力。

本文說明 Azure Data Factory 複製作業如何從來源資料到目標資料執行結構映射及資料型別映射。

模式映射

預設對映設定

預設情況下，複製活動會 依欄位名稱 區分大小寫將來源資料映射到匯入。如果匯入不存在，例如寫入檔案時，來源欄位名稱會成為匯入名稱。如果接收器已存在，則必須包含從來源複製的所有資料行。此預設映射支援彈性結構及從來源到匯流的結構漂移——所有來源資料儲存回傳的資料都能複製到匯入匯。

如果你的來源是沒有標頭行的文字檔，你需要使用明確的映射，因為來源不包含欄位名稱。

明確對應

指定明確的映射以自訂欄位，以及從來源到匯的欄位映射。透過明確映射，你可以只複製部分來源資料到匯，將來源資料映射到匯，並以不同名稱進行資料的映射，或重新塑形表或階層式資料。文案活動：

從來源讀取資料並決定來源結構。
套用您定義的對應。
把資料寫入匯入匯流器。

深入了解：

資料表來源到資料表接收器
階層式來源到資料表接收器
從表格式/階層式來源到階層式匯入

在 Authoring UI 中設定映射，方法是進入複製活動並選擇映射標籤。或者，透過使用 translator 該屬性，程式化地在複製活動中指定映射。以下屬性支援於 translator -mappings> 陣列 -> 物件 ->source 和 sink，這些屬性指向特定的欄位或欄位以映射資料。

屬性	描述	必要
名稱	來源或匯的欄位或欄位名稱。適用於表格式的源與匯。	Yes
序數	欄索引。從1開始。
適用於使用無標頭行的分隔文字。	否
路徑	用於擷取或對應每個欄位的 JSON 路徑運算式。適用於階層式原始碼與匯，例如 Azure Cosmos DB、Azure DocumentDB（具備 MongoDB 相容性）、MongoDB 或 REST 連接器。
對於根物件底下的欄位，JSON 路徑開頭會是 root `$`；對於 `collectionReference` 屬性所選擇陣列內的欄位，JSON 路徑開頭會是不含 `$` 的陣列元素。	否
型別	來源或接收器資料行的中繼資料型別。一般而言，您不需要指定或變更此屬性。欲了解更多，請參閱資料型態映射。	否
文化特性 (Culture)	來源或接收器資料行的文化特性。當類型為 `Datetime` 或 `Datetimeoffset`時適用。預設值為 `en-us`。
一般而言，您不需要指定或變更此屬性。欲了解更多，請參閱資料型態映射。	否
格式	格式化字串，當型別為 `Datetime` 或 `Datetimeoffset`時使用。有關如何格式化日期時間的資訊，請參閱自訂日期和時間格式字串。一般而言，您不需要指定或變更此屬性。欲了解更多，請參閱資料型態映射。	否

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

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

資料表來源到資料表接收器

例如，從 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 物件轉換成表格式結果中的多個記錄。

若要進行更進階的階層式轉表格轉換，請使用 Data Flow。

例如，如果你有原始碼 Azure DocumentDB 或 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 ）內的資料攤平，並使用交叉連接，並使用包含共同根資訊 （數字、日期和城市）的交叉連接：

訂單號碼	訂單日期	order_pd	訂單價格	城市
01	20170122	P1	23	西雅圖
01	20170122	P2	13	西雅圖
01	20170122	P3	231	西雅圖

請在資料工廠製作介面中定義此映射：

在複製活動中，前往映射標籤，選擇 匯入結構 以匯入來源和匯入結構。當服務在匯入結構時會取樣頂端幾個物件，如果沒有任何欄位出現，就把它加入階層結構的正確層級——將滑鼠移到現有欄位名稱上，選擇新增節點、物件或陣列。
選取您要反覆處理並擷取資料的陣列。介面會自動填入 集合引用。請注意，此操作僅支援單一陣列。
將所需的欄位對應至接收器。服務會自動判斷階層式端的對應 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']"
        }
    },
    ...
}

資料表或階層式來源到階層式接收器

使用者體驗流程與階層式來源到資料表接收器相似。

當將資料從表格來源複製到階層式匯入時，服務不支援寫入物件內部的陣列。

當將資料從階層式來源複製到階層式匯入時，你可以選擇物件或陣列並映射到匯入，而不觸及內部欄位，來保留整個層的階層結構。

若要進行更進階的資料重塑轉換，請使用 Data Flow。

將對應參數化

要建立一個動態複製大量物件的模板化管線，首先要判斷是否可以使用預設的映射，或是需要為每個物件定義明確的映射。

如果你需要明確的映射，請依照以下步驟進行：

在管線層級定義一個帶有物件類型的參數，例如 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。

支援從來源到匯入端之中介類型之間的下列資料類型轉換。

來源\接收器	布林值	位元組陣列	日期/時間	Decimal	GUID	整數	字串	TimeSpan
布林值	✓			✓		✓	✓
位元組陣列		✓					✓
日期/時間			✓				✓
Decimal	✓			✓		✓	✓
浮點數	✓			✓		✓	✓
GUID					✓		✓
整數	✓			✓		✓	✓
字串	✓	✓	✓	✓	✓	✓	✓	✓
TimeSpan							✓	✓

（1） Date/Time 包含 DateTime、DateTimeOffset、Date 和 Time。

(2) 浮點數包含 Single 與 Double。

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

注意

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

複製活動支援以下資料型別轉換的屬性（在程式化撰寫區塊下translator）：

|性質 |說明 |必備 | |-------------------------------- |------------------------------------------------------------ |-------- | |typeConversion |啟用新的資料型別轉換體驗。由於向後相容性，預設值為 false。

範例：

{
    "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"
            }
        }
	},
    ...
}

舊版模型

注意

為了向下相容，服務仍支援以下模型，將來源欄位或欄位映射至匯入。使用結構映射中描述的新模型。現在由創作介面產生新模型。

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

若要映射表格形狀的資料，請指定 copy activity -> translator -> columnMappings。在此情況下，輸入與輸出資料集 都需要結構區 段。欄位映射支援 將來源資料集結構中全部或部分欄位映射到匯資料集結構中的所有欄位。以下錯誤條件會導致異常：

來源資料儲存的查詢結果沒有你在輸入資料集結構區塊指定欄位名稱。
Sink 資料儲存（如果是預設結構）沒有你在輸出資料集結構區塊指定的欄位名稱。
要麼是匯資料集結構中欄位數較少，要麼比映射中指定的欄位更多。
重複對應。

在下列範例中，輸入資料集有一個結構，且指向內部部署 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" 來指定欄位映射，仍然支援 as-is。

替代結構映射（舊有模型）

你可以指定複製活動 ->translator ->schemaMapping 來映射階層式資料與表格式資料。例如，你可以從 MongoDB 或 REST 複製到文字檔，也可以從 Oracle 複製到 Azure Cosmos DB for MongoDB 或 Azure DocumentDB（支援 MongoDB）。複製活動 translator 區塊支援以下屬性：

屬性	描述	必要
型別	將複製活動轉換器的型別屬性設為： TabularTranslator	Yes
schemaMapping	一組代表來源端到匯端映射關係的鍵值對。

關鍵： 代表來源。對於 表格來源，請指定資料集結構中定義的欄位名稱。對於階層 式原始碼，請為每個要擷取並映射的欄位指定 JSON 路徑表達式。
價值： 代表匯。對於 表格匯，請依資料集結構中定義欄位名稱。對於階層 式匯入，請為每個要提取並映射的欄位指定 JSON 路徑表達式。如果是階層式資料，對於根物件底下的欄位，JSON 路徑開頭會是 root $；對於 collectionReference 屬性所選擇陣列內的欄位，JSON 路徑開頭會是陣列元素。 |是的 | |典藏參考資料 |如果你想從陣 列欄位內 的物件中迭代並提取相同模式的資料，並轉換成每個物件的每列，請指定該陣列的 JSON 路徑來進行交叉應用。只有在階層式資料是來源時，才支援這個屬性。 |不 |

範例：從 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" } ]
}

你要將它複製到Azure SQL表，格式如下，方法是將陣列內的資料（order_pd和order_price）攤平，並交叉連接常見的根資訊（編號、日期和城市）：

訂單號碼	訂單日期	order_pd	訂單價格	城市
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"
        }
    }
}

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

複製活動概述

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-08-14