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

2026-10-14T16:24:54Z

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

Новая страница

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

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

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

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

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

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

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

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

=== Написание скрипта ===
Каждый скрипт должен экспортировать асинхронную функцию по умолчанию. Среда выполнения вызывает эту функцию при выполнении задачи.<pre>export default async function () {
// ваша логика здесь
return {
myValue: 42
};
}</pre>

=== Намеренный сбой задачи ===
Чтобы намеренно провалить задачу «Запустить JavaScript», выбросьте необработанное исключение:<pre>export default async function() {
throw new Error();
}</pre>

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

==== Идентификаторы выполнения ====
Среда выполнения внедряет идентификаторы Workflow и задачи в параметры функции:<pre>export default async function ({ executionId, actionExecutionId }) {
console.log('Workflow execution id: ', executionId);
console.log('Action execution id: ', actionExecutionId);
}</pre>Вы также можете импортировать эти значения из пакета <code>@astromkey-sdk/automation-utils</code>:<pre>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}'`);
}</pre>Доступные свойства контекста:

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

==== Результаты предыдущих задач ====
Используйте SDK <code>automation-utils</code> для краткого получения результата задачи-предшественника:<pre>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);
}</pre>Для полного доступа к Automation API используйте SDK <code>client-automation</code>:<pre>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);
}</pre>

==== Текущий элемент цикла ====
Когда задача настроена на цикл, используйте <code>loopItemValue</code> для доступа к значению текущей итерации:<pre>export default async function ({ loopItemValue }) {
console.log(loopItemValue);
}</pre>

==== Полезная нагрузка событийного триггера ====
Для Workflow, запускаемых событием, получите полезную нагрузку события из выполнения:<pre>import { execution } from '@astromkey-sdk/automation-utils';

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

=== Передача вывода последующим задачам ===
Возвращаемое значение задачи JavaScript доступно в последующих задачах с помощью выражений Jinja. Используйте <code><nowiki>{{ result("task_name")["property"] }}</nowiki></code> для ссылки на конкретное свойство из вывода задачи. Если ваша задача JavaScript возвращает объект:<pre>export default async function () {
return {
newJobs: ["job1", "job2"],
count: 2
};
}</pre>Последующая задача может ссылаться на результат с помощью следующих выражений:

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

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

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

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

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

==== Секреты Credential Vault ====
Чтобы использовать секрет Credential Vault в скрипте, например в качестве API-ключа в HTTP-запросе, получите его с помощью <code>credentialVaultClient</code> и используйте напрямую, не сохраняя в результате задачи.<pre>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();
}</pre>Требуются следующие настройки учётных данных:

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

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

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

==== Пример — использование библиотеки XMLJSON для разбора XML-ввода ====
Если ваш бэкенд создаёт устаревший вывод XML, но вам нужно обрабатывать данные как JSON, используйте библиотеку, например XML2JSON, вместо написания собственного парсера. Добавьте URL библиотеки XMLJSON в разрешённые «Внешние запросы». Добавьте фрагмент, подобный следующему, в ваше действие JavaScript для разбора XML и преобразования его в JSON.<pre>// Загрузка 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;
}</pre>Обратите внимание, что некоторые библиотеки зависят от встроенных модулей Node.js — таких как <code>net</code>, <code>tls</code>, <code>fs</code> или <code>crypto</code> — которые среда выполнения JavaScript Ключ-АСТРОМ не предоставляет. Библиотеки, требующие низкоуровневого доступа к сокетам или файловой системе (например, клиенты Kafka, такие как KafkaJS), не загрузятся. Полные сведения о совместимости см. в документации по среде выполнения JavaScript.

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

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

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

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

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

Действие «Запустить JavaScript» для Workflows - История изменений