Skip to content

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

Zone Analytics の Colos エンドポイントから GraphQL Analytics へ

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

このガイドでは、非推奨（まもなく廃止）の Zone Analytics API から GraphQL API への移行方法を示します。colos エンドポイントの現実的なユースケースを例に、同じユースケースを GraphQL API へ置き換える手順を説明します。置き換え先の GraphQL API が、より強力になる理由も確認します。

この例では、特定 colo のリクエスト数を、発生した時間帯ごとに集計します。Zone Analytics の colos エンドポイントを参照し、API からデータを取得する curl を組み立てられます。

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

このクエリの意味は次のとおりです。

  • ZONE_ID に対する Analytics Read 権限を持つ API_TOKEN を使う。
  • ZONE_ID の colos 分析を取得する。期間の開始は 2020-12-10T00:00:00Z（since パラメーター）、終了は現在。

知りたい質問は「ZRH の 1 時間あたりのリクエスト数はいくつですか？」です。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[]

result 配列を、1 行ずつの JSON に分割します。

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

各 JSON 行を、さらに複数の JSON 行に分解します。各行には colo_id と、timeseries 配列の要素が 1 つ含まれます。

{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 リクエストです。そのため、HTTP リクエストデータの正規のソースである httpRequestsAdaptiveGroups を使います。この GraphQL API のノードでは、HTTP リクエストのほぼ任意の次元でフィルターとグループ化ができます。Adaptive なので、ABR 技術 ↗ によりレスポンスは高速です。

次の GraphQL API クエリは、「ZRH の 1 時間あたりのリクエスト数はいくつですか？」に答えるデータを取得します。

{
  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 オブジェクトを 1 行ずつ展開します。このクエリのゾーンは 1 件です（そのように選んだため）。ただし、1 つのクエリに複数ゾーンを含めることもできます。

.httpRequestsAdaptiveGroups[]

httpRequestsAdaptiveGroups フィールドはリストです。各データポイントは、選択した次元の組み合わせと、その組み合わせに対する集計を表します。ここでは、各データポイントを 1 行ずつ展開します。

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

これは単純です。各データポイントから関心のある属性を、以前 colos エンドポイントで使った形式で選びます。

GraphQL API は、多くの次元でフィルターとグループ化ができる強力なツールです。この機能は、Zone Analytics API の colos エンドポイントにはありません。

役に立ちましたか？