INTEGRITY Dokumentace

← Analytics / analytics / graphql-api / tutorials

Dotazování výsledků kontrol stavu koncových bodů Magic Transit pomocí GraphQL

Použijte GraphQL Analytics API k dotazování na výsledky kontrol stavu koncových bodů pro váš účet. magicEndpointHealthCheckAdaptiveGroups dataset vrací výsledky sond agregované podle dimenzí a časového intervalu, které zadáte.

Všechny dotazy GraphQL odesílejte jako HTTP POST požadavky na https://api.cloudflare.com/client/v4/graphql.

Předpoklady

K dotazování dat kontrol stavu koncových bodů potřebujete následující:

Parametry dotazu

Následující parametry patří mezi nejběžnější v filter objekt:

Parametr Popis
date_geq Počáteční datum dotazu ve formátu YYYY-MM-DD formát (například 2026-01-01). Při použití s dimenzí zaokrouhlování data vrátí výsledky od tohoto data dále. Můžete také použít úplné časové razítko ve formátu ISO 8601 (například 2026-01-01T00:00:00Z).
date_leq (Volitelné) Koncové datum dotazu. Používá stejný formát jako date_geq.
datetime_geq (Volitelné) Počáteční časové razítko ve formátu ISO 8601 (například 2026-01-01T00:00:00Z). Použijte místo date_geq pro časové dimenze založené na zkrácení.
datetime_leq (Volitelné) Koncové časové razítko ve formátu ISO 8601.
limit Maximální počet skupin výsledků, které se mají vrátit.

Filtrovat můžete také podle libovolné dimenze uvedené v Dostupné dimenze tabulku. Filtr vytvoříte připojením přípony operátoru k názvu dimenze, například endpoint_in k filtrování podle seznamu koncových bodů, nebo checkType_neq k vyloučení konkrétního typu kontroly. Použití názvu dimenze bez přípony filtruje podle rovnosti. Úplný seznam podporovaných operátorů najdete v Filtrování.

Dostupné dimenze

Následující dimenze můžete dotazovat v dimensions pole:

Dimenze Popis
checkId Jedinečné ID nakonfigurované kontroly stavu.
checkType Typ kontroly stavu (například icmp).
endpoint IP adresa kontrolovaného endpointu.
name Název přiřazený kontrole stavu při jejím nastavení (může být prázdný, pokud není nastaven).
date Časové razítko události zkrácené na den.
datetime Úplné časové razítko události.
datetimeMinute Časové razítko události zkrácené na minutu.
datetimeFiveMinutes Časové razítko události zkrácené na pětiminutové intervaly.
datetimeFifteenMinutes Časové razítko události zkrácené na 15minutové intervaly.
datetimeHalfOfHour Časové razítko události zkrácené na 30minutové intervaly.
datetimeHour Časové razítko události zkrácené na hodinu.

Dostupné metriky

Metrika Popis
count Celkový počet událostí kontroly stavu ve skupině.
sum.total Celkový počet odeslaných sond kontroly stavu.
sum.failures Počet neúspěšných sond kontroly stavu.
avg.lossPercentage Průměrné vypočítané procento ztráty (0-100).

volání API

Následující příklad dotazuje výsledky kontrol stavu koncových bodů pro konkrétní účet a vrací počty sond agregované v pětiminutových intervalech. Nahraďte <ACCOUNT_ID> s vaším ID účtu a <API_TOKEN> s vaším API token.

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 @-

Výstup přesměrujte rourou do jq k naformátování odpovědi JSON pro snazší čtení:

... | 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 .

Ukázková odpověď

{
  "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
}

V této odpovědi sum.total je počet sond odeslaných během intervalu a sum.failures je počet těch, které nedostaly odpověď. failures hodnotu 0 značí, že endpoint byl po celé toto období plně dostupný.