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 token で 403 ゚ラヌが発生した堎合は、正しいリ゜ヌス所有者がfine-grained personal access tokenのタヌゲットずなっおいるこずを確認したす。 たずえば、アクセスしようずしおいるリポゞトリを所有しおいる Organization がタヌゲットにされおいる必芁がありたす。

    結果は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での呌び出しの䜜成」を参照しおください。