Skip to main content

Limitações de recursos

A API do GraphQL de GitHub tem limitações de proteção contra chamadas excessivas ou abusivas para os servidores de GitHub.

Limite do nó

Para serem aprovados na validação de esquema, todas as chamadas à API do GraphQL precisam atender a estes padrões:

  • Os clientes precisam fornecer um argumento first ou last em qualquer conexão.
  • Os valores de firste last precisam estar entre 1 e 100.
  • As chamadas individuais não podem solicitar mais de 500 mil nós no total.

Calcular nós em uma chamada

Estes dois exemplos mostram como calcular os nós totais em uma chamada.

  1. Consulta simples:

    query {
      viewer {
        repositories(first: 50) {
          edges {
            repository:node {
              name
    
              issues(first: 10) {
                totalCount
                edges {
                  node {
                    title
                    bodyHTML
                  }
                }
              }
            }
          }
        }
      }
    }

    Cálculo:

    50         = 50 repositories
     +
    50 x 10  = 500 repository issues
    
                = 550 total nodes
  2. Consulta complexa:

    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
            }
          }
        }
      }
    }

    Cálculo:

    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

Limite de taxa

O limite da API do GraphQL é diferente dos limites de taxa da API REST.

Por que os limites de taxa de API são diferentes? Com o GraphQL, uma chamada do GraphQL pode substituir várias chamadas REST. Uma chamada única e complexa do GraphQL poderia ser o equivalente a milhares de solicitações de REST. Embora uma única chamada GraphQL fique bem abaixo do limite de taxa de API REST, a consulta pode ser muito cara para os servidores do GitHub calcularem.

Para representar com precisão o custo do servidor de uma consulta, a API do GraphQL calcula a pontuação de limite de taxa de uma chamada com base em uma escala normalizada de pontos. Os fatores de pontuação de uma consulta no primeiro e último argumentos em uma conexão principal e suas conexões auxiliares.

  • A fórmula usa os argumentos first e last em uma conexão pai e os filhos para calcular previamente a carga potencial nos sistemas do GitHub, como o MySQL, o ElasticSearch e o Git.
  • Cada nova conexão tem o seu valor próprio de pontos. Os pontos são combinados com outros pontos da chamada para uma pontuação de limite de taxa geral.

O limite de taxa da API do GraphQL é de 5 mil pontos por hora.

Observe que 5 mil pontos por hora não é o mesmo que 5 mil chamadas por hora: a API do GraphQL e a API REST usam limites de taxa diferentes.

Observação: a fórmula e o limite de taxa atuais estão sujeitos a alterações, conforme observamos como os desenvolvedores usam a API do GraphQL.

Retornar o status de limite da chamada

Com a API REST, você pode verificar o status do limite de taxa inspecionando os cabeçalhos HTTP retornados.

Com a API do GraphQL, você pode verificar o status do limite de taxa consultando campos no objeto rateLimit:

query {
  viewer {
    login
  }
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}
  • O campo limit retorna o número máximo de pontos que o cliente tem permissão para consumir em uma janela de 60 minutos.

  • O campo cost retorna o custo de ponto para a chamada atual que é contado no limite de taxa.

  • O campo remaining retorna o número de pontos restantes na janela de limite de taxa atual.

  • O campo resetAt retorna o tempo em que a janela de limite de taxa atual é redefinida em segundos de época UTC.

Calcular um limite de taxa antes de executar a chamada

A consulta do objeto rateLimit retorna a pontuação de uma chamada, mas a execução da chamada é contada no limite. Para evitar esse dilema, você pode calcular a pontuação de uma chamada antes de executá-la. O cálculo a seguir resulta aproximadamente no mesmo custo retornado por rateLimit { cost }.

  1. Adicione o número de solicitações necessárias para atender cada conexão única na chamada. Suponha que cada solicitação atingirá os limites dos argumentos first e last.
  2. Divida o número por 100 e arredonde o resultado para obter o custo de agregação final. Esta etapa normaliza números grandes.

Observação: o custo mínimo de uma chamada à API do GraphQL é 1, representando uma solicitação individual.

Aqui está um exemplo de consulta e cálculo de pontuação:

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Esta consulta exige que 5,101 solicitações sejam atendidas:

  • Embora estejamos retornando 100 repositórios, a API precisa se conectar à conta do visualizador uma vez para obter a lista de repositórios. Portanto, as solicitações de repositórios = 1
  • Embora estejamos retornando 50 problemas, a API precisa se conectar a cada um dos 100 repositórios para obter a lista de problemas. Portanto, as solicitações de problemas = 100
  • Embora estejamos retornando 60 rótulos, a API precisa se conectar a cada um dos cinco mil possíveis problemas totais para obter a lista de rótulos. Portanto, as solicitações de rótulos = 5.000
  • Total = 5.101

Dividindo isso por 100 e arredondando o resultado, obtemos a pontuação final da consulta: 51