GraphQL API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated

GraphQL는 API를 위한 쿼리 언어입니다. 필요한 정확한 데이터를 요청할 수 있으며, 따라서 필요한 요청 수를 제한할 수 있습니다.

GraphQL 데이터는 타입으로 배열되어 있으므로 클라이언트는 클라이언트 측 GraphQL 라이브러리를 사용하여 API를 소비하고 수동 파싱을 피할 수 있습니다.

GraphQL API는 버전이 없습니다.

시작하기

GitLab GraphQL API에 처음 오셨다면 GitLab GraphQL API 시작하기를 참조하세요.

GraphQL API 참조에서 사용 가능한 리소스를 확인할 수 있습니다.

GitLab GraphQL API 엔드포인트는 /api/graphql에 위치합니다.

대화형 GraphQL 탐색기

대화형 GraphQL 탐색기를 사용하여 GraphQL API를 탐색해 보세요:

  • GitLab.com에서.
  • https://<your-gitlab-site.com>/-/graphql-explorer에서 자체 관리 GitLab 인스턴스에서.

자세한 정보는 GraphiQL을 참조하세요.

GraphQL 예제 보기

GitLab.com의 공개 프로젝트에서 데이터를 가져오는 샘플 쿼리로 작업할 수 있습니다:

시작하기 페이지에는 GraphQL 쿼리를 사용자 정의하는 다양한 방법이 포함되어 있습니다.

인증

일부 쿼리는 인증 없이 접근할 수 있지만, 다른 쿼리는 인증이 필요합니다. 변이는 항상 인증이 필요합니다.

다음 중 하나를 사용하여 인증할 수 있습니다:

인증 정보가 유효하지 않으면 GitLab은 401 상태 코드와 함께 오류 메시지를 반환합니다:

{"errors":[{"message":"Invalid token"}]}

토큰 인증

  • 인증 방법 제한이 도입되었습니다 GitLab 17.0에서 플래그 이름이 graphql_minimal_auth_methods로 설정되었으며 GitLab 17.0.3 및 GitLab 16.11.5에 되돌려졌습니다. 기본적으로 17.0에서 비활성화됩니다.
  • 기본적으로 17.0.3 및 16.11.5에서 플래그가 활성화되므로 이러한 버전 및 이후 버전에서 제한이 적용됩니다.

다음 토큰 중 하나를 사용하여 GraphQL API에 인증할 수 있습니다:

요청 헤더나 파라미터로 토큰을 전달하여 인증하세요.

토큰은 올바른 스코프가 필요합니다.

헤더 인증

Authorization: Bearer <token> 요청 헤더를 사용한 토큰 인증의 예:

curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer <token>" \
     --header "Content-Type: application/json" --request POST \
     --data "{\"query\": \"query {currentUser {name}}\"}"
매개변수 인증

access_token 매개변수에서 OAuth 2.0 토큰을 사용하는 예:

curl "https://gitlab.com/api/graphql?access_token=<oauth_token>" \
     --header "Content-Type: application/json" --request POST \
     --data "{\"query\": \"query {currentUser {name}}\"}"

private_token 매개변수를 사용하여 개인, 프로젝트 또는 그룹 액세스 토큰을 전달할 수 있습니다:

curl "https://gitlab.com/api/graphql?private_token=<access_token>" \
     --header "Content-Type: application/json" --request POST \
     --data "{\"query\": \"query {currentUser {name}}\"}"
토큰 범위

토큰은 GraphQL API에 접근하기 위해 올바른 범위를 가져야 합니다:

범위 접근
read_api API를 읽기 전용으로 접근할 수 있습니다. 쿼리에 충분합니다.
api API에 읽기 및 쓰기 접근을 부여합니다. 변형에 필요합니다.

세션 쿠키 인증

메인 GitLab 애플리케이션에 로그인하면 _gitlab_session 세션 쿠키가 설정됩니다.

대화형 GraphQL 탐색기와 GitLab 자체의 웹 프론트엔드는 이 인증 방식을 사용합니다.

객체 식별자

GitLab GraphQL API는 식별자의 혼합을 사용합니다.

전역 ID, 전체 경로 및 내부 ID(IID)가 GitLab GraphQL API에서 인수로 사용되지만, 종종 스키마의 특정 부분이 이들을 동시에 수용하지는 않습니다.

역사적으로 GitLab GraphQL API는 이에 대한 일관성이 없었지만, 일반적으로 다음을 기대할 수 있습니다:

  • 객체가 프로젝트, 그룹 또는 네임스페이스인 경우 객체의 전체 경로를 사용합니다.
  • 객체가 IID를 가진 경우 전체 경로와 IID의 조합을 사용합니다.
  • 기타 객체의 경우 전역 ID를 사용합니다.

예를 들어, 전체 경로 "gitlab-org/gitlab"로 프로젝트를 찾기:

{
  project(fullPath: "gitlab-org/gitlab") {
    id
    fullPath
  }
}

다른 예, 프로젝트의 전체 경로 "gitlab-org/gitlab"와 이슈의 IID "1"로 이슈 잠금:

mutation {
  issueSetLocked(input: { projectPath: "gitlab-org/gitlab", iid: "1", locked: true }) {
    issue {
      id
      iid
    }
  }
}

Global ID로 CI 러너를 찾는 예:

{
  runner(id: "gid://gitlab/Ci::Runner/1") {
    id
  }
}

역사적으로 GitLab GraphQL API는 전체 경로 및 IID 필드와 인수의 유형에 대해 일관성이 없었지만, 일반적으로:

  • 전체 경로 필드와 인수는 GraphQL ID 유형입니다.
  • IID 필드와 인수는 GraphQL String 유형입니다.

전역 ID

GitLab GraphQL API에서 id라는 이름의 필드나 인수는 거의 항상 전역 ID이며 데이터베이스 기본 키 ID는 아닙니다. GitLab GraphQL API의 전역 ID는 "gid://gitlab/"로 시작합니다. 예를 들어, "gid://gitlab/Issue/123".

전역 ID는 일부 클라이언트 측 라이브러리에서 캐싱 및 가져오기를 위해 사용되는 규칙입니다.

GitLab 전역 ID는 변경될 수 있습니다. 변경되는 경우, 구식 전역 ID를 인수로 사용하는 것은 더 이상 지원되지 않으며 사용 중단 및 파괴적 변경 과정에 따라 지원됩니다.

캐시된 전역 ID가 GitLab GraphQL 사용 중단 주기를 초과하여 유효할 것이라고 기대해서는 안 됩니다.

사용 가능한 최상위 쿼리

모든 쿼리에 대한 최상위 진입점은 GraphQL 참조의 Query type에서 정의됩니다.

멀티플렉스 쿼리

GitLab은 여러 쿼리를 단일 요청으로 배치하는 것을 지원합니다. 자세한 내용은 Multiplex를 참조하십시오.

중단 변경 사항

GitLab GraphQL API는 버전이 없는이며, API에 대한 변경 사항은 주로 이전 호환성이 있습니다.

그러나 GitLab은 때때로 이전 호환성이 없는 방식으로 GraphQL API를 변경합니다. 이러한 변경 사항은 중단 변경 사항으로 간주되며, 필드, 인수 또는 스키마의 다른 부분을 제거하거나 이름을 변경하는 것을 포함할 수 있습니다.

중단 변경 사항을 만들 때 GitLab은 사용 중지 및 제거 프로세스를 따릅니다.

중단 변경 사항이 귀하의 통합에 영향을 주는 것을 피하려면 다음을 수행해야 합니다:

자세한 내용은 GitLab 기능 사용 중지를 참조하십시오.

중단 변경 사항 면제

GraphQL API 참조에서 실험으로 레이블이 지정된 스키마 항목은 사용 중지 프로세스에서 면제됩니다. 이러한 항목은 사전 통보 없이 언제든지 제거되거나 변경될 수 있습니다.

기능 플래그 뒤에 있는 필드와 기본적으로 비활성화된 필드는 사용 중지 및 제거 프로세스를 따르지 않습니다. 이러한 필드는 사전 통보 없이 언제든지 제거될 수 있습니다.

경고:
GitLab은 사용 중지 및 제거 프로세스를 따르기 위해 모든 노력을 기울입니다.
GitLab은 중요한 보안 또는 성능 문제를 패치하기 위해 중단 변경 사항 프로세스가 상당한 위험을 초래할 경우 GraphQL API에 즉각적인 중단 변경 사항을 적용할 수 있습니다.

향후 중단 변경 스키마에 대비하여 확인

모든 사용 중지된 항목이 이미 제거된 것으로 가정하고 GraphQL API를 호출할 수 있습니다.
이렇게 하면 항목이 실제로 스키마에서 제거되기 전에 중단 변경 릴리스를 미리 확인할 수 있습니다.

이러한 호출을 하려면 GraphQL API 엔드포인트에 remove_deprecated=true 쿼리 매개변수를 추가하십시오. 예를 들어, GitLab.com에서의 GraphQL에 대해 https://gitlab.com/api/graphql?remove_deprecated=true를 사용하십시오.

사용 중지 및 제거 프로세스

GitLab GraphQL API의 사용 중지 및 제거 프로세스는 광범위한 GitLab 사용 중지 프로세스와 일치합니다.

GitLab GraphQL API에서 제거될 부분은 먼저 사용 중지되지만 최소 6개 릴리스 동안 여전히 사용할 수 있습니다. 그런 다음 다음 XX.0 주요 릴리스 중에 완전히 제거됩니다.

항목은 다음에서 사용 중지로 표시됩니다:

사용 중지 메시지는 사용 중지된 스키마 항목에 대한 대안을 제공합니다(해당되는 경우).

중단 변경 사항을 경험하지 않으려면 가능한 한 빨리 GraphQL API 호출에서 사용 중지된 스키마를 제거해야 합니다.
또한 사용 중지된 스키마 항목이 없는 스키마에 대해 API 호출을 확인하십시오.

사용 중단 예시

다음 필드는 다양한 소규모 릴리즈에서 사용 중단되었지만, 둘 모두 GitLab 17.0에서 제거되었습니다:

사용 중단된 필드 이유
15.7 GitLab은 전통적으로 주요 릴리즈당 12개의 소규모 릴리즈를 가지고 있습니다. 이 필드가 6개 릴리즈에서 사용할 수 있도록 보장하기 위해, 17.0 주요 릴리즈에서 제거됩니다(16.0이 아닙니다).
16.6 17.0에서 제거되면 사용 가능 기간이 6개월로 제한됩니다.

제거된 항목 목록

이전 릴리즈에서 제거된 항목 목록을 확인하세요.

한계

다음 한계는 GitLab GraphQL API에 적용됩니다.

한계 기본값
최대 페이지 크기 페이지당 100 레코드(노드). 대부분의 연결에 적용됩니다. 특정 연결은 더 높거나 낮은 최대 페이지 크기 한계를 가질 수 있습니다.
최대 쿼리 복잡성 인증되지 않은 요청에 대해 200, 인증된 요청에 대해 250.
최대 쿼리 크기 쿼리나 변이당 10,000자. 이 한계에 도달하면 변수와 조각을 사용하여 쿼리나 변이 크기를 줄이세요. 마지막 수단으로 공백을 제거하세요.
비율 한계 GitLab.com에 대해, GitLab.com 전용 비율 한계를 참조하세요.
요청 시간 초과 30초.

최대 쿼리 복잡성

GitLab GraphQL API는 쿼리의 복잡성 점수를 평가합니다. 일반적으로 더 큰 쿼리는 더 높은 복잡성 점수를 가집니다. 이 한계는 API가 전체 성능에 부정적인 영향을 미칠 수 있는 쿼리를 수행하는 것으로부터 보호하기 위해 설계되었습니다.

쿼리의 복잡성 점수와 요청의 한계에 대해 쿼리할 수 있습니다.

쿼리가 복잡성 한계를 초과하면 오류 메시지가 반환됩니다.

일반적으로 쿼리의 각 필드는 복잡성 점수에 1을 추가하지만, 특정 필드에 따라 더 높거나 낮을 수 있습니다. 때로는 특정 인수를 추가하면 쿼리의 복잡성이 증가할 수도 있습니다.

스팸으로 감지된 변이 해결

GraphQL 변이는 스팸으로 감지될 수 있습니다. 변이가 스팸으로 감지되면:

  • CAPTCHA 서비스가 구성되지 않은 경우, GraphQL 최상위 오류가 발생합니다. 예를 들어:

    {
  "errors": [
    {
      "message": "요청 거부됨. 스팸 감지됨",
      "locations": [ { "line": 6, "column": 7 } ],
      "path": [ "updateSnippet" ],
      "extensions": {
        "spam": true
      }
    }
  ],
  "data": {
    "updateSnippet": {
      "snippet": null
    }
  }
}
  • CAPTCHA 서비스가 구성된 경우, 다음과 같은 응답을 받습니다:
    • needsCaptchaResponse가 true로 설정됩니다.
    • spamLogId와 captchaSiteKey 필드가 설정됩니다.

    예를 들어:

    {
  "errors": [
    {
      "message": "요청 거부됨. CAPTCHA 도전 과제를 해결하고 다시 시도하세요",
      "locations": [ { "line": 6, "column": 7 } ],
      "path": [ "updateSnippet" ],
      "extensions": {
        "needsCaptchaResponse": true,
        "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI",
        "spamLogId": 67
      }
    }
  ],
  "data": {
    "updateSnippet": {
      "snippet": null,
    }
  }
}

  • captchaSiteKey를 사용하여 적절한 CAPTCHA API를 통해 CAPTCHA 응답 값을 얻습니다.
    오직 Google reCAPTCHA v2만 지원됩니다.

  • X-GitLab-Captcha-Response와 X-GitLab-Spam-Log-Id 헤더가 설정된 상태로 요청을 다시 제출합니다.

참고: GitLab GraphiQL 구현은 헤더 전달을 허용하지 않으므로, 이를 cURL 쿼리로 작성해야 합니다. --data-binary는 JSON 내장 쿼리에서 이스케이프된 큰따옴표를 올바르게 처리하기 위해 사용됩니다.

export CAPTCHA_RESPONSE="<CAPTCHA 서비스에서 얻은 CAPTCHA 응답>"
export SPAM_LOG_ID="<초기 REST 응답에서 얻은 spam_log_id>"
curl --header "Authorization: Bearer $PRIVATE_TOKEN" --header "Content-Type: application/json" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" --request POST --data-binary '{"query": "mutation {createSnippet(input: {title: \"Title\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"