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

Область применения:Фабрика данных Azure Azure Synapse Analytics

Совет

Попробуйте использовать фабрику данных в Microsoft Fabric, решение для аналитики с одним интерфейсом для предприятий. Microsoft Fabric охватывает все, от перемещения данных до обработки и анализа данных в режиме реального времени, бизнес-аналитики и отчетности. Узнайте, как бесплатно запустить новую пробную версию !

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

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

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

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

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

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

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

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

См. также:

Вы можете настроить сопоставление в пользовательском интерфейсе разработки (действие Copy -> вкладка "Сопоставление") или программно задать режим сопоставления (действие Copy ->>translator свойство ). Ниже приведены свойства, поддерживаемые в translatorмассиве>mappings -> объектах ->source и sink с указанием на конкретные столбцы и поля для сопоставления данных.

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

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

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

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

Чтобы скопировать в базу 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 Seattle
01 20170122 P2 13 Seattle
01 20170122 P3 231 Seattle

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

  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 (см. примеры в разделе Явное сопоставление). Например, при копировании данных из табличного источника в табличный приемник значение должно быть таким: {"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.

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

Источник и приемник Логический массив байтов; Десятичное число Date/Time (1) Float-Point (2) GUID Integer (3) Строка TimeSpan
Логический
массив байтов;
Дата и время
Десятичное число
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 было создано до выпуска этой функции, такие параметры преобразования типов будут недоступны в пользовательском интерфейсе разработки. Это сделано для обеспечения обратной совместимости.
No
typeConversionSettings Группа параметров преобразования типов. Применяется, если для typeConversion задано значение true. Ниже приведены свойства, относящиеся к этой группе. No
Группа: typeConversionSettings
allowDataTruncation Разрешает усечение данных при преобразовании исходных данных в другой тип приемника во время копирования (например, из десятичного числа в целое или из DatetimeOffset в DateTime).
Значение по умолчанию — «истина».
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
Культура Сведения о языке и региональных параметрах, используемые при преобразовании типов (например, 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"
            }
        }
	},
    ...
}

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

Примечание.

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

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

Вы можете указать активность копирования ->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/REST в текстовый файл и копирование из Oracle в Azure Cosmos DB для MongoDB. В разделе translator действия копирования поддерживаются следующие свойства.

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

orderNumber orderDate order_pd order_price city
01 20170122 P1 23 Seattle
01 20170122 P2 13 Seattle
01 20170122 P3 231 Seattle

Настройте правило сопоставления схем, как в следующем примере 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"
        }
    }
}

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