正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

GLQL API

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

このAPIを使用して、GitLab Query Language（GLQL）のクエリをプログラムで実行します。GLQLは、プロジェクトやグループを横断して、イシュー、マージリクエスト、エピックなどのGitLabリソースを検索およびフィルタリングするための、簡素化された言語を提供します。

前提条件:

  • グループまたはプロジェクトは、そのデータへのアクセスを許可する必要があります。
  • プライベートグループおよびプロジェクトの場合、適切な権限を持つパーソナルアクセストークンを使用する必要があります。

GLQLクエリを実行する

GitLabリソースを検索およびフィルタリングするために、GLQLクエリを実行します。

POST /glql

サポートされている属性:

属性型必須説明
glql_yaml文字列はいオプションのYAML設定を含むGLQLクエリ。最大サイズ: 10,000バイト（10 KB）。詳細については、クエリ形式を参照してください。
after文字列いいえページネーションのカーソル。次の結果ページをフェッチするには、以前のクエリのdata.pageInfo.endCursor値を使用します。

クエリ形式

glql_yamlパラメータは、queryキーを持つYAML形式を受け入れます:

fields: id,title,author
group: my-group
limit: 10
sort: created desc
query: state = opened

設定オプション

次の設定オプションは、YAMLに含めることができます:

オプション型必須説明
fields文字列いいえ返されるフィールドのカンマ区切りリスト。デフォルトはtitleです。利用可能なフィールドを参照してください。
group文字列いいえクエリのスコープを特定のグループに設定します。projectでは使用できません。クエリでgroupも指定されている場合、クエリ値が優先されます。
limit整数いいえ返す結果の最大数。1～100の間でなければなりません。デフォルトは100です。
project文字列いいえクエリのスコープを特定のプロジェクトに設定します。形式: group/project。クエリでprojectも指定されている場合、クエリ値が優先されます。
sort文字列いいえ結果のソート順。形式: field direction（例: created asc、created desc）。

利用可能なフィールド

fields設定オプションは、GLQLの利用可能なフィールドによって定義されます。

GLQLクエリ構文

クエリの構文は、GLQLによって定義されます。

レスポンス属性

成功した場合、200 OKと次のレスポンス属性を返します:

属性型説明
dataオブジェクトクエリの結果が含まれています。
data.count整数一致する結果の合計数。
data.nodes配列要求されたフィールドを持つ、一致するリソースの配列。
data.pageInfoオブジェクトページネーション情報。
data.pageInfo.endCursor文字列次の結果ページをフェッチするためのカーソル。
data.pageInfo.hasNextPageブール値利用可能な結果がさらにあるかどうかを示します。
data.pageInfo.hasPreviousPageブール値以前の結果が利用可能かどうかを示します。
data.pageInfo.startCursor文字列前の結果ページをフェッチするためのカーソル。
error文字列クエリが失敗した場合のエラーメッセージ。
fields配列フィールド定義の配列。
fields[].key文字列一意のフィールド識別子。
fields[].label文字列人間が読めるフィールド名。
fields[].name文字列類似のフィールドを統合する共通のフィールド名。たとえば、createdキーとcreatedAtキーの名前はcreatedAtです。
successブール値クエリが成功したかどうかを示します。

例: 基本クエリ

グループ内で開かれたイシューを検索します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "query: group = \"my-group\" AND state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

レスポンス例:

{
  "data": {
    "count": 1,
    "nodes": [
      {
        "id": "gid://gitlab/Issue/123",
        "iid": "123",
        "reference": "#123",
        "state": "OPEN",
        "title": "Add an example of GoLang HTTP server",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/123",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjEyMyJ9",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "key": "title",
      "label": "Title",
      "name": "title"
    }
  ],
  "success": true
}

例: フロントマター設定を使用したクエリ

カスタムフィールドとソートで検索:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "fields: id,title,author,state\ngroup: my-group\nlimit: 5\nsort: created desc\nquery: state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

レスポンス例:

{
  "data": {
    "count": 2,
    "nodes": [
      {
        "author": {
          "avatarUrl": "https://www.gravatar.com/avatar/4a17cff4a15e98966063bd203d88aceac682c623e74943a08cdbe0cce87c6d7c?s=80&d=identicon",
          "id": "gid://gitlab/User/123",
          "name": "John Doe",
          "username": "johndoe",
          "webUrl": "https://gitlab.example.com/johndoe"
        },
        "id": "gid://gitlab/Issue/123",
        "iid": "123",
        "reference": "#123",
        "state": "OPEN",
        "title": "Add an example of GoLang HTTP server",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/123",
        "widgets": null
      },
      {
        "author": {
          "avatarUrl": "https://www.gravatar.com/avatar/4a17cff4a15e98966063bd203d88aceac682c623e74943a08cdbe0cce87c6d7c?s=80&d=identicon",
          "id": "gid://gitlab/User/122",
          "name": "Jane Doe",
          "username": "janedoe",
          "webUrl": "https://gitlab.example.com/janedoe"
        },
        "id": "gid://gitlab/Issue/122",
        "iid": "122",
        "reference": "#122",
        "state": "OPEN",
        "title": "HTTP server examples for all programming languages",
        "webUrl": "https://gitlab.example.com/groups/my-group/-/issues/122",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjEyMyJ9",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "key": "id",
      "label": "ID",
      "name": "id"
    },
    {
      "key": "title",
      "label": "Title",
      "name": "title"
    },
    {
      "key": "author",
      "label": "Author",
      "name": "author"
    },
    {
      "key": "state",
      "label": "State",
      "name": "state"
    }
  ],
  "success": true
}

例: プロジェクトスコープを使用したクエリ

特定のプロジェクトで検索:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "query: project = \"my-group/my-project\" AND state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

例: currentUser()関数を使用したクエリ

現在のユーザーに割り当てられたイシューを検索します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "fields: id,title,assignees\nquery: group = \"my-group\" AND assignee = currentUser()"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

レスポンス例:

{
  "data": {
    "count": 1,
    "nodes": [
      {
        "assignees": {
          "nodes": [
            {
              "avatarUrl": "https://www.gravatar.com/avatar/4a17cff4a15e98966063bd203d88aceac682c623e74943a08cdbe0cce87c6d7c?s=80&d=identicon",
              "id": "gid://gitlab/User/123",
              "name": "John Doe",
              "username": "johndoe",
              "webUrl": "https://gitlab.example.com/johndoe"
            }
          ]
        },
        "id": "gid://gitlab/Issue/123",
        "iid": "123",
        "reference": "#123",
        "state": "OPEN",
        "title": "Add an example of GoLang HTTP server",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/123",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjEyMyJ9",
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "key": "id",
      "label": "ID",
      "name": "id"
    },
    {
      "key": "title",
      "label": "Title",
      "name": "title"
    },
    {
      "key": "assignees",
      "label": "Assignees",
      "name": "assignees"
    }
  ],
  "success": true
}

例: 制限とページネーションを使用したクエリ

限られた数の結果を取得し、それらをページネーションします:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "limit: 2\nquery: group = \"my-group\" AND state = opened"
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

レスポンス例:

{
  "data": {
    "count": 68,
    "nodes": [
      {
        "id": "gid://gitlab/Issue/321",
        "iid": "321",
        "reference": "#321",
        "state": "OPEN",
        "title": "Corrupti consectetur impedit non blanditiis hic vitae minus.",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/321",
        "widgets": null
      },
      {
        "id": "gid://gitlab/WorkItem/322",
        "iid": "322",
        "reference": "#322",
        "state": "OPEN",
        "title": "Ipsa cupiditate corrupti vel maxime quasi at assumenda repellat quod.",
        "webUrl": "https://gitlab.example.com/my-group/my-project/-/issues/322",
        "widgets": null
      }
    ],
    "pageInfo": {
      "endCursor": "eyJpZCI6IjIifQ==",
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjEyMyJ9"
    }
  },
  "error": null,
  "fields": [
    {
      "key": "title",
      "label": "Title",
      "name": "title"
    }
  ],
  "success": true
}

次のページをフェッチするには、前のレスポンスのendCursor値を使用します:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "glql_yaml": "limit: 2\nquery: group = \"my-group\" AND state = opened",
    "after": "eyJpZCI6IjIifQ=="
  }' \
  --url "https://gitlab.example.com/api/v4/glql"

レート制限

GLQL APIは、クエリのSHA-256ハッシュに基づいてレート制限を実装します。タイムアウトするクエリは追跡されます。タイムアウトしている特定のクエリの実行頻度が高すぎる場合、そのクエリは一時的にブロックされます。

レート制限が適用されると、APIはエラーメッセージとともに429 Too Many Requestsステータスコードを返します:

{
  "error": "Query temporarily blocked due to repeated timeouts. Please try again later or narrow your search scope."
}

エラー処理

APIは、次のHTTPステータスコードを返します:

ステータスコード説明
200 Successクエリが正常に実行されました。
400 Bad Request無効なクエリ構文、必須パラメータの欠落、または入力がサイズ制限を超えています。
401 Unauthorized認証が必要であるか、認証情報が無効です。
403 Forbidden権限が不十分であるか、必要なOAuthスコープがありません。
429 Too Many Requestsクエリのレート制限を超えました。
500 Internal Server Errorクエリ実行中にサーバーエラーが発生しました。

エラーレスポンスの例

  • 必須パラメータがありません:

    {
  "error": "glql_yaml is missing, glql_yaml is empty"
}

  • 無効なGLQL構文:

    {
  "error": "400 Bad request - Error: Unexpected `invalid syntax @@@ ###`, expected operator (one of IN, =, !=, >, or <)"
}

  • 入力サイズを超えました:

    {
  "error": "400 Bad request - Input exceeds maximum size"
}

  • 存在しないプロジェクト:

    {
  "error": "400 Bad request - Error: Project does not exist or you do not have access to it"
}

  • 存在しないグループ:

    {
  "error": "400 Bad request - Error: Group does not exist or you do not have access to it"
}

  • レート制限を超えました:

    {
  "error": "Query temporarily blocked due to repeated timeouts. Please try again later or narrow your search scope."
}

  • 無効なフィールド

    {
  "error": "Field 'title' doesn't exist on type 'WorkItem' (Did you mean `title`?)"
}

制限と制約

GLQL APIには、次の制限があります:

  • 最大入力サイズ: glql_yamlパラメータの場合、10,000バイト（10 KB）。
  • クエリの最大制限: リクエストあたり100件の結果。
  • デフォルトの制限: 指定されていない場合は100件の結果。
  • ページネーション: 以前のレスポンスのendCursor値を持つafter属性を使用すると、前方ページネーションのみがサポートされます。
  • レート制限: クエリは、クエリのSHA-256ハッシュに基づいてレート制限されます。