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エンドポイントにクエリできます。これらのクエリは、検出および診断ツールとして使用することを目的としています。

開発環境およびテスト環境では、イントロスペクションクエリはライブスキーマに対して実行されます。
本番環境では、イントロスペクションクエリは静的スキーマを返します。
- イントロスペクションクエリは、本番環境でデータをフェッチするために使用しないでください。詳細については、以下を参照してください:
  - GraphQL Introspection in Production
  - Apollo Introspection in Production
- すべてのイントロスペクションクエリは、リクエストメソッドやパラメータに関係なく、同じ静的レスポンスを返します。
- 静的スキーマは、現在のスキーマと一致するように自動的に更新されます。
- イントロスペクションクエリは、2つの静的スキーマファイルのいずれかを返します:
  - public/-/graphql/introspection_result.json: 非推奨フィールドを含む完全なスキーマ。
  - public/-/graphql/introspection_result_no_deprecated.json: 非推奨フィールドのないスキーマ。

スキーマをリクエストするには、リクエスト本文に以下を送信します:

{
  "query": "{ __schema { types { name } } }"
}

非推奨フィールドのないスキーマをリクエストするには、リクエスト本文にremove_deprecated: trueを含めます:

{
  "query": "{ __schema { types { name } } }",
  "remove_deprecated": true
}

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

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

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

イントロスペクションの詳細: 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ドキュメント

ファイルのアップロード

一部のミューテーションは、ファイルアップロードを引数として受け入れます。これらのミューテーションは、GraphQLマルチパートリクエスト仕様を使用します。これにより、GraphQLオペレーションと共にmultipart/form-dataリクエストを使用してファイルを送信できます。

ファイルアップロードをサポートするミューテーションは、Upload型の引数を持ちます。これらのミューテーションは、GraphQL API参照でUploadスカラー型の引数を探すことで特定できます。

ファイルアップロードミューテーションはGraphiQLを介して実行できません。あなたは、コマンドラインツールであるcurl、または互換性のあるGraphQLクライアントライブラリを使用する必要があります。

マルチパートアップロードリクエストには、次の3つの主要な部分があります:

operations: ファイルの値がnullに設定された、GraphQLクエリと変数を含むJSON文字列。
map: ファイルキーをオペレーション内の変数パスにマップするJSONオブジェクト。
mapで使用されるキーによって参照されるファイルフィールド自体。

designManagementUploadミューテーションを使用してイシューにデザインをアップロードするには:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --form 'operations={"query": "mutation ($files: [Upload!]!, $projectPath: ID!, $iid: ID!) { designManagementUpload(input: { projectPath: $projectPath, iid: $iid, files: $files }) { designs { filename } errors } }", "variables": {"files": [null], "projectPath": "<group>/<project>", "iid": "<issue-iid>"}}' \
  --form 'map={"0": ["variables.files.0"]}' \
  --form '0=@/path/to/your/design.png'

workItemsCsvImportミューテーションを使用してCSVファイルから作業アイテムをインポートするには:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --form 'operations={"query": "mutation ($projectPath: ID!, $file: Upload!) { workItemsCsvImport(input: { projectPath: $projectPath, file: $file }) { message errors } }", "variables": {"projectPath": "<group>/<project>", "file": null}}' \
  --form 'map={"0": ["variables.file"]}' \
  --form '0=@/path/to/your/work-items.csv'

単一のリクエストで複数のファイルをアップロードするには、mapとフォームフィールドの両方に追加のエントリを追加します:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --form 'operations={"query": "mutation ($files: [Upload!]!, $projectPath: ID!, $iid: ID!) { designManagementUpload(input: { projectPath: $projectPath, iid: $iid, files: $files }) { designs { filename } errors } }", "variables": {"files": [null, null], "projectPath": "<group>/<project>", "iid": "<issue-iid>"}}' \
  --form 'map={"0": ["variables.files.0"], "1": ["variables.files.1"]}' \
  --form '0=@/path/to/first-design.png' \
  --form '1=@/path/to/second-design.png'

クエリURLを変更する

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

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

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