Сопоставление схем и типов данных в действии Copy

применимо к: Azure синапсе Analytics фабрика данных Azure

В этой статье описано, как действие Copy в Фабрике данных Azure сопоставляет схемы и типы исходных данных и данных приемника.

Сопоставление схем

Сопоставление по умолчанию

По умолчанию действие Copy сопоставляет исходные данные с приемниками по именам столбцов с учетом регистра. Если приемника не существует (например, при записи в файлы), имена исходных полей будут сохраняться как имена приемника. Если приемник уже существует, в нем должны быть все столбцы, копируемые из источника. Этот стандартный режим сопоставления поддерживает гибкие схемы и смещение схем от источника к приемнику от выполнения до выполнения. Все данные, которые возвращает хранилище исходных данных, можно копировать в приемник.

Если источником является текстовый файл без строки заголовка, из-за отсутствия имен столбцов требуется явное сопоставление.

Явное сопоставление

Явное сопоставление позволяет настроить сопоставление столбцов и полей от источника к приемнику согласно вашим потребностям. Так можно копировать в приемник только часть исходных данных, сопоставлять исходные данные с приемником под разными именами и преобразовывать табличные или иерархические данные. Действие Copy:

  1. Считывает данные из источника и определяет исходную схему.
  2. Применяет заданный режим сопоставления.
  3. Записывает данные в приемник.

Дополнительные сведения

Вы можете настроить сопоставление на вкладке Создание пользовательского интерфейса — > действие копирования — > Сопоставление или программно указать сопоставление в >translator свойстве действие копирования. Следующие свойства поддерживаются в параметрах translator - >mappings array- > Objects- >source и sink , которые указывают на конкретный столбец или поле для отображения данных.

Свойство Описание Обязательно
name Имя столбца или поля источника (приемника). Применяется для табличных источников и приемников. Да
ordinal Индекс столбца. Начинается со значения "1".
Применяется и требуется при использовании текста с разделителями без строки заголовка.
Нет
path Выражение пути JSON для каждого поля, которое используется для извлечения или сопоставления данных. Применяется для иерархических источников и приемников, например Cosmos DB, MongoDB и соединителей REST.
Для полей в корневом объекте путь JSON начинается с корня $. Для полей внутри массива, выбранного свойством collectionReference, путь JSON начинается с элемента массива без $.
Нет
type Промежуточный тип данных в столбце источника или приемника. Обычно это свойство не требуется ни указывать, ни изменять. Подробнее о сопоставлении типов данных. Нет
culture Язык и региональные параметры столбца источника или приемника. Применяется, если тип — Datetime или Datetimeoffset. Значение по умолчанию — en-us.
Обычно это свойство не требуется ни указывать, ни изменять. Подробнее о сопоставлении типов данных.
Нет
format Строка формата, используемая для типов Datetime и Datetimeoffset. Сведения о формате даты и времени см. в статье Строки настраиваемых форматов даты и времени. Обычно это свойство не требуется ни указывать, ни изменять. Подробнее о сопоставлении типов данных. Нет

Помимо mappings, в translator поддерживаются следующие свойства:

Свойство Описание Обязательно
collectionReference Применяется при копировании данных из иерархических источников, например Cosmos DB, MongoDB и соединителей REST.
Для итерации и извлечения данных из объектов в поле массива с таким же шаблоном и построчного преобразования этих данных по каждому объекту укажите путь JSON массива для перекрестного применения.
Нет

Табличный источник для табличного приемника

Чтобы скопировать в базу SQL Azure данные, например, из Salesforce с явным сопоставлением трех столбцов, сделайте следующее:

  1. На вкладке "действие копирования — > Сопоставление" нажмите кнопку > , чтобы импортировать схемы источника и приемника.

  2. Сопоставьте необходимые поля и исключите или удалите остальные.

Map tabular to tabular

Такое же сопоставление можно настроить в полезных данных действия Copy (см. 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" }
                }
            ]
        }
    },
    ...
}

Иерархический источник для табличного приемника

При копировании данных из иерархического источника в табличный приемник действие Copy поддерживает следующие возможности:

  • Извлечение данных из объектов и массивов.
  • Перекрестное применение нескольких объектов с одинаковым шаблоном из массива (в этом случае для преобразования одного объекта 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) и выполнив перекрестное соединение с общими корневыми сведениями (number, date, city) :

orderNumber orderDate order_pd order_price city
01 20170122 P1 23 Сиэтл
01 20170122 P2 13 Сиэтл
01 20170122 P3 231 Сиэтл

Такое сопоставление можно определить в пользовательском интерфейсе разработки Фабрики данных:

  1. На вкладке "действие копирования — > Сопоставление" нажмите кнопку > , чтобы импортировать схемы источника и приемника. Иногда какое-либо поле не отображается, когда служба выполняет выборку самых верхних объектов при импорте схемы. Такое поле можно добавить в нужный слой в иерархии. Наведите указатель на имеющееся имя поля и выберите, что добавить (узел, объект или массив).

  2. Выберите массив, из которого необходимо выполнить итерацию и извлечение данных. Он будет автоматически определен как ссылка на коллекцию. Обратите внимание: такую операцию можно проводить только с одним массивом.

  3. Сопоставьте необходимые поля с приемником. Служба автоматически определяет соответствующие пути JSON для иерархической стороны.

Примечание

Если в какой-либо записи установлен флажок и пуст массив, помеченный как ссылка на коллекцию, вся запись пропускается.

Map hierarchical to tabular using UI

Можно также переключиться в расширенный редактор. В нем можно просматривать и изменять пути JSON для полей. Чтобы добавить новое сопоставление в этом представлении, укажите путь JSON.

Map hierarchical to tabular using advanced editor

Такое же сопоставление можно настроить в полезных данных действия Copy (см. 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 определения. см. раздел примеры в 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 и Synapse.
  2. Автоматическое преобразование промежуточного типа данных для сопоставления с соответствующими типами приемников (выполняется и в режиме по умолчанию, и при явном сопоставлении).
  3. Преобразование промежуточных типов в собственные типы приемника.

Сейчас действие Copy поддерживает следующие промежуточные типы данных: Boolean, Byte, Byte Array, Datetime, DatetimeOffset, Decimal, Double, GUID, Int16, Int32, Int64, SByte, Single, String, Timespan, UInt16, UInt32, UInt64.

Ниже приведены поддерживаемые преобразования между промежуточными типами данных источника и приемника.

Источник и приемник Логическое массив байтов; Decimal Date/Time (1) Float-Point (2) Код GUID Integer (3) Строка TimeSpan
Логическое
массив байтов;
Дата и время
Decimal
Float-Point
Код GUID
Целочисленный тип
Строка
TimeSpan

(1) Date/Time включает DateTime и DateTimeOffset.

(2) Float-Point включает Single и Double.

(3) Integer включает SByte, Byte, Int16, UInt16, Int32, UInt32, Int64 и UInt64.

Примечание

  • Сейчас такое преобразование типов данных поддерживается при копировании между табличным источником и приемником. Для иерархических структур оно пока невозможно, поэтому для промежуточных типов таких источников и приемников недоступно определяемое системой преобразование типов данных.
  • Эта функция работает с последней моделью наборов данных. Если параметр не отображается в пользовательском интерфейсе, попробуйте создать новый набор данных.

Ниже приведены свойства, поддерживаемые действием Copy для преобразования типов данных (программная разработка, раздел translator).

Свойство Описание Обязательно
typeConversion Включите новый интерфейс преобразования типов данных.
В целях обратной совместимости по умолчанию используется значение false.

Для новых действий копирования, созданных с помощью пользовательского интерфейса создания фабрики данных, начиная с 2020 июня, это преобразование типов данных по умолчанию включено для лучшей работы, а на > вкладке Сопоставление действия копирования для применимых сценариев можно просмотреть следующие параметры преобразования типов.
Для создания конвейера программным путем необходимо включить свойство typeConversion, задав для него значение true.
Если действие Copy было создано до выпуска этой функции, такие параметры преобразования типов будут недоступны в пользовательском интерфейсе разработки. Это сделано для обеспечения обратной совместимости.
Нет
typeConversionSettings Группа параметров преобразования типов. Применяется, если для typeConversion задано значение true. Ниже приведены свойства, относящиеся к этой группе. Нет
Группа:
allowDataTruncation Разрешает усечение данных при преобразовании исходных данных в другой тип приемника во время копирования (например, из десятичного числа в целое или из DatetimeOffset в DateTime).
Значение по умолчанию — true.
Нет
treatBooleanAsNumber Обрабатывает логические значения как числа (например, true — как 1).
Значение по умолчанию — false.
Нет
dateTimeFormat Форматирует строку при преобразовании дат без смещения часового пояса в строки (пример формата: yyyy-MM-dd HH:mm:ss.fff). Подробности см. в статье Строки настраиваемых форматов даты и времени. Нет
dateTimeOffsetFormat Форматирует строку при преобразовании дат со смещением часового пояса в строки (пример формата: yyyy-MM-dd HH:mm:ss.fff zzz). Подробности см. в статье Строки настраиваемых форматов даты и времени. Нет
timeSpanFormat Форматирует строку при преобразовании периодов времени в строки (пример формата: dd\.hh\:mm). Подробности см. в статье Строки пользовательского формата TimeSpan. Нет
culture Сведения о языке и региональных параметрах, используемые при преобразовании типов (например, 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"
            }
        }
	},
    ...
}

Устаревшие модели

Примечание

Ниже приведены модели сопоставления столбцов и полей в источнике и приемнике, которые по-прежнему поддерживаются в целях обратной совместимости. Не советуем ими пользоваться. Лучше выбирайте новую модель, описанную в разделе Сопоставление схем. В пользовательском интерфейсе разработки уже используется именно эта новая модель.

Альтернативное сопоставление столбцов (устаревшая модель)

Вы можете указать действие копирования >translator>columnMappings , чтобы сопоставлять табличные данные. В этом случае для входных и выходных наборов данных обязателен раздел structure. Функция сопоставления столбцов поддерживает сопоставление всех или подмножества столбцов в разделе structure набора данных, используемого в качестве источника, со всеми столбцами в разделе 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, который определяет действие копирования в конвейере. Столбцы из источника сопоставлены со столбцами в приемнике с помощью свойства Translator - 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/остальное в текстовый файл и копировать из Oracle в API Azure Cosmos DB для MongoDB. В разделе translator действия копирования поддерживаются следующие свойства.

Свойство Описание Обязательно
type Для преобразователя действия Copy свойство type должно иметь значение TabularTranslator. Да
schemaMapping Коллекция пар "ключ-значение", которая представляет отношение сопоставления между источником и приемником.
- - представляет источник. Для табличного источникаукажите имя столбца, определенное в структуре набора данных. Для иерархического источника укажите выражение пути JSON для каждого поля, которое необходимо извлечь и сопоставить.
- - представляет приемник. Для табличного приемникаукажите имя столбца, определенное в структуре набора данных. Для иерархического приемника укажите выражение пути JSON для каждого поля, которое необходимо извлечь и сопоставить.
При иерархической структуре путь JSON для полей в корневом объекте начинается с корня $. Для полей внутри массива, выбранного свойством collectionReference, путь JSON начинается с элемента массива.
Да
collectionReference Для итерации и извлечения данных из объектов в поле массива с таким же шаблоном и построчного преобразования этих данных по каждому объекту укажите путь 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) и перекрестного соединения с общими сведениями о корневом объекте (number, date и city).

orderNumber orderDate order_pd order_price city
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"
        }
    }
}

Дальнейшие действия

См. другие статьи о действиях копирования: