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の実行を参照してください。

注：GitLab 11.0から12.0を実行している場合、graphql機能フラグを有効にしてください。

クエリーと突然変異

GitLab GraphQL APIを使用して実行できます：

  • データ検索のためのクエリー。
  • データの作成、更新、削除のための変異。
注: 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ドキュメント