이 가이드는 GitLab GraphQL API의 기본 사용법을 보여줍니다.

예시 실행#

여기에 문서화된 예시는 다음을 사용하여 실행할 수 있습니다:

• GraphiQL.
• 명령줄.
• Rails 콘솔.

GraphiQL#

GraphiQL("graphical"로 발음)을 사용하면 API에 대한 실제 GraphQL 쿼리를 대화형으로 실행할 수 있습니다. 구문 강조 표시 및 자동완성 기능이 있는 UI를 제공하여 스키마 탐색을 더 쉽게 만들어줍니다.

대부분의 사용자에게 GitLab GraphQL API를 탐색하는 가장 쉬운 방법은 GraphiQL을 사용하는 것입니다.

GraphiQL을 다음 중 하나에서 사용할 수 있습니다:

• GitLab.com.
• GitLab Self-Managed의 https://<your-gitlab-site.com>/-/graphql-explorer.

먼저 GitLab에 로그인하여 GitLab 계정으로 요청을 인증하세요.

시작하려면 쿼리 및 mutation 예시를 참조하세요.

명령줄#

로컬 컴퓨터의 명령줄에서 curl 요청으로 GraphQL 쿼리를 실행할 수 있습니다. 요청은 쿼리를 페이로드로 하여 /api/graphql에 POST합니다. 개인 액세스 토큰을 베어러 토큰으로 생성하여 요청을 인증할 수 있습니다. GraphQL 인증에 대해 자세히 알아보세요.

예시:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"query\": \"query {currentUser {name}}\"}"

쿼리 문자열에 문자열을 중첩하려면 데이터를 작은따옴표로 묶거나 \\로 문자열을 이스케이프합니다:

curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"query": "query {project(fullPath: \"<group>/<subgroup>/<project>\") {jobs {nodes {id duration}}}}"}'
  # or "{\"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

쿼리 및 Mutation#

GitLab GraphQL API를 사용하면 다음을 수행할 수 있습니다:

• 데이터 검색을 위한 쿼리.
• 데이터 생성, 업데이트, 삭제를 위한 Mutation.

GitLab GraphQL 스키마는 클라이언트가 쿼리할 수 있는 객체와 필드, 그리고 해당 데이터 유형을 설명합니다.

예시: 현재 인증된 사용자가 gitlab-org 그룹에서 접근할 수 있는 모든 프로젝트의 이름만 가져옵니다(제한 내).

query {
  group(fullPath: "gitlab-org") {
    id
    name
    projects {
      nodes {
        name
      }
    }
  }
}

예시: 특정 프로젝트와 Issue #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 인증을 참조하세요.

Mutation#

Mutation은 데이터를 변경합니다. 레코드를 업데이트, 삭제하거나 새로 생성할 수 있습니다. Mutation은 일반적으로 InputType과 변수를 사용하지만 여기서는 나타나지 않습니다.

Mutation에는 다음이 있습니다:

• 입력. 예를 들어 어떤 이모지 반응을 추가할지, 어떤 객체에 추가할지와 같은 인수.
• 반환 문. 즉, 성공 시 반환받고 싶은 것.
• 오류. 혹시 모를 경우를 대비해 항상 무엇이 잘못되었는지 확인합니다.

생성 Mutation#

예시: 차 한 잔 마시자 - 이슈에 :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
  }
}

업데이트 Mutation#

생성한 노트의 결과 id가 보이면 기록해 두세요. 더 빠르게 마시도록 편집해 봅시다.

mutation {
  updateNote(input: { id: "gid://gitlab/Note/<note ID>",
      body: "*SIPS TEA*"
    }) {
    note {
      id
      body
    }
    errors
  }
}

삭제 Mutation#

차를 다 마셨으니 댓글을 삭제합니다.

mutation {
  destroyNote(input: { id: "gid://gitlab/Note/<note ID>" }) {
    note {
      id
      body
    }
    errors
  }
}

다음과 같은 출력이 표시되어야 합니다:

{
  "data": {
    "destroyNote": {
      "errors": [],
      "note": null
    }
  }
}

요청한 노트가 더 이상 존재하지 않으므로 해당 필드의 반환 값은 null입니다.

Mutation에 대해 더 알아보기: GraphQL 문서.

프로젝트 설정 업데이트#

단일 GraphQL mutation으로 여러 프로젝트 설정을 업데이트할 수 있습니다. 이 예시는 CI_JOB_TOKEN 범위 지정 동작의 주요 변경사항에 대한 해결 방법입니다.

mutation DisableCI_JOB_TOKENscope {
  projectCiCdSettingsUpdate(input:{fullPath: "<namespace>/<project-name>", inboundJobTokenScopeEnabled: false}) {
    ciCdSettings {
      inboundJobTokenScopeEnabled
    }
    errors
  }
}

인트로스펙션 쿼리#

클라이언트는 인트로스펙션 쿼리를 만들어 GraphQL 엔드포인트의 스키마에 대한 정보를 쿼리할 수 있습니다. 이러한 쿼리는 탐색 및 진단 도구로 사용하기 위한 것입니다.

• 개발 및 테스트 환경에서 인트로스펙션 쿼리는 라이브 스키마에 대해 실행됩니다.
• 프로덕션 환경에서 인트로스펙션 쿼리는 정적 스키마를 반환합니다.
  • 인트로스펙션 쿼리는 프로덕션 환경에서 데이터를 가져오는 데 사용해서는 안 됩니다. 자세한 내용은 다음을 참조하세요:
    • 프로덕션에서의 GraphQL 인트로스펙션
    • 프로덕션에서의 Apollo 인트로스펙션
  • 모든 인트로스펙션 쿼리는 요청 방법이나 파라미터에 관계없이 동일한 정적 응답을 반환합니다.
  • 정적 스키마는 현재 스키마와 일치하도록 자동으로 업데이트됩니다.
  • 인트로스펙션 쿼리는 두 가지 정적 스키마 파일 중 하나를 반환합니다:
    • public/-/graphql/introspection_result.json: 사용 중단된 필드를 포함한 전체 스키마.
    • public/-/graphql/introspection_result_no_deprecated.json: 사용 중단된 필드가 없는 스키마.

스키마를 요청하려면 요청 본문에 다음을 전송합니다:

{
  "query": "{ __schema { types { name } } }"
}

사용 중단된 필드가 없는 스키마를 요청하려면 요청 본문에 remove_deprecated: true를 포함합니다:

{
  "query": "{ __schema { types { name } } }",
  "remove_deprecated": true
}

GraphiQL 인트로스펙션 쿼리#

GraphiQL 쿼리 탐색기는 인트로스펙션 쿼리를 사용하여 다음을 수행합니다:

• GitLab GraphQL 스키마에 대한 지식을 얻습니다.
• 자동완성을 수행합니다.
• 대화형 Docs 탭을 제공합니다.

인트로스펙션에 대해 더 알아보기: GraphQL 문서

쿼리 복잡도#

쿼리의 계산된 복잡도 점수 및 제한은 queryComplexity를 쿼리하여 클라이언트에 공개할 수 있습니다.

query {
  queryComplexity {
    score
    limit
  }

  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
  }
}

정렬#

일부 GitLab GraphQL 엔드포인트에서는 객체 컬렉션 정렬 방법을 지정할 수 있습니다. 스키마가 허용하는 것으로만 정렬할 수 있습니다.

예시: 이슈를 생성 날짜로 정렬할 수 있습니다:

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
   name
    issues(sort: created_asc) {
      nodes {
        title
        createdAt
      }
    }
  }
}

페이지네이션#

페이지네이션은 처음 열 개와 같이 레코드의 일부만 요청하는 방법입니다. 더 필요한 경우 다음 열 개의 레코드를 줘와 같은 형식으로 서버에 다음 요청을 할 수 있습니다.

기본적으로 GitLab GraphQL API는 페이지당 100개의 레코드를 반환합니다. 이 동작을 변경하려면 first 또는 last 인수를 사용합니다. 두 인수 모두 값을 받으므로 first: 10은 처음 열 개의 레코드를 반환하고 last: 10은 마지막 열 개의 레코드를 반환합니다. 페이지당 반환되는 레코드 수에는 일반적으로 100개의 제한이 있습니다.

예시: 처음 두 개의 이슈만 검색합니다(슬라이싱). cursor 필드는 해당 위치에서 추가 레코드를 검색할 수 있는 위치를 제공합니다.

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issues(first: 2) {
      edges {
        node {
          title
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

예시: 다음 세 개를 검색합니다. (커서 값 eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0는 다를 수 있지만 위에서 반환된 두 번째 이슈의 cursor 값입니다.)

query {
  project(fullPath: "gitlab-org/graphql-sandbox") {
    name
    issues(first: 3, after: "eyJpZCI6IjI3MDM4OTMzIiwiY3JlYXRlZF9hdCI6IjIwMTktMTEtMTQgMDU6NTY6NDQgVVRDIn0") {
      edges {
        node {
          title
        }
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

페이지네이션과 커서에 대해 더 알아보기: GraphQL 문서

파일 업로드#

일부 mutation은 인수로 파일 업로드를 허용합니다. 이러한 mutation은 GraphQL 멀티파트 요청 사양을 사용하여 multipart/form-data 요청을 사용하여 GraphQL 작업과 함께 파일을 보낼 수 있습니다.

파일 업로드를 지원하는 mutation에는 Upload 유형의 인수가 있습니다. GraphQL API 참조에서 Upload 스칼라 유형의 인수를 찾아 이러한 mutation을 식별할 수 있습니다.

파일 업로드 mutation은 GraphiQL을 통해 실행할 수 없습니다. curl과 같은 명령줄 도구나 호환 가능한 GraphQL 클라이언트 라이브러리를 사용해야 합니다.

멀티파트 업로드 요청에는 세 가지 핵심 부분이 있습니다:

• operations: GraphQL 쿼리와 변수를 포함하는 JSON 문자열로, 파일 값은 null로 설정됩니다.
• map: 파일 키를 operations의 변수 경로에 매핑하는 JSON 객체.
• map에 사용된 키로 참조되는 파일 필드 자체.

designManagementUpload mutation을 사용하여 이슈에 디자인을 업로드하려면:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --form 'operations={"query": "mutation ($files: [Upload!]!, $projectPath: ID!, $iid: ID!) { designManagementUpload(input: { projectPath: $projectPath, iid: $iid, files: $files }) { designs { filename } errors } }", "variables": {"files": [null], "projectPath": "<group>/<project>", "iid": "<issue-iid>"}}' \
  --form 'map={"0": ["variables.files.0"]}' \
  --form '0=@/path/to/your/design.png'

workItemsCsvImport mutation을 사용하여 CSV 파일에서 work item을 가져오려면:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --form 'operations={"query": "mutation ($projectPath: ID!, $file: Upload!) { workItemsCsvImport(input: { projectPath: $projectPath, file: $file }) { message errors } }", "variables": {"projectPath": "<group>/<project>", "file": null}}' \
  --form 'map={"0": ["variables.file"]}' \
  --form '0=@/path/to/your/work-items.csv'

단일 요청으로 여러 파일을 업로드하려면 map과 폼 필드 모두에 추가 항목을 추가합니다:

GRAPHQL_TOKEN=<your-token>
curl --request POST \
  --url "https://gitlab.com/api/graphql" \
  --header "Authorization: Bearer $GRAPHQL_TOKEN" \
  --form 'operations={"query": "mutation ($files: [Upload!]!, $projectPath: ID!, $iid: ID!) { designManagementUpload(input: { projectPath: $projectPath, iid: $iid, files: $files }) { designs { filename } errors } }", "variables": {"files": [null, null], "projectPath": "<group>/<project>", "iid": "<issue-iid>"}}' \
  --form 'map={"0": ["variables.files.0"], "1": ["variables.files.1"]}' \
  --form '0=@/path/to/first-design.png' \
  --form '1=@/path/to/second-design.png'

쿼리 URL 변경#

때로는 GraphQL 요청을 다른 URL로 보내야 할 필요가 있습니다. 예를 들어 보조 Geo 사이트 URL에 대해서만 작동하는 GeoNode 쿼리가 있습니다.

GraphiQL 탐색기에서 GraphQL 요청의 URL을 변경하려면 GraphiQL의 헤더 영역(하단 왼쪽, 변수 바로 옆)에 커스텀 헤더를 설정합니다:

{
  "REQUEST_PATH": "<the URL to make the graphQL request against>"
}