← Аналитика / analytics / graphql-api / migration-guides

Zone Analytics Colos Endpoint на GraphQL Analytics

В этом руководстве показано, как перейти с устаревшего (и вскоре отключаемого) zone analytics API на GraphQL API. В нём приведён пример реального сценария использования конечной точки colos, а затем показано, как этот сценарий реализовать через GraphQL API. Также рассматриваются возможности GraphQL API, которые делают его мощнее заменяемого им API.

В этом примере мы хотим вычислить количество запросов для конкретного colo с разбивкой по часам, в которые эти запросы происходили. Используя конечную точку colos в аналитике зоны, можно составить команду curl, которая получит данные из API.

curl -H "Authorization: Bearer $API_TOKEN" "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/analytics/colos?since=2020-12-10T00:00:00Z"  > colos_endpoint_output.json

Этот запрос означает следующее:

• Если у вас есть API_TOKEN с доступом Analytics Read к ZONE_ID.
• Получение аналитики colos для ZONE_ID с временным диапазоном, который начинается 2020-12-10T00:00:00Z (since параметр) до текущего момента.

Вопрос, на который мы хотим ответить: «Сколько запросов к ZHR приходится на час?» Используя данные ответа конечной точки colos и немного обработав их с помощью jq, можно ответить на этот вопрос такой командой:

cat colos_endpoint_output.json | jq  -c '.result[] | {colo_id: .colo_id, timeseries: .timeseries[]} | {colo_id: .colo_id, timeslot: .timeseries.since, requests: .timeseries.requests.all, bandwidth: .timeseries.bandwidth.all} | select(.requests > 0) | select(.colo_id == "ZRH") '

Эта команда jq довольно сложная, поэтому разберём её по частям:

.result[]

Это означает, что массив результатов разбивается на отдельные строки JSON.

{colo_id: .colo_id, timeseries: .timeseries[]}

Это разбивает каждую строку JSON на несколько строк JSON. Каждая полученная строка содержит colo_id и один элемент timeseries массив.

{colo_id: .colo_id, timeslot: .timeseries.since, requests: .timeseries.requests.all, bandwidth: .timeseries.bandwidth.all}

Это преобразует в плоский вид интересующие нас данные, которые находятся внутри объекта timeseries каждой строки.

select(.requests > 0) | select(.colo_id == "ZRH")

Это выбирает только строки, где количество запросов больше 0 и colo_id это ZRH.

Итоговые данные, которые мы получаем, выглядят как следующий ответ:

{"colo_id":"ZRH","timeslot":"2020-12-10T00:00:00Z","requests":601,"bandwidth":683581}
{"colo_id":"ZRH","timeslot":"2020-12-10T01:00:00Z","requests":484,"bandwidth":550936}
{"colo_id":"ZRH","timeslot":"2020-12-10T02:00:00Z","requests":326,"bandwidth":370627}
{"colo_id":"ZRH","timeslot":"2020-12-10T03:00:00Z","requests":354,"bandwidth":402527}
{"colo_id":"ZRH","timeslot":"2020-12-10T04:00:00Z","requests":446,"bandwidth":507234}
{"colo_id":"ZRH","timeslot":"2020-12-10T05:00:00Z","requests":692,"bandwidth":787688}
{"colo_id":"ZRH","timeslot":"2020-12-10T06:00:00Z","requests":1474,"bandwidth":1676166}
{"colo_id":"ZRH","timeslot":"2020-12-10T07:00:00Z","requests":2839,"bandwidth":3226871}
{"colo_id":"ZRH","timeslot":"2020-12-10T08:00:00Z","requests":2953,"bandwidth":3358487}
{"colo_id":"ZRH","timeslot":"2020-12-10T09:00:00Z","requests":2550,"bandwidth":2901823}
{"colo_id":"ZRH","timeslot":"2020-12-10T10:00:00Z","requests":2203,"bandwidth":2504615}
...

Как получить тот же результат с помощью GraphQL API?

GraphQL API позволяет гораздо точнее указывать, какие данные мы хотим получить. Конечная точка colos заставляет нас загружать всю информацию о распределении запросов и трафика по каждому colo, тогда как GraphQL API позволяет получать только те данные, которые нас интересуют.

Нас интересуют данные об HTTP-запросах, поэтому мы используем канонический источник таких данных, известный также как httpRequestsAdaptiveGroups. Этот узел GraphQL API позволяет фильтровать и группировать данные практически по любому измерению HTTP запроса, какое только можно представить. Он Адаптивный поэтому ответы будут быстрыми, так как их обеспечивает наша Технология ABR ↗.

Ниже приведён запрос GraphQL API, с помощью которого можно получить данные, нужные для ответа на вопрос: «Сколько запросов к ZHR приходится на час?»

{
  viewer {
    zones(filter: {zoneTag:"$ZONE_TAG"}) {
      httpRequestsAdaptiveGroups(filter: {datetime_gt: "2020-12-10T00:00:00Z", coloCode:"ZRH"}, limit:10000, orderBy: [datetimeHour_ASC]) {
        count
        sum {
          edgeResponseBytes
        }
        avg {
          sampleInterval
        }
        count
        dimensions {
          datetimeHour
          coloCode
        }
      }
    }
  }
}

Затем мы можем выполнить его с помощью curl:

curl -X POST -H "Authorization: Bearer $API_TOKEN"  https://api.cloudflare.com/client/v4/graphql -d "@./coloGroups.json" > graphqlColoGroupsResponse.json

Ответить на наш вопрос можно так же, как и раньше, с помощью jq:

cat graphqlColoGroupsResponse.json| jq -c '.data.viewer.zones[] | .httpRequestsAdaptiveGroups[] | {colo_id: .dimensions.coloCode, timeslot: .dimensions.datetimeHour, requests: .count, bandwidth: .sum.edgeResponseBytes}'

Эта команда намного проще предыдущей, потому что данные, возвращаемые GraphQL API, точнее тех, что возвращает конечная точка colos.

Всё же стоит объяснить эту команду, поскольку это поможет понять некоторые концепции, лежащие в основе GraphQL API.

.data.viewer.zones[]

Формат ответа GraphQL очень похож на формат запроса. Успешный ответ всегда содержит data объект, который оборачивает данные в ответе. Запрос всегда содержит viewer объект, который представляет вашего пользователя. Затем мы разворачиваем объекты zones построчно. В нашем запросе только одна зона, поскольку мы так решили, но запрос вполне может включать и несколько зон.

.httpRequestsAdaptiveGroups[]

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

{colo_id: .dimensions.coloCode, timeslot: .dimensions.datetimeHour, requests: .count, bandwidth: .sum.edgeResponseBytes}

Это просто: здесь выбираются нужные нам атрибуты каждой точки данных в том же формате, что и раньше использовался в конечной точке colos.

GraphQL API представляет собой очень мощный инструмент, поскольку позволяет фильтровать и группировать данные по многим измерениям. Этой возможности полностью лишена конечная точка colos в Zone Analytics API.