クエリの基本
GraphQLはデータをグラフとして構造化します。GraphQLはスキーマを使用して、データグラフ内のオブジェクトとその階層を定義します。必要なデータを取得するためにクエリを使用してグラフのエッジを探索できます。これらのクエリはスキーマの構造を尊重する必要があります。
ノードとそのフィールドがGraphQLクエリの中心です。ノードは特定のタイプのオブジェクトであり、タイプはオブジェクトを構成するフィールドを指定します。
フィールドは別のノードであることがあり、適切なクエリにはネストされた要素が含まれます。一部のノードは、作用する範囲を制限するために引数を取る関数のように見えます。各ノードでフィルターを適用できます。
Cloudflare GraphQLスキーマに対する典型的なクエリは、4つの主要なコンポーネントで構成されています：
viewer- ルートノードです。zonesまたはaccounts- クエリのスコープを示します。つまり、クエリしたいドメインエリアまたはアカウントです。viewerは1つのzonesまたはaccounts、またはその両方にアクセスできます。- データノードまたはデータセット - クエリしたいデータを表します。
zonesまたはaccountsは1つ以上のデータセットを含む場合があります。ノードの発見についての詳細はイントロスペクションを参照してください。 - フィールドセット - データセットのフィールドまたはネストされたフィールドのセットです。
Cloudflare GraphQL APIへのクエリは、次のフィールドで構成されたJSON形式のペイロードを持つHTTP POSTリクエストとして送信する必要があります：
{ "query": "", "variables": {}}上記の構造から、queryフィールドには単一行の文字列としてフォーマットされたGraphQLクエリが含まれている必要があります（つまり、すべての改行記号は削除またはエスケープされるべきです）。variablesは、クエリ自体で使用されるプレースホルダーのすべての値を含むオブジェクトです。
以下の例では、GraphQLクエリがfirewallEventsAdaptiveデータセットからゾーンスコープの2つのWAFイベントのdatetime、action、およびクライアントリクエストHTTPホストをhostフィールドとして取得します。
{ viewer { zones(filter: { zoneTag: $tag }) { firewallEventsAdaptive( filter: { datetime_gt: $start datetime_lt: $end } limit: 2 orderBy: [ datetime_DESC ] ) { action datetime host: clientRequestHTTPHost } } }}上記のクエリでは、変数プレースホルダー：$tag、$start、および$endがあります。これらのプレースホルダーに値を提供するために、クエリとともにペイロードのvariablesフィールドに配置します。
{ "tag": "<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レベルでは、データの抽出は同時に行われますが、レスポンスはすべてのデータセットクエリが結果を得るまで遅延します。実行中に失敗があった場合、全体のクエリは終了し、エラーが返されます。
{ viewer { zones(filter: { zoneTag: $tag }) { 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 } } } }}{ "tag": "<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を使用する際に役立つ記事をいくつか紹介します。