複製活動中的架構和數據類型對應

  • 發行項

適用於：Azure Data Factory Azure Synapse Analytics

提示

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

本文說明 Azure Data Factory 複製活動如何執行從源數據到接收數據的架構對應和數據類型對應。

結構描述對應

默認對應

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

如果您的來源是沒有標題行的文本檔， 則需要明確對應 ，因為來源不包含數據行名稱。

明確對應

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

  1. 從來源讀取數據，並判斷來源架構。
  2. 套用您定義的對應。
  3. 將數據寫入接收。

深入了解：

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

屬性 描述 必要
NAME 來源或接收數據行/欄位的名稱。 套用表格式來源和接收。 Yes
序數 數據行索引。 從 1 開始。
使用不含行首行的分隔文字時，請套用和必要專案。		 No
path 要擷取或對應之每個欄位的 JSON 路徑表示式。 適用於階層式來源和接收，例如 Azure Cosmos DB、MongoDB 或 REST 連接器。
若為根物件下的欄位，JSON 路徑會以根 $開頭;對於屬性選擇 collectionReference 之陣列內的欄位，JSON 路徑會從不含 $的數位元素開始。		 No
type 來源或接收數據行的過渡數據類型。 一般而言，您不需要指定或變更此屬性。 深入了解 數據類型對應。 No
culture 來源或接收數據行的文化特性。 當類型為 Datetime 或 Datetimeoffset時套用 。 預設值為 en-us。
一般而言，您不需要指定或變更此屬性。 深入了解 數據類型對應。		 No
format 類型為 Datetime 或 Datetimeoffset時要使用的格式字串。 如需 如何格式化 datetime， 請參閱自定義日期和時間格式字串。 一般而言，您不需要指定或變更此屬性。 深入了解 數據類型對應。 No

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

屬性 描述 必要
collectionReference 從階層式來源複製數據時套用，例如 Azure Cosmos DB、MongoDB 或 REST 連接器。
如果您想要以相同模式從數位欄位中的物件反覆運算和擷取數據，並針對每個物件轉換成每個數據列，請指定該數位的 JSON 路徑來執行交叉套用。		 No

表格式來源至表格式接收

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

  1. 在 [複製活動 -> 對應] 索引標籤上，按兩下 [匯入架構] 按鈕以匯入來源和接收架構。

  2. 對應所需的欄位，並排除/刪除其餘欄位。

將表格式對應至表格式

複製活動承載中可以設定相同的對應如下（請參閱 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 上定義這類對應：

  1. 在 [複製活動 -> 對應] 索引標籤上，按兩下 [匯入架構] 按鈕以匯入來源和接收架構。 當服務在匯入架構時取樣前幾個物件時，如果有任何字段未顯示，您可以將它新增至階層中的正確層 - 將滑鼠停留在現有的功能變數名稱上，然後選擇新增節點、物件或陣列。

  2. 選取您要從中反覆運算和擷取數據的陣列。 它會自動填入為 集合參考。 請注意，這類作業僅支援單一陣列。

  3. 將所需的欄位對應至接收。 服務會自動判斷階層式端的對應 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']"
        }
    },
    ...
}

階層式接收的表格式/階層式來源

用戶體驗流程類似於 階層式來源與表格式接收。

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

將數據從階層式來源複製到階層式接收時，您可以選取物件/陣列並對應至接收，而不需要觸及內部欄位，以額外保留整個層次的階層。

如需更進階的數據重塑轉換，您可以使用 數據流。

參數化對應

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

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

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

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

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

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

資料類型對應

複製活動 會執行來源類型，以下列流程對應接收類型：

  1. 從來源原生數據類型轉換成 Azure Data Factory 和 Synapse 管線所使用的過渡期數據類型。
  2. 視需要自動轉換過渡期數據類型，以符合對應的接收類型，適用於 預設對應 和 明確對應。
  3. 從過渡數據類型轉換成接收原生數據類型。

複製活動 目前支援下列過渡數據類型：布爾值、Byte、Byte 陣列、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） 日期/時間包括 DateTime 和 DateTimeOffset。

（2） 浮點包括單一和雙精度浮點。

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

注意

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

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

屬性 描述 必要
typeConversion 啟用新的資料類型轉換體驗。
默認值為 false，因為回溯相容性。

對於自 2020 年 6 月下旬以來透過 Data Factory 撰寫 UI 建立的新複製活動，預設會啟用此資料類型轉換，以獲得最佳體驗，您可以在複製活動 -> 對應索引卷標上查看下列類型轉換設定。
若要以程序設計方式建立管線，您必須將 屬性明確設定 typeConversion 為 true 以啟用它。
針對在此功能發行之前建立的現有複製活動，您將不會在撰寫 UI 上看到類型轉換選項，以取得回溯相容性。		 No
typeConversion 設定 類型轉換設定的群組。 當設定為true時typeConversion套用 。 下列屬性全都在此群組下。 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 表格式資料之間對應。 在此情況下，輸入和輸出數據集都需要「結構」區段。 數據行對應支援 將源數據集 「structure」 中的所有數據行或子集對應至接收數據集 「structure」 中的所有數據行。 以下是會導致發生例外狀況的錯誤狀況：

  • 源數據存放區查詢結果沒有輸入數據集 「structure」 區段中指定的數據行名稱。
  • 接收資料存放區（如果具有預先定義的架構）沒有輸出數據集 「structure」 區段中指定的數據行名稱。
  • 接收數據集之「結構」中的數據行或數據行數目比對應中指定的還要少。
  • 重複的對應。

在下列範例中，輸入數據集具有 結構，且指向內部部署 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 複製到適用於 MongoDB 的 Azure Cosmos DB。 複製活動 translator 區段中支援下列屬性：

屬性 描述 必要
type 複製活動翻譯工具的 type 屬性必須設定為：表格式 翻譯工具 Yes
schemaMapping 索引鍵/值組的集合，代表從來源端到接收端的對應關聯性。
- 索引鍵： 代表來源。 針對表格式來源，指定數據集結構中所定義的數據行名稱;針對階層式來源，請為每個要擷取和對應的欄位指定 JSON 路徑表達式。
- 值： 表示接收。 針對表格式接收，指定數據集結構中所定義的數據行名稱;針對階層式接收，請為每個要擷取和對應的欄位指定 JSON 路徑表達式。
如果是階層式數據，針對根物件下的欄位，JSON 路徑會以根 $開頭;針對屬性 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" } ]
}

而且您想要以下列格式將其複製到 Azure SQL 數據表，方法是將數位 資料扁平化（order_pd和order_price）， 並交叉聯結與一般根資訊 （數位、日期和城市）：

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"
        }
    }
}

相關內容

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