• 시작하기
  • 대화형 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에서.
• 자체 호스팅되는 GitLab 인스턴스에서 https://<your-gitlab-site.com>/-/graphql-explorer.

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

GraphQL 예시 보기

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

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

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

인증

일부 쿼리에는 인증이 필요하지 않지만, 다른 쿼리에는 인증이 필요합니다. 변형은 항상 인증이 필요합니다.

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

• 토큰
• 세션 쿠키

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

{"errors":[{"message":"유효하지 않은 토큰"}]}

토큰 인증

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

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

토큰을 헤더로 전달하거나 매개변수로 전달하여 인증합니다.

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

헤더 인증

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의 사용은 향후 GitLab GraphQL 폐기 및 변경 프로세스에 따라 사용이 중지되며, 캐시된 글로벌 ID가 GitLab GraphQL 폐기 주기 이후에 유효할 것으로 기대해서는 안 됩니다.

이용 가능한 최상위 쿼리

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

다중 쿼리

GitLab은 쿼리를 단일 요청으로 묶는 다중 쿼리를 지원합니다. 자세한 정보는 Multiplex를 참조하세요.

판올림 변경

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

그러나 GitLab은 때때로 GraphQL API를 하위 호환성이 없는 방식으로 변경하기도 합니다. 이러한 변경 사항은 판올림 변경으로 간주되며 필드, 인수 또는 다른 스키마 부분 제거 또는 이름 변경을 포함할 수 있습니다. 판올림 변경을 수행할 때 GitLab은 폐기 및 삭제 프로세스를 따릅니다.

판올림 변경이 통합에 영향을 미치지 않도록 하려면 다음을 해야 합니다:

• 폐기 및 삭제 프로세스를 숙지하세요.
• 미래의 판올림 변경 스키마에 대해 API 호출을 자주 확인하세요.

더 많은 정보는 GitLab 기능의 폐기를 참조하세요.

판올림 변경 면제

GraphQL API 레퍼런스에 있는 실험으로 표시된 스키마 항목은 폐기 프로세스의 면제 대상입니다. 이러한 항목은 사전 통지 없이 언제든지 제거하거나 변경할 수 있습니다.

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

경고: GitLab은 폐기 및 삭제 프로세스를 따르기위한 최선을 다합니다. GitLab은 폐기 프로세스가 중대한 리스크를 초래할 경우 중요한 보안 또는 성능 문제를 해결하기 위해 GraphQL API에 대해 즉시 판올림 변경을 가할 수 있습니다.

미래의 판올림 변경 스키마 확인

• GitLab 15.6에서 도입됨.

모든 폐기된 항목이 이미 스키마에서 제거된 것으로 API 호출을 수행할 수 있습니다. 이렇게 하면 판올림 변경 릴리스 앞에서 해당 항목이 실제로 스키마에서 제거되기 전에 API 호출을 확인할 수 있습니다.

이러한 호출을 수행하려면 GraphQL API 엔드포인트에 remove_deprecated=true 쿼리 매개변수를 추가하세요. 예를 들어 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 호출을 확인해야 합니다.

폐기 예시

다른 마이너 릴리스에서 폐기된 다음 필드는 모두 GitLab 14.0에서 제거되었습니다:

제거된 항목 목록

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

제한 사항

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

최대 쿼리 복잡성

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 $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: \"제목\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"