INTEGRITY Документация

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

Запрос результатов проверки состояния конечных точек Magic Transit с помощью GraphQL

Используйте GraphQL Analytics API для запроса результатов проверки состояния конечных точек вашего аккаунта. magicEndpointHealthCheckAdaptiveGroups набор данных возвращает результаты проб, агрегированные по указанным вами измерениям и временному интервалу.

Все запросы GraphQL отправляйте как HTTP POST запросов к https://api.cloudflare.com/client/v4/graphql.

Предварительные требования

Чтобы запрашивать данные проверок состояния конечных точек, потребуется следующее:

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

Ниже перечислены одни из самых распространённых параметров в filter объект:

Параметр Описание
date_geq Дата начала запроса в формате YYYY-MM-DD в формате (например, 2026-01-01). При использовании с измерением усечения по дате возвращает результаты начиная с этой даты. Также можно указать полную временную метку в формате ISO 8601 (например, 2026-01-01T00:00:00Z).
date_leq (Необязательно) Конечная дата запроса. Использует тот же формат, что и date_geq.
datetime_geq (Необязательно) Начальная временная метка в формате ISO 8601 (например, 2026-01-01T00:00:00Z). Используйте вместо date_geq для временных измерений с усечением.
datetime_leq (Необязательно) Конечная временная метка в формате ISO 8601.
limit Максимальное количество групп результатов для возврата.

Также можно фильтровать по любому измерению, указанному в Доступные измерения таблицу. Чтобы создать фильтр, добавьте суффикс оператора к имени измерения, например, endpoint_in чтобы отфильтровать по списку конечных точек, или checkType_neq чтобы исключить определённый тип проверки. Использование имени измерения без суффикса задаёт фильтр по равенству. Полный список поддерживаемых операторов приведён в Фильтрация.

Доступные измерения

Следующие измерения можно запрашивать в dimensions поле:

Измерение Описание
checkId Уникальный ID настроенной проверки состояния.
checkType Тип проверки состояния (например, icmp).
endpoint IP-адрес проверяемой конечной точки.
name Имя, присвоенное проверке состояния при её настройке (может быть пустым, если не задано).
date Временная метка события, усечённая до дня.
datetime Полная временная метка события.
datetimeMinute Временная метка события, усечённая до минуты.
datetimeFiveMinutes Временная метка события, усечённая до пятиминутных интервалов.
datetimeFifteenMinutes Временная метка события, усечённая до 15-минутных интервалов.
datetimeHalfOfHour Временная метка события, усечённая до 30-минутных интервалов.
datetimeHour Временная метка события, усечённая до часа.

Доступные метрики

Метрика Описание
count Общее количество событий проверки работоспособности в группе.
sum.total Общее количество отправленных зондов проверки работоспособности.
sum.failures Количество неудачных зондов проверки состояния.
avg.lossPercentage Среднее расчётное значение процента потерь (0-100).

Вызов API

Следующий пример запрашивает результаты проверки состояния конечных точек для конкретного аккаунта, возвращая количество проб, агрегированное по пятиминутным интервалам. Замените <ACCOUNT_ID> с вашим ID аккаунта и <API_TOKEN> с вашим API-токен.

echo '{ "query":
  "query GetEndpointHealthCheckResults($accountTag: string, $datetimeStart: string) {
    viewer {
      accounts(filter: {accountTag: $accountTag}) {
        magicEndpointHealthCheckAdaptiveGroups(
          filter: {
            datetime_geq: $datetimeStart
          }
          limit: 10
        ) {
          count
          dimensions {
            checkId
            checkType
            endpoint
            datetimeFiveMinutes
          }
          sum {
            failures
            total
          }
        }
      }
    }
  }",
  "variables": {
    "accountTag": "<ACCOUNT_ID>",
    "datetimeStart": "2026-01-21T00:00:00Z"
  }
}' | tr -d '\n' | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @-

Перенаправьте вывод по каналу в jq чтобы отформатировать ответ JSON для более удобного чтения:

... | curl --silent \
https://api.cloudflare.com/client/v4/graphql \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data @- | jq .

Пример ответа

{
  "data": {
    "viewer": {
      "accounts": [
        {
          "magicEndpointHealthCheckAdaptiveGroups": [
            {
              "count": 288,
              "dimensions": {
                "checkId": "90b478c7-bb51-4640-b94b-2c3050e9fa00",
                "checkType": "icmp",
                "datetimeFiveMinutes": "2026-01-21T12:00:00Z",
                "endpoint": "103.21.244.100"
              },
              "sum": {
                "failures": 0,
                "total": 288
              }
            },
            {
              "count": 288,
              "dimensions": {
                "checkId": "90b478c7-bb51-4640-b94b-2c3050e9fa00",
                "checkType": "icmp",
                "datetimeFiveMinutes": "2026-01-21T12:05:00Z",
                "endpoint": "103.21.244.100"
              },
              "sum": {
                "failures": 2,
                "total": 288
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}

В этом ответе sum.total является числом зондов, отправленных в течение интервала, а sum.failures является числом тех, кто не получил ответа. failures значение 0 означает, что конечная точка была полностью доступна в течение этого периода.