Идентификатор запроса — это уникальный идентификатор, который API возвращает в заголовке каждого ответа, чтобы конкретный вызов можно было найти в журналах провайдера при обращении в службу поддержки.
Для отладки интеграции, в которой участвуют две компании, нужен общий ориентир. Идентификатор запроса и есть такой ориентир: уникальное значение, которое сервер генерирует для каждого HTTP-обмена и возвращает в заголовке ответа, который по соглашению часто называется X-Request-Id. Назовите его службе поддержки провайдера, и там смогут точно найти, что было получено, когда и что было отправлено в ответ, не перебирая по временным меткам тысячи похожих вызовов.
Полезно различать идентификаторы. Идентификатор запроса обозначает один обмен. Идентификатор ресурса, например идентификатор сообщения, обозначает созданный объект, который может пережить множество запросов: POST-запрос, завершившийся тайм-аутом и повторённый с тем же ключом идемпотентности, даёт два идентификатора запроса и одно сообщение. Идентификатор корреляции принадлежит вам: он создаётся на входе в вашу систему и передаётся через все сервисы, которые затрагивает задание; стандарты трассировки, такие как W3C Trace Context, формализуют ту же идею для взаимодействия между сервисами. Записывайте в журнал все эти идентификаторы вместе — с эндпоинтом, HTTP-статусом и временем в UTC.
Пример
Условный сервис заказов получает ответ 500 в 14:02:11 UTC. В его строке журнала записаны идентификатор запроса из ответа, ключ идемпотентности, эндпоинт и статус. В обращении в поддержку указан идентификатор запроса, и больше ничего не нужно: ни скриншотов, ни вставленных полезных нагрузок, полных телефонных номеров, ни случайно раскрытого ключа API.
Типичные ошибки
- Записывать заголовки ответа в журнал только при успехе, хотя нужны они именно при ошибках.
- Позволять HTTP-клиенту выбрасывать исключение до того, как прочитаны заголовки.
- Путать идентификатор запроса с идентификатором сообщения, спрашивая о доставке.
В SMSMeteor: каждый ответ содержит X-Request-Id; указывайте его, когда пишете в службу поддержки, которая отвечает на обращения в панели семь дней в неделю. У идентификаторов есть префиксы: msg_, bat_, evt_, cmp_. Поле reference — до 128 символов на ваше усмотрение — возвращается в ответах и вебхуках, поэтому служит готовым идентификатором корреляции, а повторно отправленные события вебхуков сохраняют исходный идентификатор события. См. справочник API.
