GraphQL について
norumes cloud API を使用する上で GraphQL の理解が必要不可欠です。
この章では、GraphQL の基本的な使い方を学んでいきます。
GraphQL とは
レスポンス内容を自由に選択できる仕組みです。
GraphQL は HTTP プロトコルを利用したもので、エンドポイントに POST することで使用できます。
具体的には
{
"content-type": "application/json"
}
{
"query": "query Query() {}",
"variables": {},
"operationName": "Query"
}
のようなデータを POST し、レスポンスは JSON で返ってきます。
試してみよう
最初の一歩
本章に出てくるクエリは後ほど出てくる Agency 情報の取得方法 と同じクエリです。
本章では GraphQL の使い方を説明するため Agency に関して記載していませんが、後ほど出てきますので安心してください。
まずはを押してみましょう。
Responseが返ってきましたね。
あなたはデータをリクエストし、レスポンスを受け取りました。
ボタンを押した今この瞬間に GraphQL を体験しているのです。
次の章では実際に GraphQL を書きながら理解を深めていきます。
GraphQL を理解しよう
最初の一歩で何が起こったのか、1 から説明していきます。
Query とは
query FindAgencies( ... } と書かれていますね。
これを GraphQL 用語で Operation と言います。
query となっているため、これは Query ですが、他にも Mutation というものが存在します。
Mutation はデータの書き換えを行う際に使用するもので、norumes では今の所使いません。
Operation は複数記載することができ、Operation 全体の総称を Document といいます。
Schema とは
GraphQL には Schema と呼ばれる、型情報が存在します。
Operation は Schema を参考に書く必要が必要があります。
Schema は通常、GraphQL エンドポイントから取得することができます。
また、Playground のサイドメニューから確認することもできます。
型に付いている ! は null 許可しない という意味になります。
! がない場合は、逆の意味の null 許可 になります。
Field とは
findAgencies が増えましたね。これが Field です。
更に追加して...
5 行増えましたね。増えた部分は全て Field です。
Field は SQL の SELECT 文に似たようなもので、Field で指定した物のみレスポンスに含まれます。
REST API との大きな違いは、この 指定した物のみレスポンスに含まれる ことです。
Arguments とは
findAgencies が findAgencies(conditions: $conditions) になりましたね。
これは Arguments と呼ばれるものです。
日本語訳で 引数 です。
Field が 引数 を受け取れる場合、() で 引数 を渡すことができます。
感覚としては JavaScript の引数を Object で指定するのに似ています。
少々ややこしいですが、conditions が要求している引数名、$conditions が渡す変数名となります。
変数名 に関しては Variables とは で解説しています。
Variables とは
query FindAgencies(} が query FindAgencies($conditions: AgencySearchConditions!) { になりましたね。
これは Variables と呼ばれるものです。
日本語訳で 変数 です。
Field で 変数 を使用する場合、Operation で 変数 を定義する必要があります。
これは厳密には 変数名の定義 になり、変数の型 を指定する必要があります。
このクエリでは $conditions が変数名、AgencySearchConditions!が型になります。
変数名には $ を付ける必要があります。
Playground 左下の Variables に conditions: {} が追加されていることに気づきましたか？
上記で解説した $conditions と Variables の conditions は紐付いています。
ここでの conditions には AgencySearchConditions! 型のデータを入れられるため、試しに 都営バス と入れてみましょう。
findAgencies(conditions: $conditions) の conditions ではありません。
詳しくは Arguments とは で解説しています。
おっと、エラー が出ていますね。
引数が足りないようです...
引数を増やしてみましたが、ページネーション用のレスポンスしか返ってきていないようです...
Field を増やしてみましょう。
都営バス の Agency.uid を取得できました！👏
このように、GraphQL では引数に条件を入れたり、Field でレスポンスデータを制御することが可能です。
まとめ
データ量が膨大になりがちなものでも GraphQL であれば、Arguments や Field などで抑制出来ることがお分かりいただけましたでしょうか。