Использование параметров, выражений и функций в фабрике данных Azure

Статья
07/17/2023

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

Совет

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

В этом документе основное внимание уделено изучению фундаментальных концепций с различными примерами по созданию параметризованных конвейеров данных в фабрике данных Azure. Параметризация и динамические выражения — это важные дополнения к фабрике данных Azure, т. к. могут сэкономить много времени и более гибко реализовать ETL-операции (извлечения, преобразования и загрузки) и ELT-операции (извлечения, загрузки, преобразования). Это значительно сокращает затраты на обслуживание решений и ускоряет реализацию новых функций в существующих конвейерах. Эти преимущества обусловлены тем, что параметризация уменьшает количество конкретных значений переменных и увеличивает объем повторно используемых объектов и процессов.

Пользовательский интерфейс и параметры фабрики данных Azure

Если вы не знакомы с использованием параметра фабрики данных Azure в пользовательском интерфейсе ADF, изучите визуальные пояснения в статьях Пользовательский интерфейс фабрики данных для связанных служб с параметрами и Интерфейс пользователя фабрики данных для конвейера, управляемого метаданными с параметрами.

Основные понятия параметров и выражений

Параметры можно использовать для передачи внешних значений в конвейеры, наборы данных, связанные службы и потоковые данные. Переданный в ресурс параметр потом изменить не получится. Параметризация ресурсов позволяет повторно их использовать каждый раз с разными значениями. Параметры можно использовать по отдельности или в составе выражений. Значения JSON в определении могут быть литералами или выражениями, которые оцениваются в среде выполнения.

Например:

"name": "value"

"name": "@pipeline().parameters.password"

Выражения могут встречаться в любом месте строкового значения JSON и всегда возвращают другое значение JSON. Здесь password — это параметр конвейера в выражении. Если значение JSON является выражением, текст выражения извлекается без знака \"\@\". Если требуется строковый литерал, начинающийся с @, его необходимо экранировать с помощью @@. В примерах ниже показано, как вычисляются выражения.

Значение JSON	Результат
"parameters"	Возвращаются символы в виде 'parameters'.
"parameters[1]"	Возвращаются символы в виде 'parameters[1]'.
"@@"	Возвращается строка из 1 символа, содержащая символ \@\.
" @"	Возвращается строка из 2 символов, содержащая символ \@\.

Выражения также могут содержаться внутри строк, где они заключаются в структуру @{ ... }, при использовании интерполяции строк. Например: "name" : "First Name: @{pipeline().parameters.firstName} Last Name: @{pipeline().parameters.lastName}"

При использовании интерполяции строки результатом всегда будет строка. Предположим, myNumber определено как 42, а myString — как foo:

Значение JSON	Результат
"@pipeline().parameters.myString"	Возвращает `foo` как строку.
@{pipeline().parameters.myString}	Возвращает `foo` как строку.
"@pipeline().parameters.myNumber"	Возвращает `42` как номер.
@{pipeline().parameters.myString}	Возвращает `42` как строку.
"Answer is: @{pipeline().parameters.myNumber}"	Возвращает строку `Answer is: 42`.
"@concat('Answer is: ', string(pipeline().parameters.myNumber))"	Возвращает строку `Answer is: 42`.
Answer is: @{pipeline().parameters.myNumber}	Возвращает строку `Answer is: @{pipeline().parameters.myNumber}`.

Примеры использования параметров в выражениях

Пример сложных выражений

Приведенный ниже пример содержит сложное выражение, которое ссылается на глубоко вложенное поле в выходных данных действия. Чтобы создать ссылку на параметр конвейера, который вычисляет вложенное поле, используйте синтаксис [] вместо оператора точки (.) (как subfield1 и subfield2 в нашем примере).

@activity('*activityName*').output.*subfield1*.*subfield2*[pipeline().parameters.*subfield3*].*subfield4*

Редактор динамического содержимого

Редактор динамического содержимого автоматически экранирует символы в содержимом после завершения редактирования. Например, следующее содержимое в редакторе —это интерполяция строк с двумя функциями выражений.

{ 
  "type": "@{if(equals(1, 2), 'Blob', 'Table' )}",
  "name": "@{toUpper('myData')}"
}

Редактор динамического содержимого преобразует вышеприведенное содержимое в выражение "{ \n \"type\": \"@{if(equals(1, 2), 'Blob', 'Table' )}\",\n \"name\": \"@{toUpper('myData')}\"\n}". Результатом этого выражения является строка формата JSON, показанная ниже.

{
  "type": "Table",
  "name": "MYDATA"
}

Набор данных с параметрами

В следующем примере BlobDataset принимает параметр с именем path. Его значение используется для задания значения свойства folderPath с помощью выражения: dataset().path.

{
    "name": "BlobDataset",
    "properties": {
        "type": "AzureBlob",
        "typeProperties": {
            "folderPath": "@dataset().path"
        },
        "linkedServiceName": {
            "referenceName": "AzureStorageLinkedService",
            "type": "LinkedServiceReference"
        },
        "parameters": {
            "path": {
                "type": "String"
            }
        }
    }
}

Конвейер с параметрами

В следующем примере конвейер принимает параметры inputPath и outputPath. Путь к параметризованному набору данных большого двоичного объекта задается с помощью значений этих параметров. Синтаксис, используемый здесь: pipeline().parameters.parametername.

{
    "name": "Adfv2QuickStartPipeline",
    "properties": {
        "activities": [
            {
                "name": "CopyFromBlobToBlob",
                "type": "Copy",
                "inputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.inputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "BlobDataset",
                        "parameters": {
                            "path": "@pipeline().parameters.outputPath"
                        },
                        "type": "DatasetReference"
                    }
                ],
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                }
            }
        ],
        "parameters": {
            "inputPath": {
                "type": "String"
            },
            "outputPath": {
                "type": "String"
            }
        }
    }
}

Вызов функций внутри выражений

Внутри выражений можно вызывать функции. В следующих разделах предоставлены сведения о функциях, которые могут использоваться в выражении.

Строковые функции

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

Строковая функция	Задача
concat	Объединяет две или более строк и возвращает объединенную строку.
endsWith	Проверяет, заканчивается ли строка определенной подстрокой.
guid	Создает глобально уникальный идентификатор (GUID) в виде строки.
indexOf	Возвращает начальную позицию подстроки.
lastIndexOf	Возвращает начальную позицию последнего вхождения подстроки.
replace	Заменяет подстроку указанной строкой и возвращает обновленную строку.
split	Возвращает массив, содержащий подстроки, разделенные запятыми, из большей строки, основываясь на указанном символе разделителя в исходной строке.
startsWith	Проверяет, начинается ли строка с определенной подстроки.
substring	Возвращает символы из строки, начиная с указанной позиции.
toLower	Возвращает строку символов в нижнем регистре.
toUpper	Возвращает строку символов в верхнем регистре.
trim	Удаляет все начальные и конечные пробелы и возвращает обновленную строку.

Функции сбора

Для работы с коллекциями, обычно массивами, строками, а иногда и словарями, вы можете использовать следующие функции.

Функция для коллекций	Задача
contains	Проверяет наличие определенного элемента в коллекции.
empty	Проверяет, является ли коллекция пустой.
first	Возвращает первый элемент из коллекции.
intersection	Возвращает коллекцию, которая содержит только общие элементы в указанных коллекциях.
join	Возвращает строку, содержащую все элементы из массива, в которой каждый символ отделен разделителем.
last	Возвращает последний элемент из коллекции.
length	Возвращает число элементов в строке или массиве.
skip	Удаляет элементы из начала коллекции и возвращает все другие элементы.
take	Возвращает элементы, расположенные в начале коллекции.
union	Возвращает коллекцию, которая содержит все элементы из указанных коллекций.

Логические функции

Эти функции подходят для условий и могут использоваться для определения логики любого типа.

Функция логического сравнения	Задача
and	Проверяет, истинны ли все выражения.
equals	Проверяет, эквивалентны ли оба значения.
greater	Проверяет, является ли первое значение большим, чем второе.
greaterOrEquals	Проверяет, является ли первое значение большим, чем второе, или равным ему.
if	Проверьте, какое значение имеет выражение: true или false. Возвращает указанное значение на основе результата.
less	Проверяет, является ли первое значение меньшим, чем второе.
lessOrEquals	Проверяет, является ли первое значение меньшим, чем второе, или равным ему.
не	Проверяет, имеет ли выражение значение false.
or	Проверяет, является ли хотя бы одно выражение истинным.

Функции преобразования

Эти функции используются для преобразования между собственными типами языка:

строка
integer
с плавающей запятой
boolean
массивы
dictionaries;

Функция преобразования	Задача
array.	Возвращает массив из одного экземпляра указанных входных данных. Для использования нескольких входных данных см. раздел createArray.
base64	Возвращает версию строки с кодировкой base64 для заданной строки.
base64ToBinary	Возвращает двоичную версию строки с кодировкой base64.
base64ToString	Возвращает строковую версию строки с кодировкой base64.
binary	Возвращает двоичную версию входного значения.
bool	Возвращает логическую версию входного значения.
coalesce	Возвращает первое ненулевое значение из одного или нескольких параметров.
createArray	Возвращает массив из нескольких экземпляров входных данных.
dataUri	Возвращает URI данных входного значения.
dataUriToBinary	Возвращает двоичную версию строки URI данных.
dataUriToString	Возвращает строковую версию URI данных.
decodeBase64	Возвращает строковую версию строки с кодировкой base64.
decodeDataUri	Возвращает двоичную версию строки URI данных.
decodeUriComponent	Возвращает строку, которая заменяет escape-символы декодированными версиями.
encodeUriComponent	Возвращает строку, которая заменяет символы, опасные для URL-адреса, escape-символами.
float	Возвращает значение с плавающей запятой в качестве входного значения.
int	Возвращает целочисленную версию строки.
json	Возвращает значение типа JSON либо объект для строки или XML.
string	Возвращает строковую версию входного значения.
uriComponent	Возвращает кодированную версию URI для входного значения, заменив символы, опасные для URL-адреса, на escape-символы.
uriComponentToBinary	Возвращает двоичную версию строки с закодированным URI.
uriComponentToString	Возвращает строковую версию строки с закодированным URI.
xml	Возвращает XML-версию строки.
xpath	Проверяет XML на наличие узлов или значений, которые соответствуют выражению XPath, и возвращает соответствующие узлы или значения.

Математические функции

Эти функции могут использоваться для любого типа чисел: целых чисел и чисел с плавающей запятой.

Математическая функция	Задача
добавление	Возвращает результат сложения двух чисел.
div	Возвращает результат деления двух чисел.
max	Возвращает наибольшее значение из набора чисел или массива.
min	Возвращает наименьшее значение из набора чисел или массива.
mod (модуль)	Возвращает остаток результата деления двух чисел.
mul	Возвращает результат умножения двух чисел.
rand	Возвращает случайное целое число из указанного диапазона.
range	Возвращает массив целых чисел, который начинается с заданного целого числа.
sub	Вычитает второе число из первого числа и возвращает результат.

Функции данных

Функция даты и времени	Задача
addDays	Добавляет количество дней к метке времени.
addHours	Добавляет количество часов к метке времени.
addMinutes	Добавляет количество минут к метке времени.
addSeconds	Добавляет количество секунд к метке времени.
addToTime	Добавляет количество единиц времени к метке времени. См. раздел getFutureTime.
convertFromUtc	Преобразовывает метку времени формата UTC в целевой часовой пояс.
convertTimeZone	Преобразовывает метку времени из исходного часового пояса в целевой.
convertToUtc	Преобразует метку времени с исходным часовым поясом в формат UTC.
dayOfMonth	Возвращает компонент дня месяца из метки времени.
dayOfWeek	Возвращает компонент дня недели из метки времени.
dayOfYear	Возвращает компонент дня года из метки времени.
formatDateTime	Возвращает метку времени в виде строки в произвольном формате.
getFutureTime	Возвращает текущую метку времени, а также указанные единицы времени. См. раздел addToTime.
getPastTime	Возвращает текущую метку времени, вычитая указанные единицы времени. См. раздел subtractFromTime.
startOfDay	Возвращает начало дня для метки времени.
startOfHour	Возвращает начало часа для метки времени.
startOfMonth	Возвращает начало месяца для метки времени.
subtractFromTime	Вычитает количество единиц времени из метки времени. См. раздел getPastTime.
ticks	Возвращает значение свойства `ticks` для указанной метки времени.
utcNow	Возвращает текущую метку времени в виде строки.

Подробные примеры для практики

Подробный конвейер копирования фабрики данных Azure с параметрами

В руководстве по передаче параметра в конвейере копирования фабрики данных Azure описано, как передавать параметры между конвейером и действием, а также между действиями.

Подробный конвейер потока данных для сопоставления с параметрами

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

Подробные сведения о конвейере с параметрами, управляемом метаданными

Используйте конвейер с параметрами, управляемый метаданными, чтобы узнать больше об использовании параметров для проектирования конвейеров, управляемых метаданными. Это популярный вариант использования параметров.

Список системных переменных, которые можно использовать в выражениях, см. в статье System variables supported by Azure Data Factory (Системные переменные, поддерживаемые фабрикой данных Azure).