Действие «Запустить JavaScript» для Workflows

Действие «Запустить JavaScript» для Workflows

Действие Запустить JavaScript позволяет добавить пользовательскую логику в Workflow. Используйте его для вызова API Ключ-АСТРОМ или внешних сервисов, а также для преобразования и обогащения данных между задачами. Скрипты выполняются в среде выполнения JavaScript Ключ-АСТРОМ со встроенным доступом к контексту Workflow, результатам предыдущих задач и значениям элементов цикла без использования выражений Jinja.

Требования и ограничения

Среда выполнения JavaScript накладывает общие ограничения на функции, включая 120-секундный тайм-аут и лимит оперативной памяти в 256 МБ. К задачам Workflow применяются следующие дополнительные ограничения:

• Размер результата задачи ограничен 6 МБ.
• Задачи JavaScript выполняются без контекста приложения. Для доступа к секретам Credential Vault требуются определённые настройки учётных данных. Подробности см. в разделе «Секреты Credential Vault».
• Некоторые пакеты SDK Ключ-АСТРОМ, например @astromkey-sdk/platform/app-environment и @astromkey-sdk/navigation, требуют контекста приложения или браузера и недоступны в среде выполнения JavaScript для Workflow. Для получения URL текущего тенанта используйте относительный запрос (fetch("/api/v2/...")) вместо SDK платформы.

Действие «Запустить JavaScript»

Входные данные

• Script: код JavaScript для выполнения.
• sdkMajorVersions: имена пакетов SDK Ключ-АСТРОМ и выбранная основная версия.

Результат

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

Лучшие практики для действия «Запустить JavaScript»

В следующих разделах описано, как создавать эффективные и безопасные действия JavaScript: структурирование скрипта, доступ к контексту Workflow и результатам предыдущих задач, передача данных последующим задачам, выполнение HTTP-запросов, использование секретов Credential Vault, импорт сторонних библиотек и фиксация версий SDK.

Написание скрипта

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

export default async function () {
  // ваша логика здесь
  return {
    myValue: 42
  };
}

Намеренный сбой задачи

Чтобы намеренно провалить задачу «Запустить JavaScript», выбросьте необработанное исключение:

export default async function() {
  throw new Error();
}

Доступ к контексту Workflow

Идентификаторы выполнения

Среда выполнения внедряет идентификаторы Workflow и задачи в параметры функции:

export default async function ({ executionId, actionExecutionId }) {
  console.log('Workflow execution id: ', executionId);
  console.log('Action execution id: ', actionExecutionId);
}

Вы также можете импортировать эти значения из пакета @astromkey-sdk/automation-utils:

import { actionExecutionId, executionId, taskName, workflowId } from '@astromkey-sdk/automation-utils';
export default async function () {

 console.log(`Running action execution '${actionExecutionId}' for task '${taskName}' of workflow '${workflowId}' in workflow execution '${executionId}'`);

}

Доступные свойства контекста:

• workflowId: ID выполненного Workflow.
• executionId: ID связанного выполнения Workflow.
• actionExecutionId: ID текущего выполнения действия.
• taskName: имя задачи в выполнении Workflow.

Результаты предыдущих задач

Используйте SDK automation-utils для краткого получения результата задачи-предшественника:

import { result } from '@astromkey-sdk/automation-utils';

export default async function () {
  const myResult = await result('my_task');
  console.log('The whole result object: ', myResult);
  console.log('Only one variable: ', myResult.myVariable);
}

Для полного доступа к Automation API используйте SDK client-automation:

import { executionsClient } from '@astromkey-sdk/client-automation';
export default async function ({ executionId }) {

 const config = { executionId, id: 'my_task' };
 const myResult = await executionsClient.getTaskExecutionResult(config);
 console.log('My task result: ', myResult);
 console.log('Only one variable: ', myResult.myVariable);

}

Текущий элемент цикла

Когда задача настроена на цикл, используйте loopItemValue для доступа к значению текущей итерации:

export default async function ({ loopItemValue }) {
  console.log(loopItemValue);
}

Полезная нагрузка событийного триггера

Для Workflow, запускаемых событием, получите полезную нагрузку события из выполнения:

import { execution } from '@astromkey-sdk/automation-utils';

export default async function () {
  const ex = await execution();
  console.log(ex.params.event);
  // ваш код здесь
}

Передача вывода последующим задачам

Возвращаемое значение задачи JavaScript доступно в последующих задачах с помощью выражений Jinja. Используйте {{ result("task_name")["property"] }} для ссылки на конкретное свойство из вывода задачи. Если ваша задача JavaScript возвращает объект:

export default async function () {
  return {
    newJobs: ["job1", "job2"],
    count: 2
  };
}

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

• {{ result("run_javascript_1")["newJobs"] }}: весь массив.
• {{ result("run_javascript_1")["count"] }}: конкретное свойство.
• {{ result("run_javascript_1")["newJobs"] | default([]) }}: с запасным значением, когда свойство отсутствует.

Чтобы проверить доступные выходные данные перед запуском Workflow, используйте предварительный просмотр выражения в редакторе задач. Введите выражение и выберите Preview, чтобы вычислить его по последнему результату задачи. Задача может ссылаться только на выходные данные своих непосредственных предшественников в графе Workflow. Если задача-производитель не является непосредственным предшественником, выражение разрешается в Undefined во время выполнения.

Выполнение HTTP-запросов

Используйте Fetch API для вызова API Ключ-АСТРОМ или внешних конечных точек из задачи JavaScript.

Относительные URL (API Ключ-АСТРОМ): Используйте относительные пути, например /api/v2/entities, для вызова API Ключ-АСТРОМ. Среда выполнения автоматически добавляет необходимые заголовки аутентификации. Не устанавливайте пользовательский заголовок Authorization для запросов с относительными URL. Среда выполнения перезаписывает его, что приводит к ошибке 403.

Абсолютные URL (внешние конечные точки): Используйте полный URL и предоставьте собственный bearer-токен или API-ключ. Внешняя конечная точка должна быть добавлена в раздел «Внешние запросы». Внешние запросы включают исходящие сетевые подключения из вашей среды Ключ-АСТРОМ к внешним сервисам. Они позволяют управлять доступом к публичным конечным точкам из AppEngine с помощью функций приложений и функций в Дашбордах, Блокнотах и Автоматизациях. Перейдите в Настройки > Общие > Внешние запросы. Выберите Новый шаблон хоста. Добавьте доменные имена. Выберите Добавить. Таким образом можно детально управлять веб-сервисами, к которым могут подключаться ваши функции.

Секреты Credential Vault

Чтобы использовать секрет Credential Vault в скрипте, например в качестве API-ключа в HTTP-запросе, получите его с помощью credentialVaultClient и используйте напрямую, не сохраняя в результате задачи.

import { credentialVaultClient } from '@astromkey-sdk/client-classic-environment-v2';

export default async function () {
  const credential = await credentialVaultClient.getCredentialsDetails({ id: 'CREDENTIALS_VAULT-XXXXXXXXXXXXXXXX' });
  const token = credential.token;
  const response = await fetch('https://example.com/api/resource', {
    method: 'GET',
    headers: {
      'X-API-Key': token
    },
  });
  // Не включайте токен или другие учётные данные в результат задачи —
  // результаты выполнения видны всем, у кого есть доступ на чтение к Workflow.
  return response.json();
}

Требуются следующие настройки учётных данных:

• Выбрана область действия AppEngine.
• Включена опция «Разрешить доступ без контекста приложения».
• Актор Workflow имеет доступ к учётным данным.

Импорт сторонних библиотек

Чтобы использовать стороннюю библиотеку, импортируйте её через URL. Применяются ограничения:

• Модули JavaScript должны быть допустимыми модулями ECMAScript. Они выполняются в контексте среды выполнения JavaScript Ключ-АСТРОМ и соответствующей совместимости.
• Можно загружать только модули из URL, внесённых в список разрешённых. Вам нужно добавить их в раздел «Внешние запросы». Внешние запросы включают исходящие сетевые подключения из вашей среды Ключ-АСТРОМ к внешним сервисам. Перейдите в Настройки > Общие > Внешние запросы. Выберите Новый шаблон хоста. Добавьте доменные имена. Выберите Добавить.
• Импорты не могут превышать 6 МБ в размере (суммарно).

Пример — использование библиотеки XMLJSON для разбора XML-ввода

Если ваш бэкенд создаёт устаревший вывод XML, но вам нужно обрабатывать данные как JSON, используйте библиотеку, например XML2JSON, вместо написания собственного парсера. Добавьте URL библиотеки XMLJSON в разрешённые «Внешние запросы». Добавьте фрагмент, подобный следующему, в ваше действие JavaScript для разбора XML и преобразования его в JSON.

// Загрузка XML-парсера из ESM
import xml2js from "https://esm.sh/xml2js@0.6.2";

export default async function() {
  // Фиктивный XML, можно получить из вашего бэкенда
  const xml = "<root><message>Hello World</message></root>";
  const parser = new xml2js.Parser();
  const json = await parser.parseStringPromise(xml);
  return json;
}

Обратите внимание, что некоторые библиотеки зависят от встроенных модулей Node.js — таких как net, tls, fs или crypto — которые среда выполнения JavaScript Ключ-АСТРОМ не предоставляет. Библиотеки, требующие низкоуровневого доступа к сокетам или файловой системе (например, клиенты Kafka, такие как KafkaJS), не загрузятся. Полные сведения о совместимости см. в документации по среде выполнения JavaScript.

Фиксация версий SDK Ключ-АСТРОМ

В действии «Запустить JavaScript» вы можете зафиксировать каждый пакет SDK Ключ-АСТРОМ на определённой основной версии, чтобы контролировать, когда ваше действие принимает критические изменения. Минорные обновления и обновления патчей в пределах выбранной основной версии применяются автоматически. Раздел «Версии SDK Ключ-АСТРОМ» в редакторе задач показывает каждый доступный пакет и его текущую выбранную основную версию. Фиксация влияет только на версию пакетов, которые вы импортируете напрямую. Если у импортированного пакета есть собственные зависимости, они разрешаются в соответствии с собственным определением зависимостей пакета. Когда вы добавляете новую задачу «Запустить JavaScript», по умолчанию выбирается последняя основная версия SDK. Задачи, созданные до появления этой функции или в которых опущен входной параметр sdkMajorVersions, по умолчанию используют самую старую доступную основную версию. Когда вы открываете такую задачу, редактор показывает предупреждение. Выберите Настроить версии пакетов, чтобы загрузить доступные версии и явно задать их. Чтобы обновить или откатить пакет SDK:

• Откройте задачу в редакторе.
• Разверните Версии SDK Ключ-АСТРОМ.
• Выберите нужную основную версию из раскрывающегося списка для каждого пакета.

Задачи, для которых доступна более новая основная версия, показывают подсказку «Доступна новая основная версия».

Безопасность

• Действие «Запустить JavaScript» не поддерживает выражения в своих входных данных, чтобы избежать возможности внедрения кода.
• Все HTTP-вызовы проверяются по глобальному списку разрешённых.
• Если вы импортируете сторонние библиотеки, домены CDN из списка разрешённых предоставляют доступ ко всему портфелю пакетов. Среда выполнения JavaScript Ключ-АСТРОМ устойчива к определённым векторам атак, но вы можете случайно разрешить вредоносный код. Зеркалируйте зависимости в вашей внутренней инфраструктуре и отслеживайте их последствия для безопасности с помощью Application Security Ключ-АСТРОМ или сторонних инструментов, таких как Snyk.
• Не возвращайте секреты как часть результата задачи. Результаты выполнения видны всем, у кого есть доступ на чтение к Workflow.