이 API를 사용하여 GitLab 쿼리 언어(GLQL) 쿼리를 프로그래밍 방식으로 실행합니다. GLQL은 프로젝트 및 그룹 전체에서 이슈, 머지 요청, 에픽과 같은 GitLab 리소스를 검색하고 필터링하기 위한 단순화된 쿼리 언어를 제공합니다.

사전 요건:

• 그룹 또는 프로젝트가 해당 데이터에 대한 접근을 허용해야 합니다.
• 비공개 그룹 및 프로젝트의 경우 적절한 권한이 있는 개인 액세스 토큰을 사용해야 합니다.

GLQL 쿼리 실행#

GitLab 리소스를 검색하고 필터링하기 위한 GLQL 쿼리를 실행합니다.

POST /glql

지원되는 속성:

쿼리 형식#

glql_yaml 파라미터는 query 키가 있는 YAML 형식을 허용합니다:

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

구성 옵션#

YAML에는 다음 구성 옵션을 포함할 수 있습니다:

사용 가능한 필드#

fields 구성 옵션은 GLQL의 사용 가능한 필드에 의해 정의됩니다.

GLQL 쿼리 구문#

쿼리 구문은 GLQL에 의해 정의됩니다.

응답 속성#

성공하면 200 OK와 다음 응답 속성을 반환합니다:

예시: 기본 쿼리#

그룹에서 열린 이슈 검색:

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 상태 코드를 반환합니다:

오류 응답 예시#

• 필수 파라미터 누락:

  {
    "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 해시를 기반으로 속도 제한됩니다.

관련 항목#

• GLQL 쿼리 언어 문서
• REST API 인증
• OAuth 2.0 인증