Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

GraphQL で Magic Transit のエンドポイントヘルスチェック結果をクエリする

最終更新 Markdown で表示Agent セットアップ

アカウントのエンドポイント ヘルスチェック結果を照会するには、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 は特定のチェック種別を除外します。サフィックスなしのディメンション名は等価フィルタです。対応する演算子の一覧は Filtering を参照してください。

利用できるディメンション

dimensions フィールドでは、次のディメンションを照会できます。

ディメンション 説明
checkId 設定したヘルスチェックの一意の ID です。
checkType ヘルスチェックの種別です（例: icmp）。
endpoint チェック対象エンドポイントの IP アドレスです。
name 設定時にヘルスチェックへ付けた名前です（未設定の場合は空になることがあります）。
date 日単位に切り捨てたイベントのタイムスタンプです。
datetime イベントの完全なタイムスタンプです。
datetimeMinute 分単位に切り捨てたイベントのタイムスタンプです。
datetimeFiveMinutes 5 分間隔に切り捨てたイベントのタイムスタンプです。
datetimeFifteenMinutes 15 分間隔に切り捨てたイベントのタイムスタンプです。
datetimeHalfOfHour 30 分間隔に切り捨てたイベントのタイムスタンプです。
datetimeHour 時間単位に切り捨てたイベントのタイムスタンプです。

利用できるメトリクス

メトリクス 説明
count グループ内のヘルスチェックイベントの総数です。
sum.total 送信したヘルスチェックプローブの総数です。
sum.failures 失敗したヘルスチェックプローブの数です。
avg.lossPercentage 算出した損失率の平均です（0〜100）。

API 呼び出し

次の例は、特定アカウントのエンドポイント ヘルスチェック結果を照会し、5 分間隔で集計したプローブ数を返します。<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 @-

JSON レスポンスを読みやすくするには、出力を jq にパイプして整形します。

... | 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 なら、その期間中エンドポイントは完全に到達可能だったことを示します。

役に立ちましたか？