GitHub の GraphQL API Explorer の使い方

GraphQL API Expolorer とは

GitHub の GraphQL API (API ver.4) を使用すると、GitHub で管理されているリポジトリの情報やユーザーの情報などを、柔軟な GraphQL クエリを使って取得することができます。 しかし、いろいろなクエリ方法が用意されていて、実際にどのような情報が取得できるのかが分かりにくかったりします。 そんなとき便利なのが、GitHub が Web サイトとして用意してくれている、GraphQL API Explorer です。

• GraphQL API Explorer | GitHub Developer Guide

GraphQL API Explorer を使用すると、GraphQL API を使ってどのような情報を取得できるのか、実際にクエリを実行して確かめることができます。 GitHub アカウントでサインインした状態であれば、プライベートリポジトリの情報も取得することができます。 GitHub GraphQL API を利用するアプリケーションを作成するときは、このサイトでどのようなクエリを発行すればよいのかを調べながら作っていくことになると思います。

クエリエディタでは、下記のようなショートカットキーを使用することができます。

• Ctrl + Space … 入力補完
• Ctrl + Enter … 実行

History 機能と Explorer 機能

History ボタンを押すと、過去に実行したクエリをロードすることができます。 クエリに次のように名前を付けておくと、History にその名前が表示されるので、後ほど再利用する予定があれば、わかりやすい名前を付けておくとよいでしょう。

query GetApolloRepo {
  repository(owner: "apollographql", name: "apollo-client") {
    owner {
      login
      url
    }
    name
    url
  }
}

Explorer ボタンを押すと、スキーマ定義に基づいて、入力可能なフィールドをツリー形式で参照することができます（これを使うより、Ctrl + Space による補完の方が便利ですが）。

クエリのパラメータ化 (QUERY VARIABLES)

クエリ文字列の中で、実行のたびに変化させたい部分は変数にしておくと便利です。 次の例では、クエリ実行時に $owner と $name パラメーターを受け取るように定義しています。 String! は、省略できない文字列型パラメーターであることを示しています。

query GetRepo($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    owner {
      login
      url
    }
    name
    url
  }
}

このようなパラメーター付きのクエリを実行するときは、QUERY VARIABLES の入力欄で、次のように JSON 形式で変数の値をセットします。

{
  "owner": "apollographql",
  "name": "apollo-client"
}

呼び出し回数制限に注意 (rateLimit)

GraphQL Explorer では無制限に API を実行できるわけではありません。 現状は GitHub ユーザーごとに、1 時間あたり 5000 ポイントまでの呼び出しを行えるようになっています。 あるクエリで消費したポイントと残りのポイントは、次のように rateLimit フィールドを指定することで調べることができます。

query {
  rateLimit { cost remaining }

  ...残りはいつも通り記述...
}

{
  "data": {
    "rateLimit": {
      "cost": 1,
      "remaining": 4989
    },

    ...
  }
}

上記の結果は、今回のクエリ実行に 1 ポイント消費し、残り 4989 ポイント残っていることを示しています。

• 参考: GitHub GraphQL API の呼び出し回数制限 (rate limit) の情報を取得する

関連記事

• GitHub GraphQL クエリ例: イシュー情報を取得する (search)
• GitHub GraphQL クエリ例: リポジトリの情報を取得する (repository)
• GitHub GraphQL クエリ例: 組織の情報を取得する (organization)
• Node.js で GitHub GraphQL API を使用する (@octokit/graphql)
• GitHub GraphQL のスキーマ情報を取得する
• GitHub GraphQL API の呼び出し回数制限 (rate limit) の情報を取得する
• Apollo Client で GitHub GraphQL API を使う (Node & React)