• 시작하기
  • 대화형 GraphQL 탐색기
  • GraphQL 예제 보기
  • 인증
    • 토큰 인증
      • 헤더 인증
      • 매개변수 인증
      • 토큰 범위
    • 세션 쿠키 인증
• 사용 가능한 최상위 쿼리
  • 다중 쿼리
• 폐기 및 변경
  • 폐지 예시
  • 제거된 아이템 디렉터리
• 제한 사항
  • 최대 쿼리 복잡성
• 스팸으로 감지된 변경 사항 처리

GraphQL API

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.
• Self-Managed형 GitLab 인스턴스에서 https://<your-gitlab-site.com>/-/graphql-explorer로 이동합니다.

추가 정보는 GraphiQL을 참조하십시오.

GraphQL 예제 보기

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

• 감사 보고서 생성
• 이슈 보드 식별
• 사용자 쿼리
• 사용자 정의 이모지 사용

시작하기 페이지에서 GraphQL 쿼리를 사용자 정의하는 다양한 방법을 확인할 수 있습니다.

인증

일부 쿼리는 인증 없이 액세스할 수 있지만 다른 쿼리는 인증이 필요합니다. 항상 변이에는 인증이 필요합니다.

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

• 토큰
• 세션 쿠키

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

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

토큰 인증

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

• OAuth 2.0 토큰
• 개인 액세스 토큰
• 프로젝트 액세스 토큰
• 그룹 액세스 토큰

헤더를 통해 토큰으로 인증 예시:

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 토큰 사용 예시:

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

토큰에는 올바른 범위가 필요합니다.

헤더 인증

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에 액세스하려면 토큰에 올바른 범위가 필요합니다:

세션 쿠키 인증

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 타입에 정의되어 있습니다.

다중 쿼리

GitLab은 쿼리를 단일 요청으로 묶는 다중 쿼리를 지원합니다. 자세한 내용은 다중화를 참조하십시오.

폐기 및 변경

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

그러나 GitLab은 때로는 하위 호환성을 유지하지 않는 방식으로 GraphQL API를 변경할 때가 있습니다. 이러한 변경은 폐기 및 변경으로 간주되며 필드, 인자 또는 스키마의 기타 부분을 제거하거나 이름을 변경하는 것을 포함할 수 있습니다. GitLab은 폐기 및 제거 프로세스를 따릅니다.

폐지 예시

아래 필드들은 서로 다른 소품릴리스에서 폐지되었지만, 둘 다 GitLab 17.0에서 제거되었습니다:

제거된 아이템 디렉터리

이전 릴리스에서 제거된 아이템 디렉터리을 확인하세요.

제한 사항

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

최대 쿼리 복잡성

GitLab GraphQL API는 쿼리의 _복잡성_을 평가합니다. 일반적으로, 더 큰 쿼리는 더 높은 복잡성 점수를 갖습니다. 이 제한은 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 헤더를 설정하여 요청을 재제출합니다.

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"