GraphQL APIのクエリとミューテーションの実行

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このドキュメントでは、GitLab GraphQL APIの基本的な使用方法を説明します。

実行例

ここで説明する例は、以下を使用して実行できます:

GraphiQL

GraphiQL（「グラフィカル」と発音）を使用すると、実際のGraphQLクエリをAPIに対してインタラクティブに実行できます。ハイライトした構文とオートコンプリート機能を備えたUIが用意されているため、スキーマを簡単に調べることができます。

ほとんどの場合、GraphiQLを使用するのが、GitLab GraphQL APIを調べる最も簡単な方法です。

GraphiQLは以下でも使用できます:

GitLab.com。
https://<your-gitlab-site.com>/-/graphql-explorerでのGitLab Self-Managed。

最初にGitLabにサインインして、GitLabアカウントでリクエストを認証します。

使用を開始するには、クエリとミューテーションの例を参照してください。

コマンドライン

ローカルコンピューターのコマンドラインで、curlリクエストでGraphQLクエリを実行できます。リクエストは、クエリをペイロードとして/api/graphqlにPOSTします。ベアラートークンとして使用するパーソナルアクセストークンを生成して、リクエストを認証できます。詳細については、GraphQL認証を参照してください。

例:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

クエリ文字列に文字列をネストするには、データを一重引用符で囲むか、\\で文字列をエスケープします:

curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query": "query {project(fullPath: \"<group>/<subgroup>/<project>\") {jobs {nodes {id duration}}}}"}'
  # or "{\"query\": \"query {project(fullPath: \\\"<group>/<subgroup>/<project>\\\") {jobs {nodes {id duration}}}}\"}"

Railsコンソール

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed、GitLab Dedicated

GraphQLクエリは、Railsコンソールセッションで実行できます。たとえば、プロジェクトを検索するには、次のようにクエリを実行します:

current_user = User.find_by_id(1)
query = <<~EOQ
query securityGetProjects($search: String!) {
  projects(search: $search) {
    nodes {
      path
    }
  }
}
EOQ

variables = { "search": "gitlab" }

result = GitlabSchema.execute(query, variables: variables, context: { current_user: current_user })
result.to_h

クエリとミューテーション

GitLab GraphQL APIを使用すると、以下を実行できます:

データ取得のためのクエリ。
データの作成、更新、削除のためのミューテーション。

GitLab GraphQL APIでは、idはグローバルIDを指します。これは、"gid://gitlab/Issue/123"の形式のオブジェクト識別子です。詳細については、グローバルIDを参照してください。

GitLab GraphQLのスキーマは、クライアントがクエリできるオブジェクトやフィールド、対応するデータ型を示しています。

例: 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にサインインしてGraphiQLを使用すると、すべてのクエリが認証済みユーザーとして実行されます。詳細については、GraphQL認証を参照してください。

ミューテーション

ミューテーションは、データに変更を加えます。新しいレコードを更新、削除、または作成できます。通常、ミューテーションはInputTypeと変数を使用しますが、ここにはどちらも示しません。

ミューテーションには以下があります:

インプット。たとえば、どの絵文字リアクションを追加するか、どのオブジェクトに絵文字リアクションを追加するかなどの引数です。
戻り値の指定。つまり、成功した場合に何を戻したいかです。
エラー。念のため、エラーの詳細を常に確認してください。

作成ミューテーション

例: お茶を飲みましょう。イシューに: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ドキュメント。

プロジェクト設定を更新する

単一のGraphQLミューテーションで複数のプロジェクト設定を更新できます。この例は、CI_JOB_TOKENスコーピングの動作における大きな変更の回避策です。

mutation DisableCI_JOB_TOKENscope {
  projectCiCdSettingsUpdate(input:{fullPath: "<namespace>/<project-name>", inboundJobTokenScopeEnabled: false}) {
    ciCdSettings {
      inboundJobTokenScopeEnabled
    }
    errors
  }
}

イントロスペクションクエリ

クライアントは、イントロスペクションクエリを行うことにより、スキーマに関する情報についてGraphQLエンドポイントにクエリできます。

GraphiQLクエリエクスプローラーは、イントロスペクションクエリを使用して以下を行います:

GitLab GraphQLスキーマに関する知識を取得する。
オートコンプリートを行う。
インタラクティブなDocsタブを提供する。

例: スキーマ内のすべての型名を取得します。

{
  __schema {
    types {
      name
    }
  }
}

例: イシューに関連付けられたすべてのフィールドを取得します。kindは、OBJECT、SCALAR、INTERFACEのような型のenum値を取得します。

query IssueTypes {
  __type(name: "Issue") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}

イントロスペクションの詳細: GraphQLドキュメント

クエリの複雑さ

クエリで算出された複雑さのスコアと制限は、queryComplexityをクエリすることでクライアントに公開できます。

query {
  queryComplexity {
    score
    limit
  }

  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
  }
}

ソート

GitLab GraphQLエンドポイントの一部では、オブジェクトのコレクションをソートする方法を指定できます。スキーマで許可されているものだけでソートできます。

例: イシューは作成日でソートできます:

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
   name
    issues(sort: created_asc) {
      nodes {
        title
        createdAt
      }
    }
  }
}

ページネーション

ページネーションは、最初の10件など、レコードのサブセットのみをリクエストする方法です。さらに必要な場合は、give me the next ten recordsのような形式で、サーバーから次の10件を再度リクエストできます。

デフォルトでは、GitLab GraphQL APIはページごとに100件のレコードを返します。この動作を変更するには、first引数またはlast引数を使用します。どちらの引数も値を受け取ります。first: 10は最初の10件のレコードを返し、last: 10は最後の10件のレコードを返します。ページごとに返されるレコード数には制限があり、通常は100です。

例: 最初の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ドキュメント

クエリURLを変更する

GraphQLリクエストを別のURLに送信する必要がある場合があります。GeoNodeクエリがその例で、セカンダリGeoサイトのURLに対してのみ機能します。

GraphiQL ExplorerでGraphQLリクエストのURLを変更するには、GraphiQLのヘッダー領域（左下の領域、変数があるところ）にカスタムヘッダーを設定します:

{
  "REQUEST_PATH": "<the URL to make the graphQL request against>"
}