GraphQL はデータをグラフとして構造化します。GraphQL はスキーマを使って、データグラフ内のオブジェクトとその階層を定義します。必要なデータを得るには、クエリでグラフのエッジをたどります。クエリはスキーマの構造に従う必要があります。
GraphQL クエリの中心は、ノードとその フィールド です。ノードは特定の 型 のオブジェクトです。型は、オブジェクトを構成するフィールドを指定します。
フィールドは別のノードになることがあり、その場合は適切なクエリに入れ子の要素を含めます。一部のノードは関数のように見え、対象の範囲を制限する引数を取れます。各ノードにフィルターを適用できます。
Cloudflare の GraphQL スキーマに対する典型的なクエリは、次の 4 つの主な要素で構成されます。
viewer- ルートノードですzonesまたはaccounts- クエリの範囲、つまりクエリしたいドメインまたはアカウントを示します。viewerは 1 つのzonesまたはaccounts、あるいは両方にアクセスできます- データノード または データセット - クエリしたいデータを表します。
zonesまたはaccountsには 1 つ以上のデータセットが含まれます。ノードの見つけ方については、イントロスペクション を参照してください - フィールドセット - データセット のフィールド、または入れ子のフィールドの集まりです
Cloudflare GraphQL API へのクエリは、HTTP POST リクエストで送り、ペイロードは次のフィールドからなる JSON 形式である必要があります。
{
"query": "",
"variables": {}
}上記の構造では、query フィールドには 1 行 の文字列として整形した GraphQL クエリを入れます（改行は削除またはエスケープします）。variables は、クエリ内のプレースホルダーの値をすべて含むオブジェクトです。
次の例では、GraphQL クエリがゾーンスコープの firewallEventsAdaptive データセットから、2 件の WAF イベントの datetime、action、クライアントリクエストの HTTP ホストを host フィールドとして取得します。
query ASingleDatasetExample($zoneTag: string, $start: Time, $end: Time) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
firewallEventsAdaptive(
filter: { datetime_gt: $start, datetime_lt: $end }
limit: 2
orderBy: [datetime_DESC]
) {
action
datetime
host: clientRequestHTTPHost
}
}
}
}上記のクエリには、変数プレースホルダー $zoneTag、$start、$end があります。これらのプレースホルダーの値は、クエリと一緒にペイロードの variables フィールドに入れます。以下の例では、文字「Z」で示す UTC タイムゾーンを使っています。
{
"zoneTag": "<zone-tag>",
"start": "2020-08-03T02:07:05Z",
"end": "2020-08-03T17:07:05Z"
}Cloudflare GraphQL API にクエリを送る方法はいくつかあります。お気に入りの GraphQL クライアントや CLI を使って、curl でリクエストを送れます。GraphiQL クライアントの使い方 のガイドがあります。curl でクエリを実行する方法は こちら を参照してください。
{
"data": {
"viewer": {
"zones": [
{
"firewallEventsAdaptive": [
{
"action": "log",
"host": "cloudflare.guru",
"datetime": "2020-08-03T17:07:03Z"
},
{
"action": "log",
"host": "cloudflare.guru",
"datetime": "2020-08-03T17:07:01Z"
}
]
}
]
}
},
"errors": null
}前述のとおり、クエリには 1 つまたは複数のノード（データセット）を含められます。API レベルではデータ抽出は同時に行われますが、すべてのデータセットクエリが結果を得るまでレスポンスは遅れます。実行中にいずれかが失敗すると、クエリ全体が打ち切られ、エラーが返されます。
query MultipleDatasetsExample(
$zoneTag: string
$start: Time
$end: Time
$ts: Date
) {
viewer {
zones(filter: { zoneTag: $zoneTag }) {
last10Events: firewallEventsAdaptive(
filter: { datetime_gt: $start, datetime_lt: $end }
limit: 10
orderBy: [datetime_DESC]
) {
action
datetime
host: clientRequestHTTPHost
}
top3DeviceTypes: httpRequestsAdaptiveGroups(
filter: { date: $ts }
limit: 10
orderBy: [count_DESC]
) {
count
dimensions {
device: clientDeviceType
}
}
}
}
}{
"zoneTag": "<zone-tag>",
"start": "2022-10-02T00:26:49Z",
"end": "2022-10-04T14:26:49Z",
"ts": "2022-10-04"
}{
"data": {
"viewer": {
"zones": [
{
"last10Events": [
{
"action": "block",
"country": "TR",
"datetime": "2022-10-04T08:41:09Z"
},
{
"action": "block",
"country": "TR",
"datetime": "2022-10-04T08:41:09Z"
},
{
"action": "block",
"country": "RU",
"datetime": "2022-10-04T01:09:36Z"
},
{
"action": "block",
"country": "US",
"datetime": "2022-10-03T14:26:49Z"
},
{
"action": "block",
"country": "US",
"datetime": "2022-10-03T14:26:46Z"
},
{
"action": "block",
"country": "CN",
"datetime": "2022-10-02T23:51:26Z"
},
{
"action": "block",
"country": "TR",
"datetime": "2022-10-02T23:39:41Z"
},
{
"action": "block",
"country": "TR",
"datetime": "2022-10-02T23:39:41Z"
}
],
"top3DeviceTypes": [
{
"count": 4580,
"dimensions": {
"device": "desktop"
}
}
]
}
]
}
},
"errors": null
}Cloudflare Analytics API と GraphQL に関する参考記事です。