このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2021-09-23. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの改善、新機能のためには、最新バージョンのGitHub Enterpriseにアップグレードしてください。 アップグレードに関する支援については、GitHub Enterprise supportに連絡してください。

GraphQLの紹介

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

GraphQLの用語

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

スキーマ

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

フィールド

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

公式の仕様も、フィールドについて述べています。

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

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

引数

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

Implementation

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

以下は、インターフェース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固有の新たなフィールドを追加しているということです。 (!はそのフィールドが必須だという意味です)

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

コネクション

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

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

エッジ

エッジは、ノード間のコネクションを表します。 コネクションに対してクエリを行うと、そのエッジをトラバースしてノードを取得することになります。 すべてのedgesフィールドはnodeフィールドとcursorフィールドを持ちます。 カーソルはページネーションに使われます。

ノード

ノード はオブジェクトの総称です。 ノードは直接ルックアップすることもできますが、コネクションを通じて関連するノードにアクセスすることもできます。 スカラーを返さない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" http(s)://[hostname]/api/graphql

    Note: If you get the response "message": "Bad credentials" or 401 Unauthorized, check that you are using a valid token. 詳しい情報については、「個人アクセストークンを作成する」を参照してください。

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

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

    $ curl -H "Authorization: bearer token" -H "Accept: application/vnd.github.v4.idl" \
    http(s)://[hostname]/api/graphql

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

    クエリの実行に関する詳しい情報については「GraphQLでの呼び出しの作成」を参照してください。

問題がまだ解決していませんか?