Airflow API позволяет внешней системе создать запуск ИИ-DAG через публичный REST API v2 и затем запросить состояние этого запуска. Рабочая схема связывает событие источника с постоянным идентификатором запроса, правом на конкретный DAG и записью результата во внешнем журнале. Такой маршрут подходит для системы, которая сама инициирует обработку и должна отличать новый запуск от повторной доставки одного события.
Граница внешнего вызова
Официальный справочник Airflow описывает публичный REST API v2: создание DAG run выполняется запросом POST к ресурсу запусков, чтение конкретного запуска — запросом GET по его идентификатору.
Представьте внутреннюю систему, которая передаёт подтверждённое событие на обработку текста. Внешний клиент вызывает публичный API server Airflow, получает сведения о созданном DAG run и сохраняет связь с исходным событием. Затем клиент читает состояние этого запуска и передаёт итог ответственному процессу. Сама логика обработки остаётся внутри DAG: подготовка разрешённых данных, обращение к модели, разбор ответа и проверка условий выпуска результата.
Это отдельная граница интеграции. TriggerDagRunOperator запускает другой DAG из уже выполняемого DAG, тогда как здесь инициатор находится за пределами Airflow. Клиенту нужны сетевой доступ к публичному API, собственная учётная запись и разрешение на операции с конкретным DAG run. Внутренний оператор подходит для связей между DAG; внешний API нужен CRM, сервису заявок или другому приложению с собственным жизненным циклом события. Смешение маршрутов затрудняет поиск источника повторного запуска.
Заранее договоритесь, какое событие запускает конвейер и кто владеет решением о повторе. Для системы заявок таким событием может служить подтверждённый переход записи в согласованный статус. Полный текст обращения и персональные сведения лучше оставлять в разрешённом хранилище, а в параметрах запуска передавать ссылку или ключ доступа по правилам компании. Регулярный контроль аналитики разбирает содержимое обработки; здесь важен договор между внешним инициатором и Airflow.
Контракт запуска
Для каждого входящего события клиент формирует постоянный ключ операции и связывает его с dag_run_id. Правило формирования ключа задают до пилота: одинаковое событие должно вести к одному идентификатору, новое согласованное событие — к новому. Такую связь проектирует внешнее приложение; её устойчивость проверяют в пилоте. Сохраните также dag_id, исходный идентификатор события и версию схемы параметров. Так при расследовании будет видно, какой запрос породил конкретный запуск.
| Событие клиента | Действие | Что сохранять |
|---|---|---|
| Новый подтверждённый запрос | POST к запускам разрешённого DAG | Исходный ключ, dag_id, dag_run_id, ответ API |
| Неясный исход POST | GET конкретного DAG run до решения о повторе | Код ответа, признак найденного запуска, следующее действие |
| Конфликт идентификатора | Сверка существующего запуска с исходным событием | Связь ключа клиента с уже известным run_id |
| Запрос состояния | GET по dag_id и dag_run_id | Состояние, момент опроса, итог маршрута |
Справочник публичного API перечисляет dag_run_id в теле создания запуска и ответ Conflict среди возможных исходов POST. Поэтому при конфликте клиент проверяет известный идентификатор через GET и сверяет его со своей записью. При сетевом обрыве после отправки запрос мог уже создать запуск: слепой повтор способен дать спорный результат. Сначала выясните состояние по постоянному идентификатору, затем принимайте решение согласно политике повтора. Код HTTP, ответ сервера и состояние DAG run имеют разные значения; храните их раздельно.
Параметры conf ограничьте заранее утверждённой схемой. Серверное приложение проверяет типы, допустимые значения и размер входа до вызова Airflow. Для полных выгрузок используйте парсер или скрипт в отдельном контуре; языковая модель объясняет найденные отклонения и предлагает гипотезы, человек сверяет их с исходными данными. Такой договор уменьшает вероятность передачи лишнего содержимого через параметры запуска.
Права клиента
Публичный API Airflow использует аутентификацию клиента. Документация по доступу к API описывает JWT для запросов, а конкретный способ выдачи токена зависит от настроенного auth manager. Секрет хранится в принятом компанией хранилище учётных данных и исключается из текста задач, примеров и журналов. Клиент контролирует срок действия токена и порядок его обновления по настройкам собственного контура; после успешного входа сервер отдельно проверяет право на конкретный DAG run.
- Создайте отдельную учётную запись внешнего клиента в тестовом контуре. Назначьте ей доступ к чтению нужного DAG run и к созданию запуска только для согласованного DAG.
- Проверьте положительный вызов с тестовым событием и сохраните идентификатор запуска вместе с ключом внешней операции.
- Проверьте отказ при попытке обратиться к постороннему DAG. Сервер Airflow должен отклонить действие согласно разрешениям настроенного auth manager.
- После отправки запросите состояние того же DAG run через GET. Сравните ответ с журналом внешнего клиента и записью в Airflow.
- Отзовите доступ тестового клиента и убедитесь, что следующий запрос завершается отказом. Зафиксируйте владельца учётной записи и порядок её ротации.
Таблица разрешений Airflow связывает операции создания и чтения DAG run с отдельными правами, которые применяет настроенный auth manager. Права и подтверждения проверяет сервер на каждом запросе; формулировка промпта лишь помогает пользователю описать намерение. Если ИИ-компонент предлагает внешний запуск, приложение дополнительно проверяет разрешённый источник события и правило подтверждения. Требуемая степень согласования зависит от риска действия и задаётся владельцем процесса.
Нужен проверяемый внешний запуск для вашего DAG?
Отказ и аудит
Состояние вызова API и состояние задания расходятся во времени. Успешный ответ на создание говорит о принятии запроса сервером, а завершение DAG подтверждает последующее чтение состояния. Клиент должен хранить промежуточный статус и показывать ответственному человеку, какое событие ещё ожидает итог. Если выполняется дальнейшее бизнес-действие, запускайте его только по утверждённому правилу после проверки результата. Для этого правила требуется подтверждённый итог DAG, одного HTTP-ответа недостаточно.
Продумайте разные виды отказа: ошибки авторизации, отсутствие DAG, конфликт идентификатора, сетевой разрыв, отказ задачи внутри DAG и несовпадение результата с требованиями процесса. Для каждого случая укажите владельца разбора и допустимость повтора. Ошибку доступа исправляет администратор прав; сбой выполнения изучает владелец DAG; смысл ответа модели оценивает профильный специалист. При повторном событии приложение сверяет сохранённую связь с run_id и сохраняет прежний маршрут без нового внешнего действия до решения ответственного.
Журнал внешнего клиента может содержать идентификатор события, dag_id, dag_run_id, тип операции, код ответа, итоговое состояние и идентификатор ответственного решения. Сырые промпты, ключи, токены и личные данные в такой журнал писать нельзя. Для полной проверки выгрузите записи скриптом, сопоставьте их по постоянным ключам и выделите расхождения. Модель помогает описать возможные причины, инженер сверяет каждую гипотезу с ответом API и журналом Airflow. Сценарии проверки ИИ-агентов расширяют тему отказов; в этой интеграции ключевой след ведёт от события внешней системы к конкретному DAG run.
Аудит полезен лишь при ясной связи между событием, разрешением и результатом. Проверяйте эту цепочку на тестовых данных и фиксируйте пропуски как дефекты интеграции и передавайте ответственному для решения о повторе.
Пилот и решение
Для будущего пилота предложите изолированный Airflow и обезличенный набор событий внешнего приложения. Подготовьте эталон: новое событие создаёт один узнаваемый запуск, повтор обращается к прежнему run_id, посторонний DAG остаётся закрытым, ошибка выполнения видна в статусе и журнале. Затем предложите команде пройти маршрут вызова и вручную сверить каждый переход с исходным событием. Эти критерии задают будущую проверку; фактические результаты появятся после пилота.
Критерий принятия интеграции включает сохранённую связь исходного события с DAG run, раздельный учёт ответа HTTP и состояния задания, отказ при отсутствии права и понятную процедуру разбора конфликта. Если тест выявит неоднозначность после сетевого обрыва, уточните ключ операции и порядок проверки существующего запуска. Если ИИ-DAG создаёт внешний результат, добавьте проверку повторяемости действия на уровне целевой системы. Владелец процесса утверждает выпуск результата по фактам, полученным из проверяемого маршрута.
Состав проекта и стоимость зависят от источника события, схемы параметров, способа выдачи доступа, требований к журналу и проверки повторов. Смету разумно обсуждать после согласования контракта вызова и критериев приёмки, без переноса чужих тарифных цифр. Команда может проработать такой контур в рамках автоматизации бизнес-процессов. Для предметного обсуждения пригодятся схема события, перечень разрешённых DAG и правила обработки отказа.