GitHub CLI 탐색 : GitHub의 GraphQL API Endpoint와 상호 작용하는 방법

당신은 Github Cli와 당신이 할 수있는 모든 멋진 일에 대해 들어 보았을 것입니다. 그러나 숨겨진 초강대국 중 하나는 Github의 GraphQL API를 통해 복잡한 쿼리 및 돌연변이를 실행하는 기능입니다. 이 게시물은 Github의 GraphQL API 엔드 포인트가 무엇인지, GitHub CLI로 쿼리하는 방법을 안내합니다.

GraphQL이란 무엇입니까?

기본 사항부터 시작하겠습니다 : GraphQL은 API를위한 쿼리 언어이며 데이터에 대한 쿼리를 실행하기위한 런타임입니다. 사전 정의 된 엔드 포인트에서 고정 된 데이터 구조를 제공하는 기존의 REST API와 달리 GraphQL을 사용하면 클라이언트가 단일 요청에서 필요한 데이터를 정확하게 요청할 수 있습니다. 이 단일 요청 접근 방식은 네트워크 오버 헤드를 줄이고, 응용 프로그램 성능을 높이고, 클라이언트 측로 논리를 단순화하여 여러 API 응답을 조정할 필요가 없음을 제거하여 2015 년에 사양이 공개 된 이후 공개적으로 사용할 수있는 기능입니다.

GraphQL 작업은 쿼리와 돌연변이의 두 가지 주요 유형으로 제공됩니다. 쿼리 변경하지 않고 데이터를 검색하는 읽기 전용 작업입니다. 요청을받을 수 있습니다. 돌연변이반면, 서버 측 데이터를 수정하는 데 사용됩니다 (생성, 업데이트 또는 삭제)-REST API를 게시, 패치, PIT 및 삭제하기가 가능합니다. 읽기와 쓰기 작업 사이의 명확한 분리는 GraphQL 상호 작용을 예측할 수있게 해주 며 변경이 이루어진 후 반환해야 할 데이터를 정확하게 지정할 수있는 유연성을 유지할 수있게합니다.

Github에서 GraphQL은 어떻게 사용됩니까?

Github는 2016 년에 RESTFUL API의 한계를 해결하기 위해 GraphQL을 구현했습니다. 이 채택은 GitHub 데이터로 작업 할 때 개발자 경험을 크게 향상 시켰습니다. GraphQL Endpoint를 사용하면 단일 GraphQL 쿼리로 리포지토리의 문제, 레이블, 양수 및 주석을 검색 할 수 있습니다. REST API를 사용하면 여러 세트의 중첩 된 통화를 가져 왔을 것입니다.

일부 GitHub 데이터 및 운영은 GraphQL API (토론, 프로젝트 및 일부 엔터프라이즈 설정 등)를 통해서만 액세스 할 수 있습니다 (예 : REST API 쿼리 작업 워크 플로우, 러너 또는 로그) 및 일부 엔드 포인트 (예 : 리포지토리, 문제, 풀 요청 및 사용자 정보)를 사용하는 것과 같은 독점적으로. GitHub의 GraphQL 엔드 포인트는 액세스 할 수 있습니다 api.github.com/graphql 또한 GraphQL 문서에서 또는 대화식 GraphQL Explorer를 통해 전체 스키마를 탐색 할 수 있습니다.

REST API와 GraphQL API 중에서 선택할 때 주요 고려 사항은 속도 제한 계산 방법입니다. 이것이 어떻게 구현되는지에 대한 빠른 요약으로 :

휴식 API: 요청 수에 의해 제한 (일반적으로 인증 된 사용자의 경우 시간당 5,000 건의 요청, 기업에 설치된 GitHub 앱의 경우 최대 15,000 개)
GraphQL API: “포인트”로 제한 (인증 된 사용자의 경우 일반적으로 시간당 5,000 포인트이지만 GitHub 앱의 경우 시간당 최대 10,000-12,500 포인트까지 올라갈 수 있음)

각 GraphQL 쿼리 비용은 적어도 한 번의 요점이지만 쿼리의 복잡성 (요청 된 노드 수, 연결이 통과 등)에 따라 비용이 증가합니다. GraphQL API는 a rateLimit 쿼리에 포함 할 수있는 필드 현재 제한 상태를 확인하십시오.

여러 휴식을 필요로하는 관련 데이터를 가져와야하는 시나리오의 경우, 그래프 QL은 종종 다음과 같은 속도 제한 친화적입니다.

하나의 복잡한 GraphQL 쿼리는 5-10 포인트의 비용이 들지만 5-10 개의 별도의 REST API 호출을 교체합니다.
필요하지 않은 “과도한 가져 오기”데이터를 피하기 위해 비율 제한에 간접적으로 도움이됩니다.
GraphQL API는보다 세분화 된 필드 선택을 허용하여 복잡성과 포인트 비용을 줄일 수 있습니다.

그러나 많은 양의 중첩 데이터를 요청하는 최적의 최적화 된 그래프 QL 쿼리는 동등한 REST 요청보다 속도 제한을 더 빨리 사용하고 2 차 요율 제한 문제에 빠르게 사용될 수 있습니다.

사용 할 사람을 결정하는 데있어서의 빠른 경험 법칙 :

GitHub 프로젝트 및 문제와 같은 관계형 객체를 쿼리하기 위해 GraphQL은 특히 개별 항목 인 경우 종종 더 효과적입니다.
조직에서 저장소 이름 목록을 가져 오는 것과 같은 한 유형 또는 단일 데이터 포인트의 대량 데이터의 경우 나머지 API가 종종 선호됩니다.

때로는 옳고 그른 대답이 없습니다. 객체가 존재하는 한, 하나를 시도하십시오!

Github CLI를 GriphQL에 사용하는 이유는 무엇입니까?

많은 개발자가 웹에서 Github의 GraphQL 탐색기로 시작하지만 curl또는 다른 API 쿼리 도구에는보다 간소화 된 접근 방식이 있습니다. GitHub CLI에서 내장 GraphQL 지원을 사용합니다. 방법을 사용하기 전에 Github CLI가 종종 GraphQL 쿼리 및 돌연변이를위한 도구 인 이유를 이해해 봅시다.

인증은 자동으로 처리됩니다. 개인 액세스 토큰을 수동으로 관리 할 필요가 없습니다.
간소화 된 구문 : 공예보다 간단합니다 curl 명령.
지역 개발 친화적 : 터미널에서 바로 쿼리 및 돌연변이를 실행하십시오.
JSON 처리 : 필터링 및 서식 결과를위한 내장 옵션.
Pagination Support : GraphQL 응답에서 커서 기반 Pagination으로 작업하는 능력.
일관된 경험 : 다른 github 작업에 사용할 수있는 동일한 도구.

시작하는 방법 `gh api graphql`

먼저 Github CLI를 설치하고 인증했는지 확인하십시오. gh auth login. 그래프 QL 쿼리를 만들기위한 기본 구문 gh api graphql 이다:

gh api graphql -H X-Github-Next-Global-ID:1 -f query='
  query {
    viewer {
      login
      name
      bio
    }
  }
'

이 간단한 쿼리는 github 사용자 이름, 프로필에서 정의한 이름 및 바이오를 반환합니다. 그만큼 -f 플래그는 양식 변수를 정의합니다 query= 그래프 QL 쿼리 자체입니다.

예제 출력은 다음과 같습니다.

{
  "data": {
    "viewer": {
      "login": "joshjohanning",
      "name": "Josh Johanning",
      "bio": "DevOps Architect | GitHub"
    }
  }
}

실행 쿼리 및 돌연변이

기본 쿼리 예제

저장소에 대한 정보를 찾는 더 실용적인 것을 시도해 봅시다. 시작하려면 다음 쿼리를 사용하겠습니다.

gh api graphql -H X-Github-Next-Global-ID:1 -f query='
  query($owner:String!, $repo:String!) {
    repository(owner:$owner, name:$repo) {
      name
      description
      id
      stargazerCount
      forkCount
      issues(states:OPEN) {
        totalCount
      }
    }
  }
' -F owner=octocat -F repo=Hello-World

그만큼 -F 플래그는 쿼리에서 참조되는 변수 값을 설정합니다. $variable.

예제 출력은 다음과 같습니다.

{
  "data": {
    "repository": {
      "name": "Hello-World",
      "description": "My first repository on GitHub!",
      "id": "R_kgDOABPHjQ",
      "stargazerCount": 2894,
      "forkCount": 2843,
      "issues": {
        "totalCount": 1055
      }
    }
  }
}

💡 팁: -H X-Github-Next-Global-ID:1 매개 변수는 GitHub의 GraphQL API에 레거시 형식이 아닌 새로운 글로벌 노드 ID 형식을 사용하도록 지시하는 HTTP 헤더를 설정합니다. 이 헤더없이 쿼리가 작동하는 동안, 노드 ID를 참조 할 때 (예 : 통과시) repository.ID 후속 작업에서). Github는 장기적인 호환성을 보장하기 위해 모든 새로운 통합 에이 형식을 채택하는 것이 좋습니다.

돌연변이 실행

돌연변이도 비슷하게 작동합니다. 새로운 문제를 만드는 방법은 다음과 같습니다.

gh api graphql -H X-Github-Next-Global-ID:1 -f query='
  mutation($repositoryId:ID!, $title:String!, $body:String) {
    createIssue(input:{repositoryId:$repositoryId, title:$title, body:$body}) {
      issue {
        url
        number
        title
        body
        state
      }
    }
  }
' -F repositoryId="R_kgDOABPHjQ" -F title="Creating issue with GraphQL" -F body="Issue body created via GraphQL\!"

업데이트하십시오 repositoryId 실제 저장소의 그래프 QL ID가있는 매개 변수 (리포지토리 ID를 반환하는 예는 위의 기본 쿼리에 표시됩니다!).

예제 출력은 다음과 같습니다.

{
  "data": {
    "createIssue": {
      "issue": {
        "url": "
        "number": 3706,
        "title": "Creating issue with GraphQL",
        "body": "Issue body created via GraphQL!",
        "state": "OPEN"
      }
    }
  }
}

그래프 QL 결과 필터링

GitHub CLI는 응답의 특정 부분을 추출하기위한 JQ 스타일 필터링을 지원합니다. 응답의 특정 부품을 추출합니다. 이는 자동화 스크립트에 사용하기 위해 쿼리에서 저장소 이름이나 URL 만 구문 분석해야 할 때 매우 중요합니다. 다음은 사용의 예입니다 --jq 깃발:

gh api graphql -H X-Github-Next-Global-ID:1 -f query='
  query($owner:String!, $repo:String!) {
    repository(owner:$owner, name:$repo) {
      issues(first:3, states:OPEN) {
        nodes {
          number
          title
          url
        }
      }
    }
  }
' -F owner=octocat -F repo=Hello-World --jq '.data.repository.issues.nodes[]'

그만큼 --jq FLAG는 JSON 출력을 처리하기 위해 JQ 표현을 수락합니다. 이 쿼리는 주변 GraphQL 응답 구조없이 문제 배열 만 반환합니다.

예제 출력은 다음과 같습니다.

{
  "number": 26,
  "title": "test issue",
  "url": "
}
{
  "number": 27,
  "title": "just for test",
  "url": "
}
{
  "number": 28,
  "title": "Test",
  "url": "
}

우리는 수정할 수있었습니다 --jq 플래그는 다음과 같이 문제 URL을 반환합니다.

gh api graphql -H X-Github-Next-Global-ID:1 -f query='
  query($owner:String!, $repo:String!) {
    repository(owner:$owner, name:$repo) {
      issues(first:3, states:OPEN) {
        nodes {
          number
          title
          url
        }
      }
    }
  }
' -F owner=octocat -F repo=Hello-World --jq '.data.repository.issues.nodes[].url'

예제 출력은 다음과 같습니다.

페이지 매김 처리

GitHub의 GraphQL API는 페이지 당 최대 100 개 항목으로 제한되므로 더 큰 데이터 세트를 검색하려면 페이지 매김이 필요합니다.

GraphQL의 Pagination은 결과의 각 페이지에 “커서”를 반환하여 다음 결과 세트가 시작될 위치에 대한 포인터 역할을합니다. 다음 페이지를 요청하면이 커서를 제공하여 시작 장소를 표시합니다.

Github Cli 에서이 페이지 매김을 처리하는 가장 쉬운 방법은 다음과 같습니다. --paginate 장면 뒤에 이러한 커서를 관리하여 모든 결과 페이지를 자동으로 수집하는 플래그. 다음은 쿼리의 모습입니다.

gh api graphql --paginate -H X-Github-Next-Global-ID:1 -f query='
  query($owner:String!, $repo:String!, $endCursor:String) {
    repository(owner:$owner, name:$repo) {
      issues(first:100, after:$endCursor, states:OPEN, orderBy:{field:CREATED_AT, direction:DESC}) {
        pageInfo {
          hasNextPage
          endCursor
        }
        nodes {
          number
          title
          createdAt
        }
      }
    }
  }
' -F owner=octocat -F repo=Hello-World

PageInfo 객체와 객체 hasNextPage 그리고 endCursor 필드는 페이지 매김에 필수적입니다. 당신이 사용할 때 --paginate Flag, Github CLI는 이러한 필드를 자동으로 사용하여 쿼리에 사용 가능한 모든 페이지를 가져와 결과를 단일 응답으로 결합합니다.

예제 출력은 다음과 같습니다.

{
  "data": {
    "repository": {
      "issues": {
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "Y3Vyc29yOnYyOpK5MjAyNC0xMi0zMFQxNDo0ODo0NC0wNjowMM6kunD3"
        },
        "nodes": [
          {
            "number": 3708,
            "title": "Creating issue with GraphQL once more",
            "createdAt": "2025-04-02T18:15:11Z",
            "author": {
              "login": "joshjohanning"
            }
          },
          {
            "number": 3707,
            "title": "Creating issue with GraphQL again",
            "createdAt": "2025-04-02T18:15:02Z",
            "author": {
              "login": "joshjohanning"
            }
          },
          {
            "number": 3706,
            "title": "Creating issue with GraphQL",
            "createdAt": "2025-04-02T18:14:37Z",
            "author": {
              "login": "joshjohanning"
            }
          },
          … and so on
        ]
      }
    }
  }
}

이 접근법은 적당한 양의 데이터에 적합하지만 GitHub의 GraphQL API에는 속도 제한이 있으므로 쿼리가 요청간에 지연을 구현해야 할 수도 있습니다.

💡 중요한 제한: --paginate 플래그는 한 번에 단일 연결에 대한 페이지 매김 만 처리 할 수 있습니다. 예를 들어, 위에 표시된 것처럼 저장소 문제를 나열 할 때 모든 문제를 통해 페이지를 촬영할 수 있지만 각 문제의 주석을 통해 동시에 휴식 할 수는 없습니다. 중첩 된 페이지 매김의 경우 사용자 정의 로직을 구현해야합니다.

복잡한 스크립트 구축 : Chaining GraphQL 쿼리

GitHub의 GraphQL API로 작업 할 때는 종종 복잡한 작업을 수행하기 위해 여러 쿼리를 연결해야합니다. GitHub Cli를 사용하여 GuphQL 호출을 체인하는 방법을 살펴 보겠습니다.

ISSUE_ID=$(gh api graphql -H X-Github-Next-Global-ID:1 -f query='
  query($owner: String!, $repo: String!, $issue_number: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $issue_number) {
        id
      }
    }
  }
' -F owner=joshjohanning -F repo=graphql-fun -F issue_number=1 --jq '.data.repository.issue.id') 
gh api graphql -H GraphQL-Features:sub_issues -H X-Github-Next-Global-ID:1 -f query='
query($issueId: ID!) {
  node(id: $issueId) {
    ... on Issue {
      subIssuesSummary {
        total
        completed
        percentCompleted
      }
    }
  }
}' -F issueId="$ISSUE_ID"

이 쉘 스크립트가하는 일은 다음과 같습니다.

첫 번째 쿼리는 저장소 이름과 문제 번호를 사용하여 문제의 ID를 캡처합니다.
그만큼 --jq 플래그는 ID 값 만 추출하여 변수에 저장합니다.
두 번째 쿼리는이 ID를 전달하여 하위 문제 요약을 검색합니다.

예제 출력은 다음과 같습니다.

{
  "data": {
    "node": {
      "subIssuesSummary": {
        "total": 3,
        "completed": 1,
        "percentCompleted": 33
      }
    }
  }
}

이것을 당신과 함께 가져 가십시오

그만큼 gh api graphql 명령은 터미널에서 직접 GitHub의 GraphQL API와 상호 작용하는 편리한 방법을 제공합니다. 토큰 관리가 필요하지 않으며 쿼리 구문 및 서식을 단순화하며 구현하기가 복잡한 기본 페이지 매김을 처리합니다. 복잡한 쿼리 나 간단한 돌연변이를 실행하든이 접근법은 간소화 된 개발자 경험을 제공합니다.

다음에 GitHub의 GraphQL API와 상호 작용해야 할 때는 웹에서 GraphQL Explorer를 건너 뛰고 Github CLI 접근 방식을 사용해보십시오. GitHub의 강력한 GraphQL API 기능을 사용하는 데 선호하는 방법이 될 수 있습니다.

작성자가 작성했습니다

Josh는 Github Fasttrack 팀의 선임 Devops 건축가입니다. 그는 컨설턴트로서 현재 Github에서 크고 작은 회사들에게 DevOps 원칙을 홍보하는 광범위한 경험을 가지고 있습니다. 그는 Github 및 Github 액션으로 팀의 클라우드 여정을 가속화하는 데 매우 열정적입니다. 그의 오프 타임에 Josh는 홈 개선 프로젝트를 즐기고, 새로운 장소로 여행하고, 공예 칵테일을 섞고, 아내, 고양이 및 딸과 시간을 보내는 것을 즐깁니다.

출처 참조