GraphQL API 쿼리 및 변형 실행
이 가이드는 GitLab GraphQL API의 기본 사용법을 보여줍니다.
GraphQL API 스타일 가이드를 읽고 API 개발 작업을 원하는 개발자를 위한 구현 세부 사항을 확인하세요.
실행 예시
여기에 문서화된 예시는 다음을 사용하여 실행할 수 있습니다:
GraphiQL
GraphiQL(발음: “그래픽컬”)은 API에 대한 실제 GraphQL 쿼리를 상호작용적으로 실행할 수 있게 해줍니다.
구문 강조 및 자동 완성이 있는 UI를 제공하여 스키마 탐색이 더 쉬워집니다.
대부분의 사람들에게 GraphiQL을 사용하는 것이 GitLab GraphQL API를 탐색하는 가장 쉬운 방법입니다.
GraphiQL을 사용할 수 있습니다:
- GitLab.com에서.
-
https://<your-gitlab-site.com>/-/graphql-explorer에서 자가 관리 GitLab 인스턴스에서.
GitLab 계정을 사용하여 요청을 인증하려면 먼저 GitLab에 로그인하세요.
시작하려면 예제 쿼리 및 변형을 참조하세요.
명령줄
로컬 컴퓨터의 명령줄에서 curl 요청으로 GraphQL 쿼리를 실행할 수 있습니다.
요청은 /api/graphql에 POST 방식으로 쿼리를 페이로드로 보냅니다.
개인 액세스 토큰을 생성하여 베어러 토큰으로 사용할 수 있습니다.
GraphQL 인증에 대해 자세히 읽어보세요.
예시:
GRAPHQL_TOKEN=<your-token>
curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" --request POST \
--data "{\"query\": \"query {currentUser {name}}\"}"
쿼리 문자열에 문자열을 중첩하려면, 데이터를 단일 인용 부호로 감싸거나 문자열을 \\로 이스케이프하세요:
curl "https://gitlab.com/api/graphql" --header "Authorization: Bearer $GRAPHQL_TOKEN" \
--header "Content-Type: application/json" --request POST \
--data '{"query": "query {project(fullPath: \"<group>/<subgroup>/<project>\") {jobs {nodes {id duration}}}}"}'
# 또는 "{\"query\": \"query {project(fullPath: \\\"<group>/<subgroup>/<project>\\\") {jobs {nodes {id duration}}}}\"}"
Rails 콘솔
GraphQL 쿼리는 Rails 콘솔 세션에서 실행할 수 있습니다. 예를 들어 프로젝트를 검색하려면:
current_user = User.find_by_id(1)
query = <<~EOQ
query securityGetProjects($search: String!) {
projects(search: $search) {
nodes {
path
}
}
}
EOQ
variables = { "search": "gitlab" }
result = GitlabSchema.execute(query, variables: variables, context: { current_user: current_user })
result.to_h
쿼리 및 변형
GitLab GraphQL API를 사용하여 다음을 수행할 수 있습니다:
- 데이터 검색을 위한 쿼리.
- 변형 데이터를 생성, 업데이트 및 삭제하기 위한.
GitLab GraphQL 스키마는 클라이언트가 쿼리할 수 있는 객체 및 필드와 해당 데이터 유형을 개요합니다.
예시: 현재 인증된 사용자가 접근할 수 있는 모든 프로젝트의 이름만 가져옴(제한 포함) gitlab-org 그룹에서.
query {
group(fullPath: "gitlab-org") {
id
name
projects {
nodes {
name
}
}
}
}
예시: 특정 프로젝트와 이슈 #2의 제목을 가져옴.
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issue(iid: "2") {
title
}
}
}
그래프 탐색
자식 노드를 검색할 때 다음을 사용하세요:
-
edges { node { } }구문. - 짧은 형태
nodes { }구문.
모두 그래프를 탐색하고 있습니다. 이로 인해 GraphQL이라는 이름이 붙여졌습니다.
예제: 프로젝트의 이름과 모든 이슈의 제목을 가져옵니다.
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues {
nodes {
title
description
}
}
}
}
쿼리에 대한 더 많은 정보: GraphQL 문서
권한
GitLab에 로그인하고 GraphiQL을 사용하는 경우, 모든 쿼리는 인증된 사용자인 당신으로 수행됩니다. 더 많은 정보는 GraphQL 인증을 읽어보세요.
변형
변형은 데이터에 변경을 가합니다. 우리는 업데이트, 삭제 또는 새로운 기록을 생성할 수 있습니다.
변형은 일반적으로 InputTypes와 변수를 사용하며, 둘 다 여기에는 나타나지 않습니다.
변형은 다음을 가집니다:
- 입력. 예를 들어, 추가하고 싶은 이모지 반응과 어느 객체에 추가할지를 지정하는 인자입니다.
- 반환 구문. 성공 시 받고 싶은 내용을 의미합니다.
- 오류. 항상 무엇이 잘못되었는지 요청하세요. 만일을 대비해서입니다.
생성 변형
예제: 차 한 잔 - 이슈에 :tea: 반응 이모지를 추가합니다.
mutation {
awardEmojiAdd(input: { awardableId: "gid://gitlab/Issue/27039960",
name: "tea"
}) {
awardEmoji {
name
description
unicode
emoji
unicodeVersion
user {
name
}
}
errors
}
}
예제: 이슈에 댓글을 추가합니다. 이 예제에서는 GitLab.com 이슈의 ID를 사용합니다. 로컬 인스턴스를 사용하는 경우, 작성할 수 있는 이슈의 ID를 가져와야 합니다.
mutation {
createNote(input: { noteableId: "gid://gitlab/Issue/27039960",
body: "*sips tea*"
}) {
note {
id
body
discussion {
id
}
}
errors
}
}
업데이트 변형
생성한 노트의 결과 id를 볼 때, 이를 기록해두세요. 더 빠르게 마시는 것으로 수정해봅시다.
mutation {
updateNote(input: { id: "gid://gitlab/Note/<note ID>",
body: "*SIPS TEA*"
}) {
note {
id
body
}
errors
}
}
삭제 변형
댓글을 삭제합시다. 우리의 차가 다 떨어졌습니다.
mutation {
destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) {
note {
id
body
}
errors
}
}
다음과 같은 출력 결과를 받을 수 있습니다:
{
"data": {
"destroyNote": {
"errors": [],
"note": null
}
}
}
우리는 노트 세부 정보를 요청했지만, 더 이상 존재하지 않기 때문에 null이 반환됩니다.
변형에 대한 더 많은 정보: GraphQL 문서.
프로젝트 설정 업데이트
하나의 GraphQL 변형에서 여러 프로젝트 설정을 업데이트할 수 있습니다.
이 예제는 CI_JOB_TOKEN 스코프 동작의 주요 변경 사항을 위한 우회 방법입니다.
mutation DisableCI_JOB_TOKENscope {
projectCiCdSettingsUpdate(input:{fullPath: "<namespace>/<project-name>", inboundJobTokenScopeEnabled: false}) {
ciCdSettings {
inboundJobTokenScopeEnabled
}
errors
}
}
내부 탐색 쿼리
클라이언트는 내부 탐색 쿼리를 통해 GraphQL 엔드포인트에서 스키마에 대한 정보를 요청할 수 있습니다.
GraphiQL Query Explorer는 내부 탐색 쿼리를 사용하여:
- GitLab GraphQL 스키마에 대한 지식을 얻습니다.
- 자동 완성을 수행합니다.
- 상호작용 가능한
Docs탭을 제공합니다.
예시: 스키마에서 모든 타입 이름 가져오기.
{
__schema {
types {
name
}
}
}
예시: Issue와 연관된 모든 필드 가져오기. kind는 OBJECT, SCALAR 또는 INTERFACE와 같은 타입의 열거형 값을 알려줍니다.
query IssueTypes {
__type(name: "Issue") {
kind
name
fields {
name
description
type {
name
}
}
}
}
내부 탐색에 대한 더 많은 정보: GraphQL 문서
쿼리 복잡성
쿼리에 대한 복잡성 점수 및 제한은 queryComplexity를 쿼리하여 클라이언트에 노출될 수 있습니다.
query {
queryComplexity {
score
limit
}
project(fullPath: "gitlab-org/graphql-sandbox") {
name
}
}
정렬
일부 GitLab GraphQL 엔드포인트는 객체 컬렉션을 정렬하는 방법을 지정할 수 있도록 허용합니다. 스키마에서 허용하는 것 외에는 정렬할 수 없습니다.
예시: Issue는 생성 날짜로 정렬할 수 있습니다:
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(sort: created_asc) {
nodes {
title
createdAt
}
}
}
}
페이지 매김
페이지 매김은 레코드의 하위 집합만 요청하는 방법입니다. 예를 들어 처음 10개를 요청할 수 있습니다. 더 많은 레코드를 원할 경우, 서버에 다음 10개를 요청할 수 있습니다.
기본적으로 GitLab GraphQL API는 페이지당 100개의 레코드를 반환합니다. 이 동작을 변경하려면 first 또는 last 인수를 사용합니다. 두 인수 모두 값이 필요하므로, first: 10은 처음 10개의 레코드를 반환하고, last: 10은 마지막 10개의 레코드를 반환합니다. 페이지당 반환되는 레코드 수에는 일반적으로 100의 제한이 있습니다.
예시: 처음 두 개의 Issue만 가져오기 (슬라이싱). cursor 필드는 해당 레코드에 상대적인 더 많은 레코드를 가져올 수 있는 위치를 제공합니다.
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 2) {
edges {
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
예시: 다음 세 개를 가져오기. (커서 값
eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0는 다를 수 있지만, 위에서 반환된 두 번째 Issue에 대해 반환된 cursor 값입니다.)
query {
project(fullPath: "gitlab-org/graphql-sandbox") {
name
issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
edges {
node {
title
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
페이지 매김 및 커서에 대한 더 많은 정보: GraphQL 문서
도움말