Apache Airflow зарекомендовал себя как ведущая платформа для оркестрации рабочих процессов, позволяющая эффективно управлять сложными последовательностями задач. Однако для достижения по-настоящему безупречной автоматизации и бесшовной интеграции с внешними системами одного лишь веб-интерфейса или CLI бывает недостаточно. Именно здесь на помощь приходит REST API Airflow – мощный инструмент, открывающий двери к программному взаимодействию с платформой. В этой статье мы раскроем все аспекты работы с REST API, его возможности, методы аутентификации и практические примеры использования, чтобы вы могли поднять автоматизацию Airflow на новый уровень.
Что такое REST API в Apache Airflow?
REST API в Apache Airflow представляет собой мощный программный интерфейс, позволяющий взаимодействовать с планировщиком и его компонентами. Это основной инструмент для автоматизации внешних систем и глубокой интеграции, предоставляющий возможность удаленно запускать DAG’и, контролировать их выполнение, управлять задачами и получать метаданные.
Существуют две основные версии API:
-
REST API v1: Более ранняя версия, которая уже не рекомендуется к использованию.
-
REST API v2: Соответствует спецификации OpenAPI, предоставляет значительно более полный набор эндпоинтов и считается стандартом для современных интеграций.
Обзор возможностей REST API
REST API в Apache Airflow – это мощный интерфейс, открывающий двери для глубокой автоматизации и интеграции. Он позволяет программно взаимодействовать с вашим окружением Airflow, выполнять широкий спектр операций, включая:
-
Управление DAG’ами: запуск, остановка, просмотр статуса, получение информации о запусках.
-
Управление задачами: мониторинг выполнения, получение логов, изменение состояния.
-
Администрирование: управление переменными (Variables), соединениями (Connections), пулами (Pools) и пользователями.
Эти возможности делают API незаменимым инструментом для построения комплексных решений, где Airflow выступает центральным оркестратором, интегрированным с внешними системами.
Ключевые отличия REST API v1 и v2
Хотя REST API v1 еще встречается в старых развертываниях, основное внимание следует уделять v2. API v1 был экспериментальным и имел ограниченный набор эндпоинтов, часто не соответствовал стандартам RESTful, что приводило к менее предсказуемому поведению.
REST API v2, напротив, является стабильным и рекомендованным для использования в продакшене. Он полностью соответствует спецификации OpenAPI (ранее Swagger), предлагая:
-
Расширенный функционал: Значительно больше эндпоинтов для детального управления и мониторинга.
-
Улучшенную согласованность: Единый подход к именованию и обработке ошибок.
-
Лучшую документацию: Автоматически генерируемую и легкодоступную, что упрощает интеграцию.
Аутентификация и авторизация в Airflow REST API
Для безопасного взаимодействия с Airflow REST API необходимо правильно настроить аутентификацию и авторизацию. Airflow v2 предлагает более надёжные методы по сравнению с v1.
Основными методами являются:
-
Токен-аутентификация (API Tokens): Рекомендуемый метод для REST API v2. Пользователи могут генерировать токены через UI или API, которые затем используются в заголовке
Authorization: Bearer <token>. Это обеспечивает гибкое и безопасное управление доступом без передачи учётных данных. -
Базовая аутентификация (Basic Auth): Поддерживается как в v1, так и в v2 (если включена). Требует отправки имени пользователя и пароля в кодировке Base64 в заголовке
Authorization: Basic <base64_encoded_credentials>.
После успешной аутентификации, авторизация контролируется системой RBAC (Role-Based Access Control) Airflow. Ваши права доступа к DAG’ам и функциям API зависят от ролей, назначенных вашей учётной записи.
Методы аутентификации (Token, Basic Auth)
Для аутентификации в Airflow REST API доступны несколько методов. В v2 рекомендуется использовать токены. Сгенерированный токен необходимо передавать в заголовке Authorization: Bearer <ваш_токен>. Это наиболее безопасный способ.
В v1 поддерживается базовая аутентификация (Basic Auth), когда в заголовке Authorization передается строка username:password, закодированная в Base64. Однако этот метод менее безопасен, поэтому рекомендуется использовать токены, если это возможно.
При использовании любого метода аутентификации, необходимо учитывать настройки безопасности Airflow и права доступа пользователя. Управление правами доступа осуществляется через систему RBAC Airflow.
Управление доступом и ролями через API
Airflow использует модель контроля доступа на основе ролей (RBAC) для обеспечения гранулированного управления разрешениями. REST API полностью интегрирован с этой системой, позволяя программно управлять пользователями, ролями и их разрешениями. Администраторы могут создавать и изменять пользователей, назначать им существующие роли или определять новые, более специализированные разрешения для доступа к определенным ресурсам, таким как DAG’и, соединения или переменные. Это обеспечивает гибкий и безопасный подход к автоматизации управления доступом в Airflow.
Основные эндпоинты и примеры использования
Освоив аутентификацию и авторизацию, перейдем к практическому применению REST API для управления рабочими процессами. Airflow предоставляет мощные эндпоинты для взаимодействия с DAG’ами и задачами. Рассмотрим основные из них:
-
Управление DAG’ами: Вы можете программно запускать DAG-раны (
POST /dags/{dag_id}/dagRuns), получать статус (GET /dags/{dag_id}/dagRuns), приостанавливать (POST /dags/{dag_id}/clearDagRuns) или активировать DAG’и. -
Управление задачами: REST API позволяет получать логи задач (
GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/logs), проверять их статус (GET /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}) и даже перезапускать определенные экземпляры задач (POST /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/clear).
Управление DAG’ами: запуск, остановка, получение статуса
Запуск DAG’а осуществляется с помощью эндпоинта POST /dags/{dag_id}/dagRuns. Для этого необходимо передать полезную нагрузку JSON, включающую logical_date (или execution_date для v1 API) и опциональные параметры conf, которые будут доступны внутри DAG.
Вы можете приостановить или возобновить работу DAG’а, отправив PATCH-запрос на /dags/{dag_id} с полем {"is_paused": true} или {"is_paused": false} в теле запроса. Это позволяет динамически управлять доступностью рабочих процессов.
Для получения детальной информации о конкретном DAG, его конфигурации или последних запусках используйте эндпоинты GET /dags/{dag_id} и GET /dags/{dag_id}/dagRuns соответственно. Они предоставляют статус, историю и метаданные.
Управление задачами: получение логов, статусов, перезапуск
После контроля над DAG’ами, следующим логичным шагом является управление отдельными задачами. Airflow REST API позволяет детально отслеживать их выполнение и вмешиваться в процесс.
-
Получение статуса задачи: Для получения текущего статуса конкретной задачи в рамках определенного запуска DAG используется эндпоинт
/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}. Это позволяет программно отслеживать ход выполнения. -
Получение логов задачи: Доступ к логам выполнения задачи критически важен для отладки. Эндпоинт
/dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/logs/{log_id}предоставляет полный набор логов. -
Перезапуск задачи: В случае сбоя или необходимости повторного выполнения, можно очистить состояние задачи. Для этого применяется
POST /dags/{dag_id}/dagRuns/{dag_run_id}/taskInstances/{task_id}/clear, что по сути инициирует её перезапуск при следующем планировании.
Интеграция Airflow REST API с внешними инструментами
Интеграция Airflow REST API с внешними инструментами открывает широкие возможности для автоматизации и взаимодействия. Для программного доступа из Python-скриптов обычно используется библиотека requests, позволяющая легко отправлять HTTP-запросы к эндпоинтам Airflow. Это идеально подходит для создания кастомных триггеров, мониторинга и управления DAG’ами из других приложений.
Postman и аналогичные клиенты (например, Insomnia) служат отличными инструментами для быстрого тестирования API, отладки запросов и ручного взаимодействия. Они упрощают понимание структуры API и ускоряют разработку интеграций.
Использование REST API из Python скриптов
Для программного взаимодействия с Airflow REST API из Python скриптов удобно использовать библиотеку requests. Она позволяет легко отправлять HTTP-запросы (GET, POST и т.д.) и обрабатывать JSON-ответы. Например, чтобы получить список DAG’ов, достаточно выполнить GET-запрос к эндпоинту /api/v1/dags, передав необходимые учетные данные для аутентификации (например, токен JWT или Basic Auth). Аналогично, запуск DAG реализуется POST-запросом к эндпоинту /api/v1/dags/{dag_id}/dagRuns с JSON-телом, содержащим желаемую конфигурацию. Такой подход предоставляет гибкие возможности для создания собственных утилит и интеграции с внешними системами.
Применение Postman и других клиентов для работы с API
Помимо программной интеграции с использованием Python, такие инструменты, как Postman или Insomnia, предоставляют удобный графический интерфейс для интерактивного тестирования и изучения Airflow REST API. Они позволяют легко отправлять HTTP-запросы (GET, POST и т.д.), настраивать заголовки, включая данные для аутентификации (например, Basic Auth или Bearer Token), и анализировать ответы сервера. Это особенно полезно для отладки, быстрого прототипирования и проверки доступных эндпоинтов перед внедрением в скрипты или приложения. Вы можете сохранять коллекции запросов, что значительно упрощает повторное использование и совместную работу.
Заключение
Итак, REST API Apache Airflow является мощным инструментом для программного управления вашими рабочими процессами. Он открывает двери для глубокой интеграции с внешними системами, позволяя автоматизировать запуск DAG’ов, мониторинг задач и управление метаданными с непревзойденной гибкостью. Освоение этого интерфейса значительно повышает эффективность вашей платформы данных, превращая Airflow в центральный узел для оркестрации сложных экосистем. REST API — это ключ к по-настоящему автоматизированному и масштабируемому управлению Airflow.