노드 제한
스키마 유효성 검사를 통과하려면 모든 GraphQL API 호출이 다음 표준을 충족해야 합니다.
- 클라이언트는 모든 연결에서
first또는last인수를 제공해야 합니다. first및last의 값은 1~100 이내여야 합니다.- 개별 호출은 총 500,000개를 초과하는 노드를 요청할 수 없습니다.
호출에서 노드 계산
이 두 예제에서는 호출에서 총 노드를 계산하는 방법을 보여 줍니다.
-
단순 쿼리:
query { viewer { repositories(first: 50) { edges { repository:node { name issues(first: 10) { totalCount edges { node { title bodyHTML } } } } } } } }계산:
50 = 50 repositories + 50 x 10 = 500 repository issues = 550 total nodes
-
복합 쿼리:
query { viewer { repositories(first: 50) { edges { repository:node { name pullRequests(first: 20) { edges { pullRequest:node { title comments(first: 10) { edges { comment:node { bodyHTML } } } } } } issues(first: 20) { totalCount edges { issue:node { title bodyHTML comments(first: 10) { edges { comment:node { bodyHTML } } } } } } } } } followers(first: 10) { edges { follower:node { login } } } } }계산:
50 = 50 repositories + 50 x 20 = 1,000 pullRequests + 50 x 20 x 10 = 10,000 pullRequest comments + 50 x 20 = 1,000 issues + 50 x 20 x 10 = 10,000 issue comments + 10 = 10 followers = 22,060 total nodes
기본 트래픽률 제한
GraphQL API는 각 쿼리에 포인트를 할당하고 특정 시간 내에 사용할 수 있는 포인트를 제한합니다. 이 제한은 남용 및 서비스 거부 공격을 방지하고 모든 사용자가 API를 계속 사용할 수 있도록 합니다.
REST API에는 별도의 기본 트래픽률 제한도 있습니다. 자세한 내용은 "REST API에 대한 트래픽률 제한"을(를) 참조하세요.
일반적으로 인증 방법에 따라 GraphQL API에 대한 기본 트래픽률 제한을 계산할 수 있습니다.
- 사용자: 사용자당 시간당 5,000포인트 여기에는 personal access token을(를) 사용한 요청뿐만 아니라 앱에 권한을 부여한 사용자를 대신하여 GitHub App 또는 OAuth app의 요청이 포함됩니다. GitHub Enterprise Cloud 조직이 소유한 GitHub App이(가) 사용자를 대신하여 요청하는 요청에는 시간당 10,000포인트의 더 높은 트래픽률 제한이 적용됩니다. 마찬가지로 GitHub Enterprise Cloud 조직이 소유하거나 승인한 OAuth app이(가) 사용자를 대신하여 요청하는 요청에는 GitHub Enterprise Cloud 조직의 멤버인 경우 시간당 10,000포인트의 더 높은 트래픽률 제한이 적용됩니다.
- GitHub Enterprise Cloud 조직이 아닌 GitHub App 설치의 경우: 설치당 시간당 5,000포인트 리포지토리가 20개를 초과하는 설치는 각 리포지토리에 대해 시간당 50포인트의 요청을 추가로 받습니다. 사용자 수가 20명을 초과하는 조직에 대한 설치의 경우 각 사용자에 대해 시간당 50포인트의 요청을 추가로 수신할 수 있습니다. 트래픽률 제한은 시간당 12,500포인트 요청을 초과할 수 없습니다. 설치 액세스 토큰과 달리 사용자 액세스 토큰에 대한 트래픽률 제한은 사용자의 기본 트래픽률 제한에 따라 결정됩니다.
- GitHub Enterprise Cloud 조직에 GitHub App 설치의 경우: 설치당 시간당 10,000포인트 설치 액세스 토큰과 달리 사용자 액세스 토큰에 대한 트래픽률 제한은 사용자의 기본 트래픽률 제한에 따라 결정됩니다.
- OAuth apps의 경우: 시간당 5,000포인트, GitHub Enterprise Cloud 조직이 앱을 소유한 경우 시간당 10,000포인트 이는 앱이 클라이언트 ID 및 클라이언트 암호를 사용하여 공용 데이터를 요청하는 경우에만 적용됩니다. OAuth app에서 생성된 OAuth 액세스 토큰의 트래픽률 제한은 사용자의 기본 트래픽률 제한에 따라 결정됩니다.
- GitHub Actions 워크플로에서
GITHUB_TOKEN의 경우: 리포지토리당 시간당 1,000포인트 GitHub.com에서 엔터프라이즈 계정에 속한 리소스에 대한 요청의 경우 리포지토리당 시간당 15,000포인트로 제한됩니다.
다음 섹션에 설명된 대로 쿼리의 포인트 값을 검사하거나 예상 포인트 값을 계산할 수 있습니다. 포인트 및 트래픽률 제한을 계산하는 수식은 변경될 수 있습니다.
기본 트래픽률 제한의 상태 확인
각 응답과 함께 전송되는 헤더를 사용하여 기본 트래픽률 제한의 현재 상태를 확인할 수 있습니다.
| 헤더 이름 | 설명 |
|---|---|
x-ratelimit-limit | 시간당 사용할 수 있는 최대 포인트 수 |
x-ratelimit-remaining | 현재 트래픽률 제한 창의 잔여 포인트 수 |
x-ratelimit-used | 현재 트래픽률 제한 창에서 사용한 포인트 수 |
x-ratelimit-reset | 현재 트래픽률 제한 창이 UTC Epoch 초 단위로 재설정되는 시간 |
x-ratelimit-resource | 요청이 계산한 트래픽률 제한 리소스. GraphQL 요청의 경우 항상 graphql이(가) 됩니다. |
rateLimit 개체를 쿼리하여 트래픽률 제한을 확인할 수도 있습니다. 가능하면 API를 쿼리하는 대신 트래픽률 제한 응답 헤더를 사용하여 트래픽률 제한을 확인하는 것이 좋습니다.
query {
viewer {
login
}
rateLimit {
limit
remaining
used
resetAt
}
}
| 필드 | 설명 |
|---|---|
limit | 시간당 사용할 수 있는 최대 포인트 수 |
remaining | 현재 트래픽률 제한 창의 잔여 포인트 수 |
used | 현재 트래픽률 제한 창에서 사용한 포인트 수 |
resetAt | 현재 트래픽률 제한 창이 UTC Epoch 초 단위로 재설정되는 시간 |
쿼리의 포인트 값 반환
rateLimit 개체의 cost 필드를 쿼리하여 쿼리의 포인트 값을 반환할 수 있습니다.
query {
viewer {
login
}
rateLimit {
cost
}
}
쿼리의 포인트 값 예측
쿼리를 만들기 전에 쿼리의 포인트 값을 대략적으로 계산할 수도 있습니다.
- 호출에서 각각의 고유한 연결을 수행하는 데 필요한 요청 수를 추가합니다. 모든 요청이
first또는last인수 제한에 도달한다고 가정합니다. - 숫자를 100으로 나누고 결과를 가장 가까운 정수로 반올림하여 최종 집계 포인트 값을 가져옵니다. 이 단계는 큰 숫자를 정규화합니다.
Note
GraphQL API 호출의 최소 포인트 값은 1입니다.
다음은 쿼리 및 점수 계산 예제입니다.
query {
viewer {
login
repositories(first: 100) {
edges {
node {
id
issues(first: 50) {
edges {
node {
id
labels(first: 60) {
edges {
node {
id
name
}
}
}
}
}
}
}
}
}
}
}
이 쿼리를 수행하려면 5,101개의 요청이 필요합니다.
- 100개의 리포지토리를 반환하지만, API는 리포지토리 목록을 가져오기 위해 뷰어의 계정에 한 번 연결해야 합니다. 따라서 리포지토리에 대한 요청 = 1
- 50개의 이슈를 반환하지만, API는 이슈 목록을 가져오기 위해 100개 리포지토리 각각에 연결해야 합니다. 따라서 이슈에 대한 요청 = 100
- 60개의 레이블을 반환하지만, API는 레이블 목록을 가져오기 위해 총 5,000개의 잠재적 이슈 각각에 연결해야 합니다. 따라서 레이블에 대한 요청 = 5,000
- 총계 = 5,101
100으로 나누고 반올림하면 쿼리의 최종 점수인 51을 얻을 수 있습니다.
보조 속도 제한
GitHub은(는) 기본 트래픽률 제한 외에도 남용을 방지하고 모든 사용자가 사용할 수 있는 API를 유지하기 위해 보조 트래픽률 제한을 적용합니다.
다음과 같은 경우 보조 트래픽률 제한이 발생할 수 있습니다.
- 동시 요청이 너무 많습니다. 동시 요청은 100개 이하로 허용됩니다. 이 제한은 REST API 및 GraphQL API에서 공유됩니다.
- 분당 단일 엔드포인트에 너무 많은 요청을 만듭니다. REST API 엔드포인트에는 분당 900포인트를 초과할 수 없고 GraphQL API 엔드포인트에는 분당 2,000포인트를 초과할 수 없습니다. 포인트에 대한 자세한 내용은 "보조 트래픽률 제한에 대한 포인트 계산"을 참조하세요.
- 너무 많은 분당 요청을 만듭니다. 실시간 60초당 CPU 시간은 90초를 초과할 수 없습니다. GraphQL API에는 이 CPU 시간이 60초 이하일 수 있습니다. API 요청에 대한 총 응답 시간을 측정하여 CPU 시간을 대략적으로 예측할 수 있습니다.
- 짧은 기간 동안 과도한 컴퓨팅 리소스를 사용하는 요청을 너무 많이 만듭니다.
- 짧은 시간 안에 GitHub에 너무 많은 콘텐츠를 만듭니다. 일반적으로 분당 80개 이하의 콘텐츠 생성 요청과 시간당 500개 이하의 콘텐츠 생성 요청이 허용됩니다. 일부 엔드포인트는 콘텐츠 만들기 제한이 더 낮습니다. 콘텐츠 만들기 제한에는 GitHub 웹 인터페이스뿐만 아니라 REST API 및 GraphQL API를 통해 수행되는 작업이 포함됩니다.
이러한 보조 트래픽률 제한은 예고 없이 변경될 수 있습니다. 공개되지 않은 이유로 보조 트래픽률 제한이 발생할 수도 있습니다.
보조 트래픽률 제한에 대한 포인트 계산
일부 보조 트래픽률 제한은 요청의 포인트 값에 따라 결정됩니다. GraphQL 요청의 경우 이러한 포인트 값은 기본 트래픽률 제한에 대한 포인트 값 계산과 별개입니다.
| 요청 | 지점 |
|---|---|
| 변형이 없는 GraphQL 요청 | 1 |
| 변형이 있는 GraphQL 요청 | 5 |
대부분의 REST API GET, HEAD 및 OPTIONS 요청 | 1 |
대부분의 REST API POST, PATCH, PUT 또는 DELETE 요청 | 5 |
일부 REST API 엔드포인트에는 공개적으로 공유되지 않는 다른 포인트 비용이 있습니다.
속도 제한 초과
기본 트래픽률 제한을 초과하면 응답 상태가 계속 200이지만 오류 메시지가 표시되고 x-ratelimit-remaining 헤더 값이 0이(가) 됩니다. x-ratelimit-reset 헤더에 지정된 시간이 경과하지 전까지 요청을 다시 시도해서는 안 됩니다.
보조 트래픽률 제한을 초과하는 경우 응답 상태가 200 또는 403이(가) 되고 보조 트래픽률 제한을 초과했음을 나타내는 오류 메시지가 표시됩니다. retry-after 응답 헤더가 있는 경우 몇 초가 경과할 때까지 요청을 다시 시도하면 안 됩니다. x-ratelimit-remaining 헤더가 0인 경우 x-ratelimit-reset 헤더로 지정된 시간(UTC epoch 초)까지 요청을 다시 시도해서는 안 됩니다. 그렇지 않은 경우 다시 시도하기 전에 1분 이상 기다립니다. 보조 트래픽률 제한으로 인해 요청이 계속 실패하는 경우 재시도 사이에 기하급수적으로 증가하는 시간을 기다린 후 특정 횟수의 재시도 후 오류가 발생합니다.
트래픽률이 제한된 동안 요청을 계속하면 통합이 금지될 수 있습니다.
트래픽률 제한 내에서 유지
트래픽률 제한을 초과하지 않도록 하려면 변경 요청 간에 1초 이상 일시 중지하고 동시 요청을 피해야 합니다.
또한 데이터에 대한 API를 폴링하는 대신 웹후크 이벤트를 구독해야 합니다. 자세한 내용은 "웹후크 설명서"을(를) 참조하세요.