Создание карт для преобразования данных в Azure Logic Apps с помощью Visual Studio Code

Статья
11/15/2023

Область применения: Azure Logic Apps (стандартная версия)

Чтобы обмениваться сообщениями с различными форматами XML или JSON в рабочем процессе Azure Logic Apps, необходимо преобразовать данные из одного формата в другой, особенно если между структурами исходной и целевой схемы есть пробелы. Преобразование данных помогает преодолеть эти пробелы. Для этой задачи необходимо создать карту, которая определяет преобразование между элементами данных в исходных и целевых схемах.

Для визуального создания и редактирования карты можно использовать Visual Studio Code с расширением Azure Logic Apps (standard) в контексте проекта приложения логики "Стандартный". Средство сопоставления данных предоставляет унифицированный интерфейс для сопоставления и преобразования XSLT с помощью жестов перетаскивания, предварительно созданной библиотеки функций для создания выражений и способа вручную проверить карты, созданные и используемые в рабочих процессах.

После создания карты вы можете напрямую вызвать эту карту из рабочего процесса в проекте приложения логики или из рабочего процесса в портал Azure. Для этой задачи можно использовать действие "Операции сопоставления данных" с именем "Преобразование" с помощью XSLT средства сопоставления данных в рабочем процессе.

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

Известные проблемы и ограничения

В настоящее время средство сопоставления данных работает только в Visual Studio Code, работающем в операционных системах Windows.
Mapper данных в настоящее время доступен только в Visual Studio Code, а не в портал Azure, а только из проектов приложения логики "Стандартный", а не в проектах приложения логики потребления.
В настоящее время Mapper данных не поддерживает файлы с разделителями-запятыми (.csv).
Область представления кода карты данных в настоящее время доступна только для чтения.
Макет карты и позиция элемента в настоящее время автоматически и доступны только для чтения.
Чтобы вызвать карты, созданные с помощью средства сопоставления данных, можно использовать только действие "Операции сопоставления данных" с именем "Преобразование" с помощью XSLT для сопоставления данных. Для карт, созданных любым другим средством, используйте действие xml Operations с именем Transform XML.
Чтобы использовать карты, создаваемые с помощью средства сопоставления данных, но в портал Azure, необходимо добавить их непосредственно в ресурс приложения логики "Стандартный".

Необходимые компоненты

Visual Studio Code и расширение Azure Logic Apps (standard) для создания рабочих процессов приложения логики уровня "Стандартный".

Примечание.

Ранее отдельное расширение Mapper данных теперь объединяется с расширением Azure Logic Apps (Standard). Чтобы избежать конфликтов, при установке или обновлении расширения Azure Logic Apps (стандартный) удаляется любая существующая версия расширения Mapper данных. После установки или обновления расширения перезапустите Visual Studio Code.
Исходные и целевые файлы схемы, описывающие типы данных для преобразования. Эти файлы могут иметь любой из следующих форматов:
- Файл определения схемы XML с расширением XSD-файла
- Файл нотации объектов JavaScript с расширением файла .json
Проект приложения логики уровня "Стандартный", включающий рабочий процесс без отслеживания состояния или рабочий процесс без отслеживания состояния с по крайней мере триггером. Если у вас нет проекта, выполните следующие действия в Visual Studio Code:
1. Подключитесь к учетной записи Azure, если вы еще не сделали этого.
2. Создайте локальную папку, локальный проект приложения логики "Стандартный" и рабочий процесс без отслеживания состояния. Во время создания рабочего процесса выберите "Открыть" в текущем окне.
Пример входных данных, если вы хотите протестировать карту и убедитесь, что преобразование работает должным образом.
Чтобы использовать функцию Run XSLT, фрагменты кода XSLT должны существовать в файлах, использующих расширение имени файла .xml или Xslt . Необходимо поместить фрагменты XSLT в папку InlineXslt в структуру локальной папки проекта: Artifacts>DataMapper>Extensions>InlineXslt. Если эта структура папок не существует, создайте отсутствующие папки.

Создание карты данных

В меню слева Visual Studio Code выберите значок Azure .
В области Azure в разделе "Сопоставление данных" выберите "Создать карту данных".
Укажите имя карты данных.
Укажите исходные и целевые схемы, выполнив следующие действия.
1. На поверхности карты выберите " Добавить исходную схему".
2. На открывающейся панели "Настройка" нажмите кнопку "Добавить новый>обзор".
3. Найдите и выберите исходный файл схемы, а затем нажмите кнопку "Добавить".
  
  Если исходная схема не отображается в окне "Открыть", в списке типов файлов измените XSD-файл (*.xsd) на все файлы (*.*.*).
  
  Теперь на поверхности карты отображаются типы данных из исходной схемы. Примеры, приведенные в этом руководстве,
4. На поверхности карты выберите " Добавить целевую схему".
5. На открывающейся панели "Настройка" нажмите кнопку "Добавить новый>обзор".
6. Найдите и выберите целевой файл схемы, а затем нажмите кнопку "Добавить".
  
  Если целевая схема не отображается в окне "Открыть", в списке типов файлов измените XSD-файл (*.xsd) на все файлы (*.*.*).
  
  На поверхности карты теперь отображаются типы данных из целевой схемы.
Кроме того, можно добавить исходные и целевые файлы схем локально в проект приложения логики в папке "Схемы артефактов/", чтобы они отображались в Visual Studio Code. В этом случае можно указать исходную и целевую схему в средстве "Сопоставление данных" на панели "Настройка", выбрав "Выбрать существующий", а не "Добавить".

По завершении карта выглядит примерно так:

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

Символ	Тип	Дополнительная информация
	Массив	Содержит элементы или узлы повторяющихся элементов
	Binary
	Bool	Только true или false
	Complex	XML-объект со свойствами дочерних объектов, аналогичный типу OBJECT JSON
	Дата/время
	Десятичное число
	Целое	Только целые числа
	Null	Не тип данных, но отображается при возникновении ошибки или недопустимого типа
	Число	Целое или десятичное число JSON
	Object	Объект JSON со свойствами дочерних объектов, аналогичный сложному типу XML
	Строка

Навигация по карте

Чтобы перемещаться по карте, у вас есть следующие параметры:

Чтобы переместить вокруг, перетащите указатель вокруг поверхности карты. Или нажмите и удерживайте колесико мыши при перемещении мыши или трекбола.

После перемещения одного уровня вниз на карту в левом нижнем углу карты появится панель навигации, где можно выбрать из следующих параметров:

Снимок экрана: панель навигации карты.

Вариант	Альтернативный жест
Увеличение масштаба	На поверхности карты нажмите клавиши SHIFT + двойной выбор. -или- Прокрутите вниз колесиком мыши.
Увеличение масштаба	На поверхности карты дважды выберите. -или- Прокрутите вверх с помощью колесика мыши.
Масштабирование для соответствия	нет
Показать (скрыть) мини-карту	нет

Чтобы перейти на один уровень на карте, в верхней части карты выберите предыдущий уровень.

Выбор целевых и исходных элементов для сопоставления

На поверхности карты, начиная с правой стороны, в целевой области схемы выберите целевой элемент, который требуется сопоставить. Если нужный элемент является дочерним элементом родительского элемента, найдите и разверните родительский элемент.
Теперь в левой части области исходной схемы выберите элемент Select.
В появившемся окне схемы источника выберите один или несколько исходных элементов для отображения на карте.
- Чтобы включить родительские и прямые дочерние элементы, откройте контекстное меню родителя и нажмите кнопку "Добавить дочерние".
- Чтобы включить родительский и все дочерние элементы для этого родителя, включая всех дочерних родителей, откройте контекстное меню верхнего уровня и выберите "Добавить дочерние" (рекурсивные).
По завершении можно закрыть окно исходной схемы. Вы всегда можете добавить дополнительные исходные элементы позже. На карте в левом верхнем углу выберите "Показать исходную схему " ().

Создание прямого сопоставления между элементами

Для простого преобразования между элементами с одинаковым типом в исходных и целевых схемах выполните следующие действия:

Чтобы просмотреть, что происходит в коде при создании сопоставления, в правом верхнем углу карты выберите "Показать код".
Если вы еще не сделали, на карте выберите целевые элементы и исходные элементы, которые вы хотите сопоставить.
Переместите указатель на исходный элемент, чтобы отображались как круг, так и знак плюса (+).
Перетащите линию в целевой элемент, чтобы строка подключилась к появившемся кругу.

Теперь вы создали прямое сопоставление обоих элементов.

Окно представления кода отражает созданную связь сопоставления:

Примечание.

Если вы создаете сопоставление между элементами, в которых их типы данных не совпадают, в целевом элементе появится предупреждение, например:

Снимок экрана: прямое сопоставление между типами данных несоответствия.

Создание сложного сопоставления между элементами

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

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

Групповой	Примеры функций
Коллекция	Среднее, счетчик, прямой доступ, уникальные значения, фильтр, индекс, соединение, максимальное, минимальное, обратное, сортировка, подсечет, сумма
Преобразование	К дате, целое число, число, "Строка"
Дата и время	Добавление дней
Логическое сравнение	Равно, существует, больше, больше или равно, если, если, is nil, is null, Is number, Is string, Less, Less или equal, Logical AND, Logical NOT, Logical OR, Not equal
Мат. функции	Absolute, Add, Arctangent, Ceiling, Cosine, Divide, Exponential, Exponential (base 10), Floor, Integer divide, Log, Log (base 10), Module, Multiply, Power, Round, Sine, Square root, Subtract, Tangent
Строка	Код указывает на строку, Concat, Contains, Ends with, Length, Lowercase, Name, Regular expression replace, Regular expression replace, Replace, Starts with, String to code-points, Substring, Substring after, Substring after, Trim left, Trim left, Trim right, Uppercase
Utility	Копирование, ошибка, выполнение XPath, формат даты и времени, номер формата, выполнение XSLT

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

Снимок экрана: пример метки функции.

Добавление функции без связи сопоставления

Пример в этом разделе преобразует тип исходного элемента из типа String в тип DateTime, соответствующий типу целевого элемента. В примере используется функция "Дата" , которая принимает один вход.

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

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

Примечание.

Если при добавлении функции в карту строка сопоставления не существует или выбрана, функция отображается на карте, но отключена от любых элементов или других функций, например:
Разверните фигуру функции, чтобы отобразить сведения о функции и точки подключения. Чтобы развернуть фигуру функции, выберите внутри фигуры.
Подключите функцию к исходным и целевым элементам.
1. Перетащите и нарисуйте линию между исходными элементами и левым краем функции. Вы можете начать либо из исходных элементов, либо из функции.
2. Перетащите и нарисуйте линию между правым краем функции и целевым элементом. Вы можете начать либо из целевого элемента, либо из функции.
На вкладке "Свойства" функции подтвердите или измените входные данные для использования.

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

Окно представления кода отражает созданную связь сопоставления:

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

Добавление функции в существующую связь сопоставления

Если связь сопоставления уже существует между исходными и целевыми элементами, можно добавить функцию, выполнив следующие действия:

На карте выберите строку для созданного сопоставления.
Переместите указатель по выбранной строке и выберите знак "Вставка плюс " (+например:
В открывающемся списке функций найдите и выберите нужную функцию.

Функция отображается на карте и автоматически подключается между исходными и целевыми элементами.

Добавление функции с несколькими входными данными

Пример в этом разделе объединяет несколько типов исходных элементов, чтобы можно было сопоставить результаты с типом целевого элемента. В примере используется функция Concat , которая принимает несколько входных данных.

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

В этом примере выбирается функция Concat :

Примечание.

Если при добавлении функции в карту строка сопоставления не существует или выбрана, функция отображается на карте, но отключена от любых элементов или других функций. Если функция требует настройки, красная точка появится в правом верхнем углу функции, например:
Разверните фигуру функции, чтобы отобразить сведения о функции и точки подключения. Чтобы развернуть фигуру функции, выберите внутри фигуры.
В области сведений о функции на вкладке "Свойства " в разделе "Входные данные" выберите исходные элементы данных, которые будут использоваться в качестве входных данных.

В этом примере выбираются исходные элементы FirstName и LastName в качестве входных данных функции, которые автоматически добавляют соответствующие подключения на карте.
Чтобы завершить перетаскивание сопоставления и нарисовать линию между правым краем функции и целевым элементом. Вы можете начать либо из целевого элемента, либо из функции.

Окно представления кода отражает созданную связь сопоставления:

Создание цикла между массивами

Если исходные и целевые схемы включают массивы, можно создать связь сопоставления циклов, которая выполняет итерацию элементов в этих массивах. В примере этого раздела выполняется цикл по исходному массиву Employee и целевому массиву Person.

Чтобы просмотреть, что происходит в коде при создании сопоставления, в правом верхнем углу карты выберите "Показать код".
На карте в области целевой схемы выберите элемент целевого массива и элементы элемента целевого массива, которые требуется сопоставить.
На карте в области целевой схемы разверните элемент целевого массива и элементы массива.
В области исходной схемы добавьте элемент исходного массива и элементы элемента массива в карту.
Создайте прямое сопоставление между исходными и целевыми элементами.

При первом создании связи сопоставления между сопоставленной парой элементов массива связь сопоставления автоматически создается на родительском уровне массива.

Окно представления кода отражает созданную связь сопоставления:
Продолжить сопоставление других элементов массива.

Настройка условия и задачи для выполнения между элементами

Чтобы добавить связь сопоставления, которая оценивает условие и выполняет задачу при выполнении условия, можно использовать несколько функций, например функцию If, функцию сравнения, например "Больше", а также задачу для выполнения такой задачи, как Умножение.

Пример в этом разделе вычисляет скидку, которая будет применяться, если количество покупок превышает 20 элементов с помощью следующих функций:

Больше: проверьте, превышает ли количество элементов 20.
Если: проверьте, возвращается ли функция Greater true.
Умножение: вычислите скидку, умножив цену на 10% и количество элементов.

Чтобы просмотреть, что происходит в коде при создании сопоставления, в правом верхнем углу карты выберите "Показать код".
Если вы еще не сделали, на карте выберите целевые элементы и исходные элементы, которые вы хотите сопоставить.

В этом примере выбираются следующие элементы:
В левом верхнем углу карты выберите "Показать функции " ().
Добавьте следующие функции на карту: "Больше", "Если" и "Умножение"
Разверните все фигуры функции, чтобы отобразить сведения о функции и точки подключения.
Подключите исходные элементы, функции и целевые элементы следующим образом:
- Элемент ItemPrice исходной схемы для элемента ItemPrice целевой схемы
- Элемент ItemQuantity исходной схемы в поле "Значение" функции "Больше"
- Выходные данные функции "Больший" в поле условия функции If
- Элемент ItemPrice исходной схемы в поле "Умножение" функции "Умножение" 0*
- Выходные данные функции Умножения в поле "Значение" функции If
- Выходные данные функции If в элемент ItemDiscount целевой схемы
Примечание.

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

В следующих функциях на вкладке "Свойства " укажите следующие значения:

Function	Входной параметр и значение
Выше	- Значение #1: исходный элемент с именем ItemQuantity - Значение #2: 20
Умножение	- Умножение #1: исходный элемент с именем ItemPrice - Умножение #2: .10
If	- Условие: больше(ItemQuantity,20) - Значение: умножение(ItemPrice, .10)

На следующей карте показан готовый пример:

Снимок экрана: пример готового условия.

Окно представления кода отражает созданную связь сопоставления:

Снимок экрана: представление кода с условным сопоставлением между исходными и целевыми элементами с помощью функций,

Сохранение карты

По завершении на панели инструментов карты нажмите кнопку "Сохранить".

Visual Studio Code сохраняет карту в виде следующих артефактов:

Файл <map-name>.yml в папке проекта Artifacts>MapDefinitions
Файл <map-name.xslt> в папке проекта Artifacts Maps>

Создание XSLT-файла в любое время

Чтобы создать <файл map-name.xslt> в любое время, на панели инструментов карты выберите "Создать XSLT".

Проверка карты

Чтобы убедиться, что преобразование работает должным образом, вам потребуется образец входных данных.

Прежде чем протестировать карту, создайте последнюю версию <файла map-name.xslt.>
На панели инструментов карты выберите "Тест".
На панели "Карта тестирования" в окне "Входные данные" вставьте образец входных данных и выберите "Тест".

Панель тестирования переключается на вкладку "Выходные данные " и отображает код состояния теста и текст ответа.

Вызов карты из рабочего процесса в проекте

В меню слева Visual Studio Code выберите проводник (значок файлов), чтобы просмотреть структуру проекта приложения логики.
Разверните папку с именем рабочего процесса. В контекстном меню файла workflow.json выберите "Открыть конструктор".
В конструкторе рабочих процессов выполните следующие общие действия, чтобы добавить встроенное действие "Операции сопоставления данных" с именем "Преобразование" с помощью XSLT для сопоставления данных.
В конструкторе выберите действие Преобразования с помощью действия XSLT для сопоставления данных.
В появившейся области сведений о действии укажите значение содержимого и оставьте для источника карты значение Logic App. В списке имен карты выберите файл карты (Xslt), который требуется использовать.

Чтобы использовать то же преобразование с помощью действия XSLT для сопоставления данных в портал Azure, необходимо добавить карту в ресурс приложения логики "Стандартный".

Создание пользовательской функции

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

Создайте XML-файл (.xml), имеющий понятное имя, описывающее назначение функции.

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

В XML-файле необходимо использовать следующую схему для определения функции:

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:element name="customfunctions">
      <xs:complexType>
         <xs:sequence>
            <xs:element maxOccurs="unbounded" name="function">
               <xs:complexType>
                  <xs:sequence>
                     <xs:element maxOccurs="unbounded" name="param">
                        <xs:complexType>
                            <xs:attribute name="name" type="xs:string" use="required" />
                            <xs:attribute name="as" type="xs:string" use="required" />
                        </xs:complexType>
                     </xs:element>
                     <xs:any minOccurs="0" />
                  </xs:sequence>
                  <xs:attribute name="name" type="xs:string" use="required" />
                  <xs:attribute name="as" type="xs:string" use="required" />
                  <xs:attribute name="description" type="xs:string" use="required" />
               </xs:complexType>
            </xs:element>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>

Каждый XML-элемент с именем function реализует функцию стиля XSLT3.0 с несколькими дополнительными атрибутами. Список функций Mapper данных содержит имя функции, описание, имена параметров и типы параметров.

В следующем примере показана реализация файла SampleFunctions.xml :

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<customfunctions>
   <function name="age" as="xs:float" description="Returns the current age.">
      <param name="inputDate" as="xs:date"/> 
      <value-of select="round(days-from-duration(current-date() - xs:date($inputDate)) div 365.25, 1)"/>
   </function> 
   <function name="custom-if-then-else" as="xs:string" description="Evaluates the condition and returns corresponding value.">
      <param name="condition" as="xs:boolean"/>
      <param name="thenResult" as="xs:anyAtomicType"/>
      <param name="elseResult" as="xs:anyAtomicType"/>
      <choose>
         <when test="$condition">
            <value-of select="$thenResult"></value-of>
         </when>
         <otherwise>
            <value-of select="$elseResult"></value-of>
         </otherwise>
      </choose>
   </function>
</customfunctions>

На локальном компьютере откройте папку для проекта приложения логики "Стандартный".
Откройте папку Artifacts и создайте следующую структуру папок, если она отсутствует: Функции расширений>DataMapper.>
В папке "Функции" сохраните XML-файл функции.
Чтобы найти пользовательскую функцию в списке функций средства сопоставления данных, найдите функцию или разверните коллекцию пользовательских функций .

Следующие шаги

Сведения о преобразованиях данных с помощью операций B2B в Azure Logic Apps см. в статье "Добавление карт для преобразований в рабочих процессах с помощью Azure Logic Apps"

Поделиться через