GraphQL API
GraphQL는 API를 위한 쿼리 언어입니다. 정확한 데이터만 요청하여 필요한 요청 횟수를 제한할 수 있습니다.
GraphQL 데이터는 타입으로 구성되어 있으므로 클라이언트는 client-side GraphQL libraries를 사용하여 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 쿼리를 사용자 정의하는 다양한 방법을 찾을 수 있습니다.
인증
인증 없이 일부 쿼리에 액세스할 수도 있지만, 다른 경우 인증이 필요할 수 있습니다. 변이(mutation)는 항상 인증을 필요로 합니다.
다음 중 한 가지를 사용하여 인증할 수 있습니다:
인증 정보가 잘못된 경우, GitLab은 상태 코드가 401인 오류 메시지를 반환합니다:
{"errors":[{"message":"유효하지 않은 토큰"}]}
토큰 인증
다음 토큰 중 하나를 사용하여 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 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은 쿼리를 단일 요청으로 묶는 다중화 쿼리를 지원합니다. 자세한 내용은 다중화를 참조하세요.
파기 및 파기 주기
GitLab GraphQL API는 버전이 없습니다 그리고 API의 변경 사항은 주로 하위 호환성을 유지합니다.
그러나 GitLab은 때로는 GraphQL API를 하위 호환되지 않는 방식으로 변경할 수 있습니다. 이러한 변경 사항은 파기 변경 사항으로 간주되며 필드, 인수 또는 스키마의 기타 부분을 제거하거나 이름을 변경할 수 있습니다. 파기 변경 사항을 작성할 때 GitLab은 폐기 및 제거 프로세스를 따릅니다.
파기 변경 사항이 통합 사항에 영향을 미치지 않도록 하려면 다음을 수행해야 합니다:
- 폐기 및 제거 프로세스에 익숙해집니다.
- 미래의 파기 변경 스키마에 대해 자주 API 호출을 확인합니다.
추가 정보는 GitLab 기능 폐기를 참조하십시오.
파기 변경 사항 면제
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 레퍼런스.
- 릴리스 글에서 링크된 폐기 기능 제거 일정.
- GraphQL API의 탐사 쿼리.
폐기 메시지는 해당할 경우 폐기된 스키마 항목에 대한 대체 방법을 제공합니다.
중단 변경을 경험하지 않으려면 가능한 빨리 GraphQL API 호출에서 폐기된 스키마를 제거해야 합니다. 폐기된 스키마 항목 없이 스키마에 대한 API 호출을 확인해야 합니다(#verify-against-the-future-breaking-change-schema).
폐기 예시
다른 소규모 릴리스에서 다음 필드는 폐기되었지만 모두 GitLab 14.0에서 제거되었습니다.
| 폐기된 필드 위치 | 이유 |
|---|---|
| 12.7 | GitLab은 기본적으로 주요 릴리스 당 12개의 소규모 릴리스가 있습니다. 해당 필드가 6개의 더 많은 릴리스에 사용할 수 있도록 보장하기 위해 14.0 주요 릴리스에서 제거되었습니다(13.0이 아님). |
| 13.6 | 14.0에서의 제거는 6개월 동안 사용할 수 있도록 합니다. |
제거된 항목 디렉터리
이전 릴리스에서 제거된 항목 디렉터리을 확인하세요.
제한 사항
다음 제한이 GitLab GraphQL API에 적용됩니다.
| 제한 | 기본값 |
|---|---|
| 페이지 당 최대 크기 | 페이지당 100개 레코드(노드). API의 대부분의 연결에 적용됩니다. 특정 연결에는 더 높거나 낮은 최대 페이지 크기 제한이 적용될 수 있습니다. |
| 최대 쿼리 복잡도 | 인증되지 않은 요청의 경우 200, 인증된 요청의 경우 250. |
| 요청 제한시간 | 30초. |
| 최대 쿼리 크기 | 쿼리 또는 뮤테이션당 10,000자. 이 제한에 도달하면 변수와 fragment를 사용하여 쿼리 또는 뮤테이션 크기를 줄이세요. 마지막 수단으로 공백을 제거하세요. |
최대 쿼리 복잡도
GitLab GraphQL 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헤더를 설정하여 요청을 다시 제출합니다.
--data-binary가 사용됩니다.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: \"제목\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"
도움말