Skip to main content

GraphQLの紹介

GitHub GraphQL APIを利用するための有益な用語と概念を学んでください。

GraphQLの用語

GitHub GraphQL APIは、GitHub REST APIからのアーキテクチャ及び概念的な移行を表すものです。 GraphQL API のリファレンス ドキュメントでは、いくつかの新しい用語が登場することになるでしょう。

スキーマ

スキーマは、GraphQL APIの型システムを定義します。 これは、クライアントがアクセスできる、存在しうるデータ(オブジェクト、フィールド、リレーションシップ、すべて)の完全な集合を記述します。 クライアントからの呼び出しは、スキーマに対して検証され、実行されます。 クライアントは、イントロスペクションを使用してスキーマに関する情報を確認できます。 スキーマはGraphQL APIサーバー上にあります。 詳細については、「GraphQL API の検出」を参照してください。

フィールド

フィールドは、オブジェクトから取り出せるデータの単位です。 GraphQL の公式ドキュメントでは、「GraphQL クエリ言語は、基本的にオブジェクトのフィールドを選択するものです」と記載されています。

公式仕様では、フィールドについても次のように記載されています。

すべてのGraphQLの操作は、明確な形のレスポンスが保証されるよう、スカラー値を返すフィールドまで降りた指定をしなければなりません。

これはすなわち、スカラーではないフィールドを返させようとすると、スキーマ検証でエラーが投げられるということです。 すべてのフィールドがスカラー値を返すまで、入れ子になったサブフィールドを追加しなければなりません。

引数

引数は、特定のフィールドに添付されるキー/値ペアの集合です。 フィールドの中には、引数を必要とするものがあります。 ミューテーションでは、引数として入力オブジェクトが要求されます。

実装

GraphQL スキーマでは、_実装_という用語を使用して、オブジェクトがインターフェイスからどのように継承されるかを定義することがあります。

以下は、インターフェース X とオブジェクト Y を定義するスキーマの考案された例です。

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

これは、オブジェクト Y でインターフェース X と同じフィールド/引数/戻り値の型が必要とされる一方で、オブジェクト Y 固有の新たなフィールドを追加する必要があるということです。 (! はそのフィールドが必須であることを意味します。)

リファレンスドキュメントには、以下のような記述があります。

  • オブジェクト には、継承元のインターフェイス [実装] の下に一覧表示されます。

  • インターフェイス には、継承 するオブジェクトが [実装] の下に一覧表示されます。

Connection

コネクションを使うと、同じ呼び出しの一部として関連するオブジェクトに対するクエリを実行できます。 コネクションを使うと、REST APIでは複数の呼び出しを使うような場合に、単一のGraphQL呼び出しを使うことができます。 詳しくは、「RESTからGraphQLへの移行」を参照してください。

点を線でつなぎ、グラフを図示すると役立ちます。 点はノードで、線はエッジです。 コネクションは、ノード間の関係を定義します。

Edge

エッジは、ノード間のコネクションを表します。 コネクションに対してクエリを行うと、そのエッジをトラバースしてノードを取得することになります。 すべての edges フィールドには、node フィールドと cursor フィールドがあります。 カーソルは改ページ位置の自動修正に使用されます。 詳しくは、「GraphQL API 内での改ページ位置の自動修正の使用」を参照してください。

Node

ノード はオブジェクトの総称です。 ノードは直接ルックアップすることもできますが、コネクションを通じて関連するノードにアクセスすることもできます。 スカラーを返さない node を指定する場合は、すべてのフィールドでスカラーが返されるまでサブフィールドを含める必要があります。 REST API によるノード ID へのアクセスと、GraphQL クエリでのそれらの使用について詳しくは、「グローバルノードIDの利用」をご覧ください。

GraphQL APIの発見

GraphQL は内省的です。 これはすなわち、GraphQLスキーマに関する詳細をクエリできるということです。

  • __schema に対してクエリを実行して、スキーマで定義されているすべての型を一覧表示させ、それぞれの詳細を取得します。

    query {
      __schema {
        types {
          name
          kind
          description
          fields {
            name
          }
        }
      }
    }
    
  • __type に対してクエリを実行して、任意の型の詳細を取得します。

    query {
      __type(name: "Repository") {
        name
        kind
        description
        fields {
          name
        }
      }
    }
    
  • GET 要求を使用して、スキーマの_イントロスペクション クエリ_を実行することもできます。

    curl -H "Authorization: bearer TOKEN" https://api.github.com/graphql
    

    : "message": "Bad credentials" または 401 Unauthorized 応答を受け取った場合は、有効なトークンを使用していることを確認してください。 Resource not accessible by personal access token403 エラーが発生した場合は、正しいリソース所有者が fine-grained personal access token のターゲットになっていることを確認します。 たとえば、アクセスしようとしているリポジトリを所有している組織がターゲットになっている必要があります。

    結果はJSONで返されるので、読んだり検索したりしやすくするために、プリティプリントすることをおすすめします。 jq などのコマンドライン ツールを使用したり、この目的のために結果を python -m json.tool にパイプしたりできます。

    あるいは、idl メディア型を渡して、IDL 形式で結果を返してもらうこともできます。これはスキーマの圧縮バージョンです。

    $ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
    https://api.github.com/graphql
    

    : イントロスペクション クエリは、おそらく GraphQL で実行する唯一の GET 要求です。 本文を渡す場合、GraphQL の要求メソッドは、クエリでもミューテーションでも POST です。

    クエリの実行について詳しくは、「GraphQLでの呼び出しの作成」をご覧ください。