Преобразование файлов JSON и XML с помощью шаблонов Liquid как сопоставлений в рабочих процессах с использованием службы Azure Logic Apps

Область применения: Azure Logic Apps (Потребление + Стандартный)

При необходимости выполнения основных преобразований JSON в рабочих процессах приложений логики можно использовать встроенные операции с данными, такие как Создание или Синтаксический анализ JSON. Однако в некоторых сценариях могут потребоваться расширенные и сложные преобразования, включающие такие элементы, как итерации, потоки управления и переменные. Для преобразований JSON в JSON, JSON в текст, XML в JSON или XML в текст можно создать шаблон, описывающий необходимое сопоставление или преобразование с помощью языка шаблонов Liquid с открытым исходным кодом. Этот шаблон можно выбрать при добавлении встроенного действия Liquid в рабочий процесс. Вы можете использовать действия Liquid в рабочих процессах приложения логики с несколькими клиентами и рабочих процессах приложения логики уровня "Стандартный".

Хотя триггеры Liquid отсутствуют, вы можете использовать любой триггер или действие для передачи исходного содержимого JSON или XML в рабочий процесс. Например, можно использовать встроенный триггер соединителя, управляемый или размещенный в Azure триггер соединителя, доступный для Azure Logic Apps, или даже другое приложение.

В этой статье показано, как выполнять следующие задачи:

• Создание шаблона Liquid.
• Отправьте шаблон в учетную запись интеграции для рабочих процессов приложения логики категории "Потребление" или в ресурс приложения логики категории "Стандартный" для использования в любом дочернем рабочем процессе.
• Добавьте действие Liquid в рабочий процесс.
• Выбор шаблона в качестве сопоставления, которое необходимо использовать.

Дополнительные сведения см. в следующей документации:

• Выполнение операций с данными в Azure Logic Apps
• Язык шаблонов Liquid с открытым исходным кодом
• Приложения логики категории "Потребление" и "Стандартный"
• Встроенные соединители учетной записи интеграции
• Общие сведения о встроенных соединителях для Azure Logic Apps
• Общие сведения об управляемых или размещенных в Azure соединителях для Azure Logic Apps и управляемых или размещенных в Azure cоединителях в Azure Logic Apps

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

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

• Ресурс и рабочий процесс приложения логики. Операции Liquid не имеют доступных триггеров, поэтому рабочий процесс должен включать хотя бы один триггер. Дополнительные сведения см. в следующей документации:

  • Создание примера рабочего процесса приложения логики потребления в мультитенантных Azure Logic Apps

  • Создание примера рабочего процесса приложения логики уровня "Стандартный" в azure Logic Apps с одним клиентом

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

  Внимание

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

  • Если вы работаете над рабочим процессом приложения логики уровня "Потребление", то для учетной записи интеграции требуется ссылка на ресурс приложения логики.

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

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

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

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

• Базовые знания о языке шаблонов Liquid Azure Logic Apps использует DotLiquid 2.0.361.

  Примечание.

  Действие Liquid под названием Преобразование JSON в JSON соответствует реализации DotLiquid для Liquid, которая в отдельных случаях отличается от реализации Shopify для Liquid. Дополнительные сведения см. в разделе Рекомендации по шаблонам Liquid.

• Установите или используйте средство, которое может отправлять HTTP-запросы для тестирования решения, например:

  • Visual Studio Code с расширением из Visual Studio Marketplace
  • PowerShell Invoke-RestMethod
  • Microsoft Edge — средство сетевой консоли
  • Бруно
  • curl

  Внимание

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

Шаг 1. Создание шаблона

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

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

   В примере преобразования JSON в JSON в этой статье используется следующий пример шаблона Liquid:

   {%- assign deviceList = content.devices | Split: ', ' -%}
   
   {
      "fullName": "{{content.firstName | Append: ' ' | Append: content.lastName}}",
      "firstNameUpperCase": "{{content.firstName | Upcase}}",
      "phoneAreaCode": "{{content.phone | Slice: 1, 3}}",
      "devices" : [
         {%- for device in deviceList -%}
            {%- if forloop.Last == true -%}
            "{{device}}"
            {%- else -%}
            "{{device}}",
            {%- endif -%}
         {%- endfor -%}
      ]
   }
   

2. Сохраните шаблон, указав расширение файла шаблона Liquid (.liquid). В этом примере используется SimpleJsonToJsonTemplate.liquid.

Шаг 2. Отправка шаблона Liquid

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

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

• Если вы работаете с рабочим процессом приложения логики уровня "Стандартный", вы можете отправить шаблон в учетную запись интеграции или отправить шаблон в ресурс приложения логики.

Отправка схем в учетную запись интеграции

1. Войдите на портал Azure с помощью учетных данных учетной записи Azure.

2. В поле поиска на портале Azure введите текст учетные записи интеграции и выберите элемент Учетные записи интеграции.

   

3. Найдите и выберите учетную запись интеграции.

   

4. В меню навигации учетной записи интеграции в разделе Параметры выберите пункт Maps.

   

5. На панели Maps выберите Добавить. Укажите следующие сведения о сопоставлении:

   Свойство	Значение	Описание
   Имя	JsonToJsonTemplate	Это имя сопоставления, в нашем примере это "JsontoJsonTemplate"
   Тип сопоставления	Liquid	Обозначает тип сопоставления. Для преобразования JSON в JSON необходимо выбрать Liquid.
   Map	SimpleJsonToJsonTemplate.liquid	Это существующий файл шаблона или сопоставления Liquid, который будет использован для преобразования. В нашем примере это SimpleJsonToJsonTemplate.liquid. Чтобы найти этот файл, используйте средство выбора файлов. Ограничения размера сопоставления см. в разделе Ограничения и конфигурация.

   

Отправка шаблона в приложение логики уровня "Стандартный"

1. На портале Azure найдите ресурс приложения логики и откройте его. Убедитесь, что вы находитесь на уровне ресурса, а не на уровне рабочего процесса.

2. В меню навигации приложения логики в разделе Артефакты выберите Карты.

3. На панели инструментов на панели Карты выберите Добавить.

4. На панели Добавить карту укажите следующие сведения о шаблоне:

   Свойство	Значение	Описание
   Имя	JsonToJsonTemplate	Это имя сопоставления, в нашем примере это "JsontoJsonTemplate"
   Тип сопоставления	Liquid	Обозначает тип сопоставления. Для преобразования JSON в JSON необходимо выбрать Liquid.
   Map	SimpleJsonToJsonTemplate.liquid	Это существующий файл шаблона или сопоставления Liquid, который будет использован для преобразования. В нашем примере это SimpleJsonToJsonTemplate.liquid. Чтобы найти этот файл, используйте средство выбора файлов. Ограничения размера сопоставления см. в разделе Ограничения и конфигурация.

5. По завершении нажмите кнопку OK.

   Когда файл карты будет отправлен, карта появится в списке Карты. Отправленная карта также появится на странице Обзор учетной записи интеграции в разделе Артефакты.

Шаг 3. Добавление действия преобразования Liquid

Далее показано, как добавить действие преобразования Liquid для рабочих процессов приложений логики "Потребление" и "Стандартный".

Потребление

1. На портале Azure откройте рабочий процесс приложения логики в конструкторе, если он еще не открыт.

2. Если рабочий процесс не имеет требуемых триггера или каких-либо других действий, сначала добавьте эти операции. Операции Liquid не имеют доступных триггеров.

   Этот пример продолжается с триггером запроса с именем "При получении HTTP-запроса".

3. В конструкторе рабочего процесса в шаге, где вы хотите добавить действие Liquid, выберите Создать шаг.

4. Под полем поиска Choose an operation (Выберите действие) выберите вкладку Все. В поле поиска введите liquid.

5. В списке действий выберите действие Liquid, которое необходимо использовать.

   В этом примере продолжается использование действия под названием Преобразование JSON в JSON.

   

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

   1. Щелкните внутри поля Содержимое, чтобы отобразился список динамического содержимого.

   2. В списке динамического содержимого выберите данные JSON, которые требуется преобразовать.

      В этом примере в списке динамического содержимого в разделе При получении HTTP-запроса выберите токен Текст, который представляет выходные данные содержимого текста из триггера.

      

7. В списке Карта выберите шаблон Liquid.

   В этом примере продолжается работа с шаблоном JsonToJsonTemplate.

   

   Примечание.

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

   Когда все будет готово, действие будет выглядеть следующим образом:

   

8. Сохраните результаты своих действий. На панели инструментов конструктора выберите Сохранить.

Стандартные

1. На портале Azure откройте рабочий процесс приложения логики в конструкторе, если он еще не открыт.

2. Если рабочий процесс не имеет требуемых триггера или каких-либо других действий, сначала добавьте эти операции. Операции Liquid не имеют доступных триггеров.

   Этот пример продолжается с триггером запроса с именем "При получении HTTP-запроса".

3. В конструкторе в шаге, в котором нужно добавить действие Liquid, выберите знак "плюс" (+), а затем нажмите кнопку Добавить действие.

4. В открывшейся области Добавление действия в поле поиска выберите Встроенные.

5. В поле поиска введите liquid. В списке действий выберите действие Liquid, которое необходимо использовать.

   В этом примере продолжается использование действия под названием Преобразование JSON в JSON.

   

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

   1. Щелкните внутри поля Содержимое, чтобы отобразился список динамического содержимого.

   2. В списке динамического содержимого выберите данные JSON, которые требуется преобразовать.

      В этом примере в списке динамического содержимого в разделе При получении HTTP-запроса выберите токен Текст, который представляет выходные данные содержимого текста из триггера.

      

   Примечание.

   Если свойство Текст не отображается в списке динамического содержимого, выберите Дополнительные сведения рядом с заголовком раздела При получении HTTP-запроса. Кроме того, можно ввести содержимое для декодирования непосредственно в поле Содержимое.

7. В списке Источник выберите либо LogicApp, либо IntegrationAccount в качестве источника шаблона Liquid.

   В этом примере снова выбирается IntegrationAccount.

   

8. В списке Имя выберите шаблон Liquid.

   В этом примере продолжается работа с шаблоном JsonToJsonTemplate.

   

   Примечание.

   Если список сопоставлений пуст, скорее всего, ресурс приложения логики не связан с учетной записью интеграции. Обязательно свяжите ресурс приложения логики с учетной записью интеграции, в которой имеется шаблон Liquid или карта.

   Когда все будет готово, действие будет выглядеть следующим образом:

   

9. Сохраните результаты своих действий. На панели инструментов конструктора выберите Сохранить.

Тестирование рабочего процесса

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

1. В триггере запроса найдите свойство URL-адреса HTTP POST и скопируйте URL-адрес.

2. Откройте средство HTTP-запроса и используйте его инструкции для отправки HTTP-запроса на скопированный URL-адрес, включая метод, который ожидает триггер запроса .

   В этом примере используется POST метод с URL-адресом.

3. Включите входные данные JSON для преобразования, например:

   {
      "devices": "Surface, Mobile, Desktop computer, Monitors",
      "firstName": "Dean",
      "lastName": "Ledet",
      "phone": "(111)0001111"
   }
   

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

   

Другие преобразования Liquid

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

• JSON в текст
• XML в JSON
• XML в текст

Преобразование JSON в текст.

В следующем шаблоне Liquid показан пример для преобразования JSON в текст:

{{content.firstName | Append: ' ' | Append: content.lastName}}

В следующем примере показаны примеры входных и выходных данных:

Преобразование XML в JSON.

В следующем шаблоне Liquid показан пример для преобразования XML в JSON:

[{% JSONArrayFor item in content -%}
      {{item}}
  {% endJSONArrayFor -%}]

Цикл JSONArrayFor представляет собой пользовательский циклический механизм для входных данных XML, что позволяет создавать полезные данные JSON, избегая конечной запятой. Кроме того, условие where для этого пользовательского циклического механизма для сравнения использует имя XML-элемента, а не значение элемента, как другие фильтры Liquid. Дополнительные сведения см. в статье Подробный обзор политики Set-Body. Коллекции объектов.

В следующем примере показаны примеры входных и выходных данных:

Преобразование XML в текст.

В следующем шаблоне Liquid показан пример для преобразования XML в текст:

{{content.firstName | Append: ' ' | Append: content.lastName}}

В следующем примере показаны примеры входных и выходных данных:

Рекомендации по использованию шаблонов Liquid

• Шаблоны Liquid соответствуют предельным размерам файлов для сопоставлений в Azure Logic Apps.

• Действие Преобразование JSON в JSON соответствует реализации DotLiquid для Liquid. Эта реализация портирована на платформу .NET из реализации Shopify для Liquid и отличается в отдельных случаях.

  В следующем списке описаны известные отличия:

  • Действие Преобразование JSON в JSON по умолчанию выводит строку, которая может включать в себя JSON, XML, HTML и т. д. Действие Liquid указывает только на то, что ожидаемые текстовые выходные данные из шаблона Liquid являются строкой JSON. Это действие дает приложению логики указание выполнить синтаксический анализ входных данных в виде объекта JSON и применяет программу-оболочку, чтобы Liquid смог интерпретировать структуру JSON. После преобразования действие указывает приложению логики выполнить синтаксический анализ текстовых выходных данных из Liquid обратно в JSON.

    По умолчанию DotLiquid не понимает формат JSON, поэтому убедитесь, что вы избегаете употребления обратной косой черты (\) и других зарезервированные символов JSON.

  • Если шаблон использует фильтры Liquid, убедитесь в соблюдении соглашений об именовании DotLiquid и C#, в которых используется регистр предложений. Для всех преобразований Liquid убедитесь, что имена фильтров в шаблоне также используют регистр предложений. В противном случае фильтры не будут работать.

    Например, при использовании фильтра replace используйте Replace, а не replace. То же правило применяется при попытке использовать примеры в DotLiquid Online. Дополнительные сведения см. в разделах Фильтры Liquid Shopify и Фильтры Liquid DotLiquid. Спецификация Shopify включает примеры для каждого фильтра, поэтому для сравнения можно попробовать эти примеры на странице DotLiquid — попробовать в режиме онлайн.

  • Фильтр json из фильтров расширений Shopify в настоящее время не реализован в DotLiquid. Как правило, этот фильтр можно использовать для подготовки текстовых выходных данных для синтаксического анализа строк JSON, но вместо этого необходимо использовать фильтр Replace.

  • Стандартный фильтр Replace в реализации DotLiquid использует сопоставление регулярных выражений (RegEx), а реализация Shopify использует сопоставление простых строк. Обе реализации работают одинаково, пока вы не используете символ, зарезервированный регулярным выражением, или escape-символ в параметре сопоставления.

    Например, чтобы избежать употребления зарезервированного регулярным выражением escape-символа обратной косой черты (\), используйте | Replace: '\\', '\\', а не | Replace: '\', '\\'. В этих примерах показано различное поведение фильтра Replace при попытке избежать употребления символа обратной косой черты. Следующая версия успешно работает:

    { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\\', '\\' | Replace: '"', '\"'}}"}

    И в результате получается следующее:

    { "SampleText": "The quick brown fox \"jumped\" over the sleeping dog\\\\"}

    Следующая версия приводит к сбою:

    { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\', '\\' | Replace: '"', '\"'}}"}

    Возникает следующая ошибка:

    { "SampleText": "Liquid error: parsing "\" - Illegal \ at end of pattern."}

    Дополнительные сведения см. в разделе Замена стандартного фильтра с использованием сопоставления шаблона регулярного выражения....

  • Фильтр Sort в реализации DotLiquid сортирует элементы в массиве или коллекции по свойству, но со следующими отличиями:

    • Соответствует реакции на событие sort_natural Shopify, а не реакции на событие sort Shopify.

    • Выполняет сортировку только в строковом буквенно-цифровом порядке. Дополнительные сведения см. на странице Цифровая сортировка.

    • Использует порядок без учета регистра, а не порядок с учетом регистра. Дополнительные сведения см. на странице Фильтр сортировки не соответствует реакции на событие из спецификации Shopify.

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

• Язык и примеры Liquid Shopify
• DotLiquid
• DotLiquid — попробовать в режиме онлайн
• DotLiquid на GitHub
• Проблемы DotLiquid на GitHub
• Дополнительные сведения о сопоставлениях