GitLab GraphQL APIを使い始めるには
このガイドはGitLabのGraphQL APIの基本的な使い方を示します。
API自体の開発に取り組みたい開発者を対象とした実装の詳細については、GraphQL APIスタイルガイドを参照してください。
走行例
ここに記載されている例は、以下の方法で実行できます:
- コマンドライン。
- GraphiQL。
コマンドライン
GraphQL クエリーは、curl
リクエストで、内部マシンのコマンドラインで実行できます。GraphQL リクエストは、/api/graphql
へのPOST
リクエストとして、クエリーをペイロードとして作成できます。ベアラートークンとして使用する個人アクセストークンを生成することで、リクエストを認可できます。
使用例:
GRAPHQL_TOKEN=<your-token>
curl 'https://gitlab.com/api/graphql' --header "Authorization: Bearer $GRAPHQL_TOKEN" --header "Content-Type: application/json" --request POST --data "{\"query\": \"query {currentUser {name}}\"}"
グラフィカルキューエル
GraphiQL(「グラフィカル」と発音)では、構文のハイライトやオートコンプリートを使って、サーバーのエンドポイントに対して直接クエリを実行することができます。 また、スキーマや型を探索することもできます。
以下の例:
- GitLab 11.0以降に対して直接実行できますが、古いバージョンではサポートされていない型やフィールドもあります。
- GitLab.comでは、これ以上設定しなくても動作します。 ログインしていることを確認し、GraphiQLエクスプローラーに移動します。
ローカルでクエリを実行したい場合、またはセルフマネージドインスタンスでクエリを実行したい場合は、以下のいずれかが必要です:
-
gitlab-org
グループを作成し、その下にgraphql-sandbox
というプロジェクトを作成します。 プロジェクト内にいくつかのイシューを作成します。 - クエリを編集して、
gitlab-org/graphql-sandbox
を自分のグループとプロジェクトに置き換えてください。
詳細はGraphiQLの実行を参照してください。
graphql
機能フラグを有効にしてください。クエリーと突然変異
GitLab GraphQL APIを使用して実行できます:
- データ検索のためのクエリー。
- データの作成、更新、削除のための変異。
id
は一般的にグローバル ID を指し、これはgid://gitlab/Issue/123
の形式のオブジェクト識別子です。GitLabのGraphQL Schemaは、クライアントがクエリできるオブジェクトとフィールド、そして対応するデータ型の概要を示しています。
例: 現在ログインしているユーザーがアクセスできる(上限あり、詳細は後述)、グループgitlab-org
内のすべてのプロジェクト名のみを取得します。
query {
group(fullPath: "gitlab-org") {
id
name
projects {
nodes {
name
}
}
}
}
例:特定のプロジェクトとイシュー#2のタイトルを入手。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issue(iid: "2") {
title
}
}
}
グラフ走査
子ノードを取得する場合は
-
edges { node { } }
構文。 - 短縮形
nodes { }
構文。
その下にあるのが、私たちがトラバースしているグラフであり、それがGraphQLという名前の由来です。
例: プロジェクト(名前のみ)とそのすべてのイシューのタイトルを取得します。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues {
nodes {
title
description
}
}
}
}
クエリの詳細:GraphQLドキュメント
作成者
GitLabアプリケーション(およびGitLab.com)と同じエンジンを使用するため、GitLabにサインインしてGraphiQLを使用する場合、すべてのクエリはサインインしたユーザーとして実行されます。 詳細については、GitLab APIドキュメントを参照してください。
突然変異
ミューテーションはデータに変更を加えます。 レコードの更新、削除、新規作成が可能です。 ミューテーションは通常、InputTypesと変数を使用しますが、ここではどちらも使用しません。
突然変異はあります:
- 入力:例えば、どの絵文字をどのオブジェクトに授与するかなどの引数。
- リターンステートメント。 つまり、成功したときに何を返してほしいか。
- 念のため、何がいけなかったのか必ず聞いてください。
創造の突然変異
例:お茶を飲もう - イシューに:tea:
のリアクション絵文字を追加します。
mutation {
awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
name: "tea"
}) {
awardEmoji {
name
description
unicode
emoji
unicodeVersion
user {
name
}
}
errors
}
}
例: イシューにコメントを追加します(ここではGitLab.com
イシューのIDを使用していますが、内部インスタンスを使用している場合は、書き込み可能なイシューのIDを取得する必要があります)。
mutation {
createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
body: "*sips tea*"
}) {
note {
id
body
discussion {
id
}
}
errors
}
}
変異の更新
作成したメモの結果id
が表示されたら、それをメモしてください。 では、より速く口にできるように編集してみましょう!
mutation {
updateNote(input: { id: "gid://gitlab/Note/<note id>",
body: "*SIPS TEA*"
}) {
note {
id
body
}
errors
}
}
欠失変異
お茶がなくなってしまったので、コメントを削除しましょう。
mutation {
destroyNote(input: { id: "gid://gitlab/Note/<note id>" }) {
note {
id
body
}
errors
}
}
以下のような出力が得られるはずです:
{
"data": {
"destroyNote": {
"errors": [],
"note": null
}
}
}
ノートの詳細を尋ねましたが、もう存在しないので、null
。
変異の詳細:GraphQL Docs.
内省的な質問
クライアントは、内省的なクエリを実行することで、自身のスキーマに関する情報を GraphQL エンドポイントに問い合わせることができます。
GraphiQL Query ExplorerがGraphQLスキーマに関するすべての知識を取得し、オートコンプリートを実行し、インタラクティブなDocs
タブを提供するのは、イントロスペクション・クエリーを通じてです。
例: スキーマ内のすべての型名を取得します。
{
__schema {
types {
name
}
}
}
例: イシューに関連するすべてのフィールドを取得します。kind
は、OBJECT
、SCALAR
、INTERFACE
のように、タイプの列挙値を示します。
query IssueTypes {
__type(name: "Issue") {
kind
name
fields {
name
description
type {
name
}
}
}
}
イントロスペクションの詳細:GraphQLドキュメント
ソート
GitLab のいくつかの GraphQL エンドポイントでは、オブジェクトのコレクションをどのようにソートしたいのかを指定することができます。 スキーマが許可しているものでしかソートすることはできません。
例:イシューを作成日順に並べ替えることができます:
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(sort: created_asc) {
nodes {
title
createdAt
}
}
}
}
ページネーション
ページネーションは、レコードのサブセット(たとえば最初の10件)のみを要求する方法です。 もっと多くのレコードが必要な場合は、サーバーから次の10件を(「次の10件をください」というような形で)再度要求することができます。
デフォルトでは、GitLab の GraphQL API はコレクションの最初の 100 レコードのみを返します。これはfirst
あるいはlast
引数を使うことで変更できます。どちらの引数も値を取るので、first: 10
は最初の 10 レコード、last: 10
は最後の 10 レコードを返します。
例: 最初の2つのイシューのみを取得します(スライシング)。cursor
フィールドは、そのイシューに関連するレコードをさらに取得できる位置を示します。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 2) {
edges {
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
例: 次の 3 を取得します。(カーソル値eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0
は異なる可能性がありますが、上記で返された 2 番目のイシューで返されたcursor
の値です)。
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
edges {
node {
title
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
ページネーションとカーソルに関する詳細:GraphQLドキュメント