GraphQL API

Tier: Free, Premium, Ultimate Offering: GitLab.com, 자체 관리, 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에서.
자체 관리형 GitLab 인스턴스에서 https://<your-gitlab-site.com>/-/graphql-explorer.

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

GraphQL 예시 보기

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

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

인증

일부 쿼리는 인증 없이 액세스할 수 있지만, 기타 쿼리는 인증이 필요합니다. 변형은 항상 인증을 필요로 합니다.

토큰
세션 쿠키 둘 중 하나를 사용하여 인증할 수 있습니다.

인증 정보가 잘못된 경우, GitLab은 상태 코드가 401인 오류 메시지를 반환합니다:

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

토큰 인증

GitLab 17.0에서 소개된 graphql_minimal_auth_methods라는 플래그로 구성한 인증 방법의 제한 사항 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}}\"}"

매개변수 인증

OAuth 2.0 토큰을 access_token 매개변수를 사용하여 예시:

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
    }
  }
}

글로벌 ID를 사용하여 CI 러너를 찾는 예시:

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

Global IDs

GitLab GraphQL API에서 id라는 필드나 인자는 거의 항상 Global ID이며 절대로 데이터베이스 기본 키 ID가 아닙니다. GitLab GraphQL API의 Global ID는 일반적으로 "gid://gitlab/"로 시작합니다. 예를 들어 "gid://gitlab/Issue/123"입니다.

Global ID는 일부 클라이언트 측 라이브러리에서의 캐싱 및 검색에 사용되는 관례입니다.

GitLab Global ID는 변경될 수 있습니다. 변경된 경우 이전 Global ID를 사용하는 것은 인수로 사용되지만 지원이 종료되었으며 사용 중단 및 파기 변경 프로세스에 따라 지원됩니다. 캐시된 Global ID가 GitLab GraphQL 사용 중단 주기 이후에 유효할 것으로 기대해서는 안 됩니다.

사용 가능한 최상위 쿼리

모든 쿼리의 최상위 진입점은 GraphQL 레퍼런스의 Query 유형에 정의되어 있습니다.

다중화 쿼리

GitLab은 쿼리를 단일 요청으로 배치하는 것을 지원합니다. 자세한 정보는 다중화를 참조하십시오.

Breaking changes

GitLab GraphQL API는 버전없음이며 API의 변경 사항은 주로 하위 호환성을 유지합니다.

그러나 GitLab은 때로는 하위 호환성이 없는 방식으로 GraphQL API를 변경합니다. 이러한 변경 사항은 파기 변경으로 간주되며 필드, 인자 또는 스키마의 다른 부분을 제거하거나 이름을 변경할 수 있습니다. GitLab은 파기 및 제거 프로세스를 따릅니다(사용 중단 및 파기 프로세스).

파기 변경이 통합에 영향을 미치지 않도록 하려면 다음과 같이 해야 합니다:

사용 중단 및 파기 프로세스에 대해 자세히 알아보십시오.
미래의 파기 변경 스키마에 대해 자주 API 호출을 확인하십시오.

자세한 내용은 GitLab 기능의 사용 중단을 참조하십시오.

파기 변경 면제 사항

GraphQL API 레퍼런스에서 실험으로 표시된 스키마 항목은 사용 중단 프로세스에서 면제됩니다. 이러한 항목은 언제든지 알림 없이 제거하거나 변경할 수 있습니다.

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

경고: GitLab은 사용 중단 및 제거 프로세스를 준수하기 위해 최선을 다합니다. 그러나 중요한 보안 또는 성능 문제를 해결하기 위해 사용 중단 프로세스가 중대한 위험을 초래할 경우 GitLab은 GraphQL API에 대한 즉시적인 변경 사항을 가할 수 있습니다.

미래의 파기 변경 스키마에 대한 확인

GitLab 15.6에서 도입되었습니다.

미래의 파기 변경 릴리스(deprecation and removal process) 이전에 모든 사용되지 않은 항목이 이미 제거되었다는 가정하에 GraphQL API를 호출할 수 있습니다. 이렇게 하면 실제로 스키마에서 항목이 제거되기 전에 API 호출을 확인할 수 있습니다.

이러한 호출을 수행하려면 remove_deprecated=true 쿼리 매개변수를 GraphQL API 엔드포인트에 추가하십시오. 예: https://gitlab.com/api/graphql?remove_deprecated=true (GitLab.com의 GraphQL의 경우).

사용 중단 및 파기 프로세스

GitLab GraphQL API의 사용 중단 및 파기 프로세스는 더 넓은 GitLab의 사용 중단 프로세스와 일치합니다.

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

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

스키마.
GraphQL API 레퍼런스.
릴리스 포스트에서 연결된 사용 중단 기능 제거 일정.
GraphQL API의 내기 질의.

사용 중단 메시지는 사용 중단된 스키마 항목에 대한 대체 항목을 제공합니다(적용 가능한 경우).

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

사용 중단 예시

다른 소수 릴리스에서 사용 중단된 다음 필드는 모두 GitLab 17.0에서 제거되었습니다:

사용 중단된 필드 릴리스	이유
15.7	일반적으로 GitLab은 주요 릴리스 당 12개의 소수 릴리스가 있습니다. 필드가 6개의 릴리스 더 사용 가능하도록 하기 위해 17.0 주요 릴리스에서 제거됩니다 (16.0이 아닌).
16.6	17.0에서의 제거로 6개월 동안 사용할 수 있습니다.

제거된 항목 목록

이전 릴리스에서 제거된 항목 목록을 확인하십시오(removed_items.md).

제한

다음 제한 사항이 GitLab GraphQL API에 적용됩니다.

제한	기본값
최대 페이지 크기	페이지당 100개 레코드(노드)입니다. API의 대부분의 연결에 해당됩니다. 특정 연결은 더 높거나 낮은 최대 페이지 크기 제한을 가질 수 있습니다.
최대 쿼리 복잡성	인증되지 않은 요청에 대해 200, 인증된 요청에 대해 250입니다.
최대 쿼리 크기	쿼리 또는 변이당 10,000개 문자입니다. 이 한도를 초과하면 변수 및 fragment를 사용하여 쿼리 또는 변이 크기를 줄여야 합니다. 마지막 수단으로 공백을 제거하십시오.
속도 제한	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 응답에서 얻은 스팸 로그 ID>"
curl --header "Authorization: Bearer $개인_토큰" --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: \"제목\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"

GraphQL API

시작하기

대화형 GraphQL 탐색기

GraphQL 예시 보기

인증

토큰 인증

헤더 인증

매개변수 인증

토큰 범위

세션 쿠키 인증

객체 식별자

Global IDs

사용 가능한 최상위 쿼리

다중화 쿼리

Breaking changes

파기 변경 면제 사항

미래의 파기 변경 스키마에 대한 확인

사용 중단 및 파기 프로세스

사용 중단 예시

제거된 항목 목록

제한

최대 쿼리 복잡성

스팸으로 감지된 변이 해결하기

도움말

기능 사용 가능성과 제품 평가판

도움받기