コピー アクティビティでのスキーマとデータ型のマッピング

適用対象: Azure Data Factory Azure Synapse Analytics

この記事では、Azure Data Factory コピー アクティビティが、ソース データからシンク データへのスキーマ マッピングとデータ型マッピングを実行する方法について説明します。

スキーマ マッピング

既定のマッピング

デフォルトでは、コピーアクティビティはカ ラム名で ソースデータをシンクにマッピングし、大文字と大文字を区別します。 ファイルに書き込みを行うなど、シンクが存在しない場合は、ソースフィールド名がシンク名になります。 シンクが既に存在する場合は、ソースからコピーされるすべての列が含まれている必要があります。 このデフォルトのマッピングは柔軟なスキーマと、ソースからシンクへのスキーマドリフトをサポートします。ソースデータストアから戻るすべてのデータはシンクにコピー可能です。

ソースがヘッダー行のないテキストファイルであれば、カラム名が含まれていないため明 示的なマッピング を使う必要があります。

明示的なマッピング

明示的なマッピングを指定して、ソースからシンクまでのカラムとフィールドマッピングをカスタマイズできます。 明示的なマッピングを使うことで、ソースデータの一部だけをシンクにコピーしたり、ソースデータを異なる名前でシンクにマッピングしたり、表状や階層型データの形を変えたりできます。 コピー活動:

1. ソースからデータを読み込み、ソーススキーマを決定します。
2. 定義されたマッピングが適用されます。
3. データをシンクに書き込む。

各項目の詳細情報

• 表形式のソースから表形式のシンクへ
• 階層構造のソースから表形式のシンクへ
• 表形式または階層構造のソースから階層構造のシンクへ

Authoring UIでコピーアクティビティに行き、 マッピング タブを選択してマッピングを設定してください。または、 translator プロパティを使ってコピー活動でマッピングをプログラム的に指定することもできます。 以下のプロパティは、->mappings配列、->、オブジェクト、->source、sinktranslatorでサポートされており、特定のカラムやフィールドを指し示してデータをマッピングします。

translator に加えて、mappings の下では、次のプロパティがサポートされています。

表形式のソースから表形式のシンクへ

たとえば、Salesforce からAzure SQL Databaseにデータをコピーし、3 つの列を明示的にマップするには、

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

階層型ソースからテーブル形式シンクへ

階層的なソースから表状のシンクへデータをコピーすると、コピー活動は以下の機能をサポートします:

• オブジェクトと配列からデータを抽出します。
• 1 つの配列から同じパターンを持つ複数のオブジェクトをクロス適用します。この場合、1 つの 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)、 共通のルート情報 (番号、日付、都市)とのクロスジョインを使用します。

Data FactoryオーサリングUIでこのマッピングを定義します:

1. コピーアクティビティで Mapping タブに行き、「 スキーマをインポート 」を選択してソーススキーマとシンクスキーマの両方をインポートします。 スキーマをインポートする際にサービスが上位のオブジェクトをサンプリングするので、もしフィールドが現れなければ階層の正しいレイヤーに追加してください。既存のフィールド名にカーソルを合わせ、ノード、オブジェクト、配列のいずれかを追加してください。

2. データの反復処理と抽出を行う配列を選択します。 UIはコレクション 参照を自動で埋め込みます。 この操作は単一の配列のみをサポートしていることに注意してください。

3. 必要なフィールドをシンクにマップします。 サービスによって、階層側の対応する JSON パスが自動的に決定されます。

また、上級エディターに切り替えることもできます。 フィールドの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をご利用ください。

マッピングのパラメーター化

多数のオブジェクトを動的にコピーするテンプレート化パイプラインを作成するには、 まずデフォルトのマッピング を使えるか、それとも各オブジェクトごとに 明示的なマッピング を定義する必要があるかを判断してください。

明示的なマッピングが必要な場合は、以下の手順に従ってください:

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"}}]} である必要があります。

データ型マッピング

Copy アクティビティは、以下のフローを用いてソースタイプをシンクタイプにマッピングします:

1. ソース ネイティブ データ型から、Azure Data Factory および Synapse パイプラインで使用される中間データ型に変換します。
2. 必要に応じて中間データ型を対応するシンクタイプに合わせて自動変換します。 このステップは デフォルトマッピング と 明示マッピングの両方に適用されます。
3. 中間データ型からシンクのネイティブなデータ型に変換します。

Copy アクティビティは現在、次の中間データ型をサポートしています: Boolean、Byte、Byte array、Datetime、DatetimeOffset、Decimal、Double、GUID、Int16、Int32、Int64、SByte、Single、String、Timespan、UInt16、UInt32、UInt64。

次のデータ型変換は、ソースからシンクへの中間型の間でサポートされています。

(1) 日付/時間にはDateTime、DateTimeOffset、Date、Timeが含まれます。

(2) 浮動小数点には、Single と Double が含まれます。

(3) 整数には、SByte、Byte、Int16、UInt16、Int32、UInt32、Int64、UInt64 が含まれます。

Copy アクティビティは、プログラム作成のtranslatorセクションの下にあるデータ型変換のための以下のプロパティをサポートしています:

|性質 |説明 |必須 | |-------------------------------- |------------------------------------------------------------ |-------- | |typeConversion |新しいデータ型変換体験を有効にしてください。 下位互換性のため、既定値は false です。

2020年6月下旬以降、Data FactoryオーサリングUIを通じて作成された新規コピー活動では、このデータ型変換がデフォルトで有効化されており、最良の体験が期待できます。 該当するシナリオのコピー活動-> マッピングタブで以下のタイプの変換設定を確認できます。 プログラムを使ってパイプラインを作成するには、typeConversion プロパティを明示的に true に設定して有効にする必要があります。 この機能がリリースされる前に作成された既存のコピー アクティビティについては、下位互換性のため、型変換オプションが作成 UI に表示されません。 |いいえ | |typeConversionSettings |型変換設定のグループです。 typeConversion が true に設定されている場合に適用します。 次のプロパティはすべてこのグループの下にあります。 |いいえ | |typeConversionSettings下| | | |allowDataTruncation |コピー時にソースデータをシンクに変換する際、例えばDatetimeOffsetからDatetimeへと異なるタイプで変換する際、データ切り詰めを許可します。
既定値は true です。 |いいえ | |treatBooleanAsNumber |例えば、ブール値を数値として扱い、真は1として使います。
既定値は false です。 |いいえ | |日付フォーマット |日付と文字列間の変換時には文字列をフォーマットしてください。例えば yyyy-MM-dd。 詳細については、カスタム日時書式指定文字列に関する記事を参照してください。 |いいえ | |dateTimeFormat |タイムゾーンオフセットなしの日付や文字列(例えば yyyy-MM-dd HH:mm:ss.fff)を変換する際は、文字列をフォーマットしてください。 詳細については、カスタム日時書式指定文字列に関する記事を参照してください。 |いいえ | |dateTimeOffsetFormat |日付間の変換時には、タイムゾーンオフセットや文字列(例えば yyyy-MM-dd HH:mm:ss.fff zzz)を組み合わせてフォーマットしてください。 詳細については、カスタム日時書式指定文字列に関する記事を参照してください。 |いいえ | |timeSpanFormat |時間帯や文字列間の変換時には、 dd\.hh\:mmなどの文字列をフォーマットしてください。 詳細については、カスタム TimeSpan 書式指定文字列に関する記事を参照してください。 |いいえ | |timeFormat |時間と文字列の変換時には、 HH:mm:ss.fffのように文字列をフォーマットしてください。 詳細については、カスタム日時書式指定文字列に関する記事を参照してください。 |いいえ | |文化 |タイプ変換時に使用する文化情報、例えば en-us や fr-fr。 |いいえ |

例:

{
    "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(MongoDB用)やAzure DocumentDB(MongoDB互換付き)にコピーしたりできます。 コピー活動 translator セクションは以下のプロパティをサポートしています:

• キー: 出典を表しています。 表形式のソースの場合は、データセット構造で定義された列名を指定します。 階層的ソースの場合は、各フィールドごとにJSONパス式を指定して抽出・マッピングします。
• 値: シンクを表します。 表状シンクの場合は、データセット構造で定義された列名を指定します。 階層的 シンクの場合は、各フィールドごとにJSONパス式を指定し、抽出・マッピングします。 階層構造のデータで、ルート オブジェクトの直下のフィールドの場合、JSON パスはルートの $ から記述します。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" } ]
}

そして、配列内のデータをフラット化して(order_pdとorder_price)と共通のルート情報(番号、日付、都市)とクロスジョインすることで、以下の形式でAzure SQLテーブルにコピーしたいです。

スキーママッピングルールを以下のコピー活動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"
        }
    }
}

関連するコンテンツ

コピー アクティビティの他の記事を参照してください。

• Copy アクティビティの概要