Requests в Adal

Обзор

Request — это один HTTP-запрос, полученный Adal Server. Каждый принятый вебхук становится отдельным Request, который можно изучить в разделе Requests и проследить через настроенные Destinations.

Adal сохраняет полученные HTTP-метод, URI, путь, строку запроса, заголовки и тело без скрытого преобразования содержимого. Request описывает, что получил Server; Delivery отслеживает отправку этого Request в один Destination. У одного Request может быть несколько независимых Deliveries с разными результатами.

Важно: Request подтверждает, что Adal принял вебхук. Успешный Delivery подтверждает, что Adal получил ожидаемый HTTP-ответ от Destination. Ни одно из этих событий не доказывает, что Destination завершил бизнес-операцию.

Жизненный цикл Request

1. Внешний сервис отправляет HTTP-запрос на URL Server.

2. Server проверяет метод, общий размер, доступные кредиты и другие правила приёма.

3. Каждый принятый вебхук становится Request в регионе Server и согласно текущей модели оплаты использует один кредит.

4. Adal создаёт независимый Delivery для каждого настроенного Destination.

5. Adal фиксирует каждую попытку и может запланировать автоматический повтор согласно конфигурации Destination.

6. Сохранённые данные Request и история доступны до запланированной даты удаления.

Server без Destinations всё равно может принимать Requests для просмотра, если выбранная конфигурация сохраняет их, но автоматические Deliveries не создаются. Отклонённый запрос не проходит этот цикл: у него нет Deliveries, а Adal сохраняет только минимальные диагностические данные.

Данные Request

Для принятого Request, сохраняемого выбранной конфигурацией, Adal хранит данные, необходимые для просмотра и Delivery:

• HTTP-метод;

• полный URI, путь и строку запроса;

• заголовки и тело;

• отдельные размеры URI, заголовков и тела, а также общий размер;

• IP-адрес отправителя;

• время получения и запланированную дату удаления;

• Server и регион, принявшие Request;

• статус Request и связанные Deliveries;

• технические идентификаторы, связывающие записи.

Общий размер, сравниваемый с применимым ограничением, рассчитывается так:

Версия HTTP не хранится как отдельное поле Request. Переданный User-Agent остаётся доступен в заголовках. В обзоре также показывается Content-Type, но он описывает лишь формат, заявленный отправителем, и не доказывает, что тело является корректным JSON, XML, набором полей формы, текстом или другим заявленным форматом.

Adal не дополняет Request бизнес-данными и не исправляет некорректное содержимое. Проверяйте формат и смысл в приложении Destination.

Принятые и отклонённые Requests

Принятый Request прошёл проверки Server и аккаунта. Adal может сохранить полный Request согласно выбранной конфигурации, использует один кредит и создаёт Deliveries для текущих Destinations Server.

Общий статус Request рассчитывается по всем связанным Deliveries:

Запрос может быть отклонён, если его метод отключён, общий размер превышает текущее ограничение, HTTP-сообщение некорректно, достигнуто ограничение аккаунта, недоступны кредиты или принимающая инфраструктура не может обработать запрос.

Для отклонённого Request Adal сохраняет только минимальную диагностическую информацию: метод, время получения, причину отклонения, а также необходимые технические идентификаторы или рассчитанные счётчики. URI, путь, строка запроса, заголовки, тело, заявленный тип содержимого, IP-адрес отправителя и данные Delivery не сохраняются.

У отклонённых Requests нет Deliveries, их нельзя отправить через replay, они не используют кредиты, а отброшенное содержимое невозможно восстановить позднее.

Просмотр Request

Откройте Requests и выберите запись. Страница разделяет полученные HTTP-данные, состояние Request и технические идентификаторы.

Full URI содержит путь и строку запроса, а Path — только путь. Значения после ? также разбираются в панели параметров запроса. Размеры URI, заголовков и тела показаны отдельно; Total size является их суммой.

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

Чувствительные данные: Заголовки, пути, параметры запроса и тело могут содержать токены, подписи, персональные данные и другие секреты. Не копируйте полный Request в обычные логи, аналитику, отчёты об ошибках, публичные задачи или обращения в поддержку.

Deliveries и история попыток

Сводка Delivery перечисляет все Deliveries, связанные с Request. Если Delivery не был создан, страница показывает пустое состояние; это ожидаемо, когда у Server нет Destinations или запрос был отклонён.

Каждый Delivery отслеживается независимо. Request остаётся в статусе delivering, пока хотя бы один маршрут активен. Когда все маршруты получают окончательный результат, общий статус становится success, partial или failed.

Любой ответ 2xx означает успешный Delivery. Ответы 4xx и 5xx, тайм-ауты и сетевые ошибки считаются неудачными и могут вызвать автоматический повтор согласно конфигурации Destination.

Подробности Delivery могут содержать:

• текущий статус и время создания;

• номер текущей или последней попытки;

• статус ответа или зафиксированную ошибку;

• продолжительность и время с момента получения Request;

• исходный Request и Destination;

• URL и метод Delivery;

• время и результат каждой попытки.

Adal не хранит заголовки или тело ответа Destination. Используйте результат, время и диагностические сведения вместе с собственными логами приложения Destination.

Ручной повтор снова отправляет существующий Request в один выбранный Destination. Он не создаёт новый Request и не влияет на другие маршруты. Согласно текущей модели оплаты ручной повтор использует один дополнительный кредит, автоматические повторы — нет.

Replay Request

Replay создаёт новый Request из сохранённого и снова отправляет его через текущий процесс Server.

• исходный Request не изменяется;

• новый Request хранится отдельно и ссылается на исходный;

• Adal использует Destinations, настроенные для Server в момент replay;

• новый Request получает собственные Deliveries и историю попыток;

• согласно текущей модели оплаты replay использует один кредит;

• replay доступен только пока необходимые исходные данные хранятся в Adal.

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

Дубликаты и идемпотентность

Автоматические и ручные повторы могут доставить один Request несколько раз. Replay создаёт новый Request в Adal, но он может представлять то же событие провайдера. Adal не предоставляет exactly-once delivery.

Destination можно настроить на получение заголовка идемпотентности Adal:

Deliveries и повторы одного Request используют одинаковый ключ Adal. Replay создаёт новый Request с новым ключом, поэтому один этот заголовок не позволяет обнаружить то же событие провайдера после replay.

Обработчики Destination должны:

• проверять подпись отправителя и валидировать все входные данные;

• быть идемпотентными;

• использовать стабильный идентификатор события провайдера для устранения дублей, если он доступен;

• сохранять идентификатор события атомарно с бизнес-операцией;

• возвращать 2xx только после принятия ответственности за обработку.

Retention и удаление

Принятые Requests хранятся ограниченное время, определяемое планом и конфигурацией Server. Retention начинается при приёме Request, а в его подробностях указывается запланированная дата удаления, если это применимо.

После окончания retention Adal безвозвратно удаляет сохранённое содержимое Request и связанные данные Delivery. Request больше нельзя просмотреть, восстановить, отправить вручную или через replay.

Удаление Server останавливает приём новых запросов и удаляет его Destinations. Ранее принятые Requests могут оставаться до индивидуальных запланированных дат удаления; удаление Server не превращает Adal в постоянное хранилище этих записей.

Важно: Используйте собственные базы данных, журналы приложения, резервные копии и механизмы восстановления для долгосрочного хранения бизнес-данных. Retention Requests в Adal является временным и зависит от плана.

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

Любой, кто знает публичный URL Server, может отправить на него запрос. Наличие Request и успешный Delivery не доказывают подлинность отправителя или безопасность содержимого.

• проверяйте подписи вебхуков согласно актуальной документации провайдера;

• разрешайте на Server только ожидаемые HTTP-методы;

• валидируйте структуру, типы, размеры, тип содержимого и допустимые значения;

• не считайте одни лишь заголовки или IP-адрес отправителя доказательством подлинности;

• обеспечивайте идемпотентность и учитывайте дубли событий;

• защищайте URL Server, доступ к панели управления, токены и учётные данные Destination;

• выбирайте подходящие регион и срок retention;

• не помещайте полные данные Request в обычные логи, аналитику, уведомления и отчёты об ошибках.

Некоторые схемы подписи требуют точного исходного тела. Если провайдер требует этого, проверяйте подпись по исходным байтам до разбора или повторной сериализации payload.

Adal шифрует чувствительные данные Requests при хранении и использует защищённые соединения при передаче, но не заменяет аутентификацию, авторизацию, валидацию и контроль доступа в вашем приложении.

Устранение неполадок

Request не появился в панели управления

Проверьте полный URL Server, журнал отправителя, существование Server, разрешённый метод, общий размер, кредиты и доступность региона. Также найдите отклонённую запись.

Request отклонён

Откройте запись и изучите причину. Сравните метод с конфигурацией Server и помните, что общий размер включает URI и заголовки вместе с телом. Исправьте причину и попросите провайдера повторить событие: отброшенное содержимое недоступно.

Request принят, но Delivery отсутствует

Убедитесь, что у Server есть Destination. Проверяйте каждый маршрут независимо: прямой HTTP-сервис может быть недоступен, а маршрут Adal CLI — ожидать подключения.

Тело отличается от ожидаемого

Сравните Content-Type, сохранённое тело, кодировку и документацию провайдера. Adal сохраняет полученные данные, но не гарантирует, что отправитель сформировал корректное содержимое заявленного формата.

Adal показывает успех, но операция не выполнена

Результат 2xx означает, что Adal получил ожидаемый HTTP-ответ. Проверьте состояние и логи приложения Destination: его внутренняя транзакция, очередь или последующая обработка всё ещё могут завершиться ошибкой.

Событие обработано дважды

Проверьте автоматические и ручные повторы, а также replay. Устраняйте дубли по стабильному идентификатору события провайдера. Ключ идемпотентности Adal позволяет распознать повторный Delivery одного Request, но меняется при создании нового Request через replay.

Связанные страницы

• Servers

• Основные понятия

• Destinations

• Повторные попытки Delivery

• Хранение данных и retention

• Adal CLI