GraphQL API 쿼리 및 뮤테이션 실행

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

개발자가 API 자체를 개발하려는 사람들을 대상으로 한 구현 세부 정보를 위해 GraphQL API 스타일 가이드를 참조하세요.

실행 예시

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

GraphiQL.
Command line.
Rails console.

GraphiQL

GraphiQL(발음: “그래픽”)은 API와 상호작용적으로 실제 GraphQL 쿼리를 실행할 수 있게 해줍니다. 구문 강조와 자동 완성 기능을 제공하는 UI를 통해 스키마를 쉽게 탐색할 수 있도록 도와줍니다.

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

GraphiQL을 사용할 수 있습니다:

GitLab.com에서.
자체 관리 GitLab 인스턴스에서 https://<your-gitlab-site.com>/-/graphql-explorer에서.

요청을 권한 부여하려면 먼저 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 console

Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

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 API에서 id는 Global ID를 참조하는데, 이는 "gid://gitlab/Issue/123" 형식의 객체 식별자입니다. 자세한 내용은 Global IDs를 참조하세요.

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: "*차를 마십니다*"
    }) {
    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 쿼리 탐색기는 다음을 위해 인트로스펙션 쿼리를 사용합니다:

GitLab GraphQL 스키마에 대한 정보 획들.
자동 완성 기능 제공.
대화형 Docs 탭 제공.

예시: 스키마 내 모든 타입 이름 가져오기.

{
  __schema {
    types {
      name
    }
  }
}

예시: 이슈에 대한 연관된 모든 필드 가져오기. kind는 우리에게 타입에 대한 enum 값인 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 엔드포인트 중 일부는 객체 컬렉션의 정렬 방법을 지정할 수 있습니다. 스키마에서 허용되는 것만으로 정렬할 수 있습니다.

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

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 문서

GraphQL API 쿼리 및 뮤테이션 실행

실행 예시

GraphiQL

커맨드 라인

Rails console

쿼리 및 뮤테이션

그래프 순회

권한

뮤테이션

생성 뮤테이션

변경 사항 뮤테이션

삭제 뮤테이션

프로젝트 설정 업데이트

인트로스펙션 쿼리

쿼리 복잡도

정렬

페이지네이션

도움말

기능 사용 가능성과 제품 평가판

도움받기