Запросы в Adal

Обзор

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

Adal сохраняет полученный HTTP-метод, URI, заголовки и тело без скрытого преобразования содержимого. Это позволяет увидеть, что действительно отправил источник, и доставить тот же запрос локальному или удалённому приложению.

Запрос и доставка — разные сущности. Запрос описывает то, что принял сервер, а доставка — отдельную попытку передать сохранённый запрос конкретному получателю. Один запрос может иметь несколько независимых доставок с разными результатами.

Жизненный цикл запроса

1. Внешний сервис отправляет HTTP-запрос на URL сервера Adal.
2. Сервер проверяет метод, размер, доступные кредиты и другие условия приёма.
3. Принятый запрос сохраняется в выбранном регионе и расходует 1 кредит.
4. Для каждого настроенного получателя создаётся независимая доставка.
5. Adal фиксирует результат каждой попытки и при необходимости планирует автоматический повтор.
6. Запрос и связанная история доступны до индивидуальной даты удаления.

Если у сервера нет получателей, Adal всё равно может принять и сохранить запрос, но автоматическая доставка не начнётся.

Отклонённый запрос не входит в обычный жизненный цикл: Adal сохраняет только минимальные сведения и не создаёт доставок.

Какие данные содержит запрос

Для каждого принятого запроса Adal хранит сведения, необходимые для просмотра, доставки и диагностики:

• HTTP-метод;
• полный URI, путь и параметры строки запроса;
• заголовки и тело запроса;
• размеры URI, заголовков и тела, а также их сумму;
• удалённый IP-адрес отправителя;
• дату и время приёма;
• дату запланированного удаления;
• принявший сервер;
• статус запроса и причины отклонения, если они есть;
• сводку по связанным доставкам;
• идентификаторы запроса и сервера, ключ региона и его географическое расположение.

Размер рассчитывается как сумма размеров URI, заголовков и тела:

Версия HTTP отдельно не хранится. Значение User-Agent доступно в составе заголовков, если отправитель его передал.

Поле Content-Type также вынесено в обзор запроса, чтобы заявленный формат тела был виден без поиска соответствующего заголовка в таблице.

Тело и формат данных

Тело может содержать JSON, данные формы, XML, обычный текст, двоичные данные или другой формат. Заголовок Content-Type описывает заявленный отправителем формат, но не подтверждает, что тело ему соответствует. Проверяйте данные в приложении-получателе.

Adal не дополняет запрос бизнес-данными и не исправляет его содержимое. Сохранённые метод, URI, заголовки и тело остаются источником истины о принятом HTTP-запросе.

Принятые и отклонённые запросы

Принятый запрос

Принятый запрос соответствует условиям сервера и аккаунта. Adal сохраняет его полные данные, расходует 1 кредит и создаёт доставки для настроенных получателей.

Принятие и доставка происходят отдельно, но общий статус запроса рассчитывается по совокупному состоянию всех его доставок.

Статусы запроса

Отклонённый запрос

Запрос может быть отклонён до сохранения полного содержимого. В поле Reject reasons могут отображаться следующие причины:

• Method not allowed — HTTP-метод не разрешён в настройках сервера;
• Payload too large — размер запроса превышает допустимый лимит;
• Bad request — входящий HTTP-запрос сформирован некорректно;
• Max requests reached — достигнут лимит количества запросов;
• Out of credits — на аккаунте недостаточно кредитов.

Для диагностики Adal оставляет ограниченную запись об отклонении. На странице видны метод, время приёма, связанный сервер, статус rejected , причина отказа, рассчитанные размеры, дата удаления, идентификаторы запроса и сервера, а также регион.

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

Отклонённые запросы не доставляются, не поддерживают Replay и не расходуют кредиты. Для них в Delivery summary нет доставок, а полное содержимое нельзя восстановить позднее.

Просмотр запроса

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

Обзор запроса

Full URI содержит путь вместе со строкой запроса, а Path показывает путь отдельно. Параметры после ? дополнительно разобраны в самостоятельном блоке Query parameters.

Status показывает агрегированное состояние запроса и всех его доставок. Например, success означает, что каждый получатель завершил доставку успешно, а partial — что успешные и окончательно неуспешные доставки присутствуют одновременно. Поле Reject reasons содержит причины отказа; если причин нет, интерфейс показывает прочерк.

Размеры URI, заголовков и тела показаны раздельно в байтах. Поле Total size равно их сумме и используется при проверке лимита размера запроса.

Параметры, заголовки и тело

В таблицах параметров и заголовков показаны исходные имена и значения. Счётчик в заголовке блока помогает быстро увидеть их количество; для пустого списка интерфейс показывает отдельное сообщение.

Блок тела показывает сохранённое содержимое и его заявленный Content-Type. JSON может быть показан сразу в форматированном виде с подсветкой либо по нажатию Preview. Действие скачивания позволяет получить тело отдельно, что особенно полезно для больших или нетекстовых данных.

Доставки и история попыток

Блок Delivery summary показывает доставки, связанные с запросом, и их общий итог, например 1 of 1 succeeded. Если доставки не созданы, страница явно сообщает No deliveries yet. Это нормальная ситуация, например когда у сервера нет настроенных получателей.

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

Каждая доставка отслеживается независимо, а поле Status в Request overview агрегирует их состояния. Пока хотя бы одна доставка продолжается, запрос имеет статус delivering . После завершения всех маршрутов он становится success , partial или failed .

Любой статус 2xx считается успешным. Статусы 4xx и 5xx , тайм-ауты и сетевые ошибки считаются неуспешными и могут привести к автоматическому повтору.

Подробная страница доставки

Переход из сводки открывает страницу конкретной доставки. Блок Delivery overview показывает:

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

В блоке Delivery history попытки представлены таблицей с временем, номером попытки, использованным URL и результатом. По ней можно сопоставить результат с конкретным номером попытки и адресом, на который выполнялась отправка.

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

Ручной повтор доставки

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

Повторная отправка запроса (Replay)

Replay создаёт новый запрос на основе сохранённого и заново проводит его через обычный процесс сервера. Это удобно после изменения кода, настройки маршрутов или устранения сбоя.

• исходный запрос не изменяется;
• новый запрос хранится отдельно и ссылается на исходный;
• используются получатели, настроенные для сервера в момент Replay;
• для нового запроса создаются новые доставки и история;
• операция расходует 1 кредит;
• Replay доступен только пока необходимые исходные данные ещё хранятся.

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

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

Автоматический или ручной повтор может доставить один запрос больше одного раза. Replay создаёт новый запрос Adal, но может представлять то же внешнее событие. Доставка через Adal не означает «ровно один раз».

Для получателя можно включить заголовок:

Все доставки одного запроса используют один ключ. Replay создаёт новый запрос и новый ключ. Если провайдер передаёт стабильный идентификатор события, используйте его для дедупликации и после Replay.

• проверяйте подпись и валидируйте входные данные;
• делайте обработчик идемпотентным;
• сохраняйте идентификатор события атомарно с бизнес-операцией;
• возвращайте 2xx только после принятия ответственности за обработку.

Срок хранения и удаление

Принятый запрос хранится ограниченный срок, определяемый тарифом и настройками сервера. Срок начинается в момент приёма; индивидуальная дата удаления отображается в деталях запроса.

По окончании срока Adal безвозвратно удаляет URI, заголовки, тело, IP-адрес, историю доставки и записи попыток. После этого запрос нельзя восстановить, повторно доставить или воспроизвести через Replay.

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

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

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

• проверяйте подпись вебхука по инструкции провайдера;
• разрешайте только ожидаемые HTTP-методы;
• валидируйте структуру, типы, размеры и значения входных данных;
• не доверяйте заголовкам и IP-адресу как единственному доказательству подлинности;
• защищайте URL сервера и доступ к панели;
• выбирайте подходящие регион и срок хранения;
• не помещайте секреты и содержимое вебхуков в обычные логи и аналитику.

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

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

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

Запрос не появился в панели

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

Запрос отклонён

Откройте запись и изучите причину. Сопоставьте метод с настройками сервера и учитывайте, что в размер входят тело, URI и заголовки. Полные данные отклонённого запроса недоступны — исправьте причину и отправьте событие заново.

Запрос принят, но доставки нет

Проверьте получателей сервера и историю конкретного маршрута. Direct HTTP может быть недоступен или вернуть ошибку, а доставка через Adal CLI — ожидать подключения. Результат другого получателя не определяет этот маршрут.

Тело выглядит неожиданно

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

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

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

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

Проверьте автоматические и ручные повторы, а также связь Replay с исходным запросом. Дедуплицируйте по стабильному ID события; для повторов одного запроса можно использовать X-Adal-Idempotency .

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

• Серверы — URL приёма, методы, регионы, лимиты и кредиты.
• Получатели — Direct HTTP, Adal CLI, история доставки и ручные действия.
• Повторные попытки — расписание, результаты, дубликаты и идемпотентность.
• Хранение данных — регионы, сроки, отклонённые запросы и удаление.
• Adal CLI — доставка запросов в локальные и приватные приложения.