Использование XML-политик для регистрации и анализа вызовов API из Azure API Management

Azure API Management (APIM) — это мощная платформа, которая позволяет публиковать и масштабировать API, обеспечивая при этом их безопасность.
Одной из замечательных особенностей Azure APIM является то, что вы можете добавлять плагины и трансформации к своим API без изменения кода или перезапуска.

Эти возможности развертываются с помощью XML Policies, которые представляют собой набор утверждений.
Moesif API Observability можно добавить всего за несколько минут с помощью XML-политики для APIM, что позволяет легко получить видимость вызовов API, даже тех, которые отклоняются и никогда не достигают вашей базовой службы.

Что такое Moesif API Observability для Azure APIM?

API Observability позволяет инженерам и бизнесу глубоко понять, как используются их API, и определить, что нужно исправить, прежде чем клиенты напишут в службу поддержки и перегрузят вашу команду.
вашу команду. В отличие от классического мониторинга API, который обычно проверяет конечную точку на наличие типичного «красного, желтого, зеленого» статуса, API Observability
позволяет руководителям наблюдать за любым поведением, происходящим с API. Некоторые примеры включают:

• владельцы продуктов для понимания использования API и того, на чем следует сосредоточиться
• Руководители инженерных подразделений для информирования о проблемах API и их устранения
• Исследователи безопасности для изучения угроз API и их предотвращения.

Как работает это решение

Для работы API Observability агент мониторинга должен пассивно регистрировать трафик API в службе наблюдаемости. Это может быть пользовательская сборка на базе хранилища данных, например Azure Synapse Analytics, или готовое решение, например Moesif. Шлюз API, такой как Azure APIM, является естественной точкой для централизации журналов API. В противном случае каждая служба должна иметь свой собственный SDK.

Это решение развертывается с помощью шаблона Azure Resource Manager, который автоматически добавляет несколько компонентов к вашей подписке Azure:

Ниже приведена диаграмма, показывающая, как решение развертывается в вашей подписке Azure.

Как только журналы API получены Moesif, остальная обработка данных и аналитика выполняется службой.

Примеры использования

Понимание использования API клиентами

Цель аналитики API — получить представление о том, кто использует ваши API и как они их используют. Для этого интеграция автоматически свяжет вызовы API с определенными профилями пользователей. По умолчанию политика XML также будет извлекать информацию о пользователе, такую как идентификатор пользователя, имя, фамилия и электронная почта из объекта
объекта context.User и сохраняется как часть профиля пользователя в Moesif. Вы всегда можете добавить дополнительные свойства пользователя, используя API Moesif для отслеживания пользователей.

Важнейшим отчетом является понимание того, какие клиенты чаще всего используют ваши API. Поскольку мы отслеживаем имя и электронную почту, мы можем открыть отчет в Moesif, показывающий еженедельный трафик API по названию компании.

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

Благодаря высокой кардинальности и наблюдаемости API вы можете нарезать журналы API по любому количеству полей, таких как маршрут URI, HTTP-заголовки и даже поля в полезной нагрузке, что позволит вам выявить проблемы, влияющие на клиентов. Одной из таких метрик, которую мы рекомендуем отслеживать, является 90-й процентиль. В отличие от средней задержки, если посмотреть на 90-ю процентильную задержку, можно лучше увидеть большие колебания в задержке, что обычно хуже для клиентов, чем API с постоянно высокой задержкой. API с постоянными случайными скачками задержки может посеять хаос в своих собственных сервисах.

Для этого перейдите в раздел События -> Временные ряды, а затем выберите метрику P90 Latency. Вы также можете понять это в разбивке по маршрутам или службам. Для этого добавьте группу по «Request URI». Moesif объединяет маршруты таким образом, что /items/1 и /items/2 будут отображаться как /items/:id в пользовательском интерфейсе, что облегчает анализ.

Исследовательские угрозы

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

Распространенной угрозой безопасности API является отсутствие надлежащей защиты от соскабливания данных и намеренного злоупотребления API. API предоставляет прямой доступ к вашим данным, который хакер может использовать для соскабливания. Одним из способов обнаружения клиентов, злоупотребляющих API, является просмотр объема данных, доступных каждому пользователю. Чтобы создать эту метрику, добавьте суммирование response.headers.Content-Length, а затем сгруппируйте их по имени пользователя:

Как настроить Azure APIM с Moesif API Observability

1. Запустите развертывание ресурсов Azure

Нажмите кнопку ниже, чтобы начать пользовательское развертывание с шаблоном ресурсов Moesif Azure Resource Template.

2. Настройте параметры

На панели развертывания шаблона Azure установите следующие свойства:

• Установите группу ресурсов на ту же группу ресурсов, которая содержит ваш существующий экземпляр Azure APIM. Это гарантирует, что регистратор APIM, moesif-log-to-event-hub, будет автоматически создан для вас.

• Установите Moesif Application Id на тот, который отображается после входа в вашу учетную запись Moesif. Вы можете создать бесплатный идентификатор на сайте Moesif.

• Установите Existing Api Mgmt Name на имя вашего экземпляра Azure APIM. Если оно пустое, вам нужно будет вручную создать регистратор APIM.

После этого нажмите кнопку Review+create внизу и завершите работу мастера создания шаблона.

Иногда Azure сообщает о неудачном развертывании из-за медленного распространения новых настроек DNS, даже если все было развернуто успешно. Мы рекомендуем продолжить процесс. Если после последнего шага у вас все еще возникают проблемы, просмотрите раздел «Устранение неполадок».

3. Добавление XML-политики

На портале Azure перейдите к существующему экземпляру Azure API Management.
Затем добавьте приведенные ниже XML-политики ко всем продуктам или API, для которых вы хотите включить ведение журналов API.

Рекомендуется добавить XML-политику глобально для всех API. Затем используйте динамическую выборку Moesif, если вы хотите создать правила, которые избирательно выбирают или подавляют сбор данных. Правила включаются динамически на основе определенного поведения клиентов, правил regex и т.д.

Более подробную информацию о редактировании политик APIM можно найти в документации Azure.

<policies>
    <inbound>
        <base />
        <set-variable name="moesif-message-id" value="@(Guid.NewGuid())" />
        <log-to-eventhub logger-id="moesif-log-to-event-hub" partition-id="0">@{
var body = context.Request.Body?.As<string>(true);
var MAX_BODY_EH = 145000;
var origBodyLen = (null != body) ? body.Length : 0;
if (MAX_BODY_EH < origBodyLen){ body = body.Remove(MAX_BODY_EH); }
var headers = context.Request.Headers
    .Where(h => h.Key != "Ocp-Apim-Subscription-Key")
    .Select(h => string.Format("{0}: {1}", h.Key, String.Join(", ", h.Value).Replace(""", "\""))).ToArray<string>();
var jwtToken = context.Request.Headers.GetValueOrDefault("Authorization","").AsJwt();
var userId = (context.User != null && context.User.Id != null) ? context.User.Id : (jwtToken != null && jwtToken.Subject != null ? jwtToken.Subject : string.Empty);
var cru = new JObject();
if (context.User != null) {
  cru.Add("Email", context.User.Email);
  cru.Add("Id", context.User.Id);
  cru.Add("FirstName", context.User.FirstName);
  cru.Add("LastName", context.User.LastName);}
var crus = System.Convert.ToBase64String(Encoding.UTF8.GetBytes(cru.ToString()));
var requestBody = (body != null ? System.Convert.ToBase64String(Encoding.UTF8.GetBytes(body)) : string.Empty);
return new JObject(
  new JProperty("event_type", "request"),
  new JProperty("message-id", context.Variables["moesif-message-id"]),
  new JProperty("method", context.Request.Method),
  new JProperty("ip_address", context.Request.IpAddress),
  new JProperty("uri", context.Request.OriginalUrl.ToString()),
  new JProperty("user_id", userId),
  new JProperty("contextRequestUser", crus),
  new JProperty("company_id", ""),
  new JProperty("request_headers", string.Join(";;", headers)),
  new JProperty("request_body", requestBody),
  new JProperty("contextTimestamp", context.Timestamp.ToString("o")),
  new JProperty("metadata", $@"")
  ).ToString();}</log-to-eventhub>
        <set-variable name="sent-moesif-request" value="@(true)" />
    </inbound>
    <backend>
        <forward-request follow-redirects="true" />
    </backend>
    <outbound>
        <base />
        <choose>
            <when condition="@(context.Variables.ContainsKey("sent-moesif-request") && !context.Variables.ContainsKey("sent-moesif-response"))">
                <log-to-eventhub logger-id="moesif-log-to-event-hub" partition-id="1">@{
var body = context.Response.Body?.As<string>(true);
var MAX_BODY_EH = 145000;
var origBodyLen = (null != body) ? body.Length : 0;
if (MAX_BODY_EH < origBodyLen){ body = body.Remove(MAX_BODY_EH);}
var headers = context.Response.Headers.Select(h => string.Format("{0}: {1}", h.Key, String.Join(", ", h.Value).Replace(""", "\""))).ToArray<string>();
var responseBody = (body != null ? System.Convert.ToBase64String(Encoding.UTF8.GetBytes(body)) : string.Empty);
return new JObject(
  new JProperty("event_type", "response"),
  new JProperty("orig_body_len", origBodyLen),
  new JProperty("message-id", context.Variables["moesif-message-id"]),
  new JProperty("status_code", context.Response.StatusCode),
  new JProperty("response_headers", string.Join(";;", headers)),
  new JProperty("contextTimestamp", context.Timestamp.Add(context.Elapsed).ToString("o")),
  new JProperty("response_body", responseBody)
  ).ToString();}</log-to-eventhub>
                <set-variable name="sent-moesif-response" value="@(true)" />
            </when>
        </choose>
    </outbound>
    <on-error>
        <base />
        <choose>
            <when condition="@(context.Variables.ContainsKey("sent-moesif-request") && !context.Variables.ContainsKey("sent-moesif-response"))">
                <log-to-eventhub logger-id="moesif-log-to-event-hub" partition-id="1">@{
var body = context.Response.Body?.As<string>(true);
var MAX_BODY_EH = 145000;
var origBodyLen = (null != body) ? body.Length : 0;
if (MAX_BODY_EH < origBodyLen){ body = body.Remove(MAX_BODY_EH);}
var headers = context.Response.Headers.Select(h => string.Format("{0}: {1}", h.Key, String.Join(", ", h.Value).Replace(""", "\""))).ToArray<string>();
var responseBody = (body != null ? System.Convert.ToBase64String(Encoding.UTF8.GetBytes(body)) : string.Empty);
return new JObject(
  new JProperty("event_type", "response"),
  new JProperty("orig_body_len", origBodyLen),
  new JProperty("message-id", context.Variables["moesif-message-id"]),
  new JProperty("status_code", context.Response.StatusCode),
  new JProperty("response_headers", string.Join(";;", headers)),
  new JProperty("contextTimestamp", context.Timestamp.Add(context.Elapsed).ToString("o")),
  new JProperty("response_body", responseBody)
  ).ToString();}</log-to-eventhub>
                <set-variable name="sent-moesif-response" value="@(true)" />
            </when>
        </choose>
    </on-error>
</policies>

4. Успех!

После интеграции Azure APIM вы должны увидеть, что журналы API отображаются в Moesif. Сделайте несколько вызовов к домену API-шлюза и посмотрите, как они отображаются в журнале событий Moesif в режиме реального времени. Вы должны увидеть код состояния, URL и другие параметры HTTP, как показано на скриншоте ниже:

Идентификация пользователей

Вызовы API ассоциируются с пользователями с помощью поля user_id. Политика XML по умолчанию извлекает его из context.User.Id или JWT-токена, используя следующую логику:

var jwtToken = context.Request.Headers.GetValueOrDefault("Authorization","").AsJwt();
var userId = (context.User != null && context.User.Id != null) ? context.User.Id : (jwtToken != null && jwtToken.Subject != null ? jwtToken.Subject : null);

Вы можете изменить значение идентификатора пользователя, изменив эти строки кода.

Добавление метаданных пользователя

По умолчанию политика XML также сохраняет некоторые полезные свойства пользователя, такие как Email и FirstName, используя следующий код в политике XML:

if (context.User != null) {
  cru.Add("Email", context.User.Email);
  cru.Add("FirstName", context.User.FirstName);
  cru.Add("LastName", context.User.LastName);
}
var crus = System.Convert.ToBase64String(Encoding.UTF8.GetBytes(cru.ToString()));

Они будут сохранены вместе с профилем пользователя в Moesif, который соответствует определенному userId. Вы можете добавить дополнительные поля из context.User для удовлетворения ваших требований, изменив эти строки кода.

Добавление метаданных события

Вы также можете сохранять метаданные события. В отличие от метаданных пользователя, метаданные события специфичны для каждой транзакции API и могут содержать полезную информацию, которая еще не регистрируется Moesif, например, идентификаторы трассировки или переменные среды. Поле metadata должно представлять собой строку в кодировке JSON.

Запросы на выборку

Эта интеграция также поддерживает динамическую выборку. Это позволяет выборочно отбирать вызовы API на основе поведения пользователя.
чтобы сэкономить на стоимости подписки на Moesif. Moesif по-прежнему будет экстраполировать исходные метрики.

Расширенная API-аналитика поведения пользователей

Вы можете использовать свою интеграцию не только для изолированного анализа вызовов API, но и для анализа всего пути клиента. Такой подход облегчает просмотр таких вещей, как отчеты о воронке «Время до первого приветствия» и «Время до ценности».

Отслеживайте действия пользователя в вашем пользовательском интерфейсе, такие как «Signed In» или «Viewed Docs», и начните отслеживать действия пользователя в вашем пользовательском интерфейсе, такие как «Signed In» или «Viewed Docs». Это облегчит нарезку использования API по трафику клиентов. Для этого добавьте moesif-browser-js в свой пользовательский интерфейс и вызовите метод track:

moesif.track('Clicked Sign Up', {
  button_label: 'Get Started',
  sign_up_method: 'Google SSO'
});

После этого первым делом создайте отчет о воронке. В приведенном ниже отчете мы создали анализ воронки, состоящей из трех этапов.

1. Первый шаг — это регистрация клиента в вашем веб-приложении (действие пользователя).
2. Второй шаг — это одна платежная операция через API. Таким образом, переход от шага 1 к шагу 2 показывает коэффициент конверсии от регистрации до первого вызова API.
3. Третий шаг — это более 100 платежных операций. Для данного примера мы считаем это моментом «ага», демонстрирующим ценность для клиента. Переход от шага 2 к шагу 3 показывает снижение числа клиентов, совершивших вызовы API, которые действительно получили реальную пользу.

Заключение

Наблюдаемость API критически важна для инженерных и бизнес-лидеров, чтобы принимать обоснованные решения о том, на чем сосредоточиться и где есть проблемы. Хотя вы можете создать свой собственный шлюз API, конвейер обработки данных и хранилище данных, это может стать причиной огромного дефицита времени для вашей инженерной команды. Использование полностью управляемых услуг, таких как Azure API Management API Gateway и Moesif API Analytics, поможет вам масштабироваться, не сдерживаясь устаревшей инфраструктурой.

Хотите узнать, как клиенты используют ваши API? Попробуйте Moesif API Analytics!

Эта статья была первоначально написана для блога Moesif Дерриком Гиллингом, генеральным директором и основателем Moesif API Analytics.