Limitations des ressources

Limite du nombre de nœuds

Pour passer la validation de schéma, tous les appels d’API GraphQL doivent respecter les standards suivants :

Les clients doivent fournir un argument first ou last sur toute connexion.
Les valeurs de first et last doivent être comprises entre 1 et 100.
Des appels individuels ne peuvent pas demander plus de 500 000 nœuds au total.

Calcul des nœuds dans un appel

Les deux exemples suivants montrent comment calculer le nombre total de nœuds dans un appel.

Requête simple :

query {
  viewer {
    repositories(first: 50) {
      edges {
        repository:node {
          name

          issues(first: 10) {
            totalCount
            edges {
              node {
                title
                bodyHTML
              }
            }
          }
        }
      }
    }
  }
}

Calcul :

50         = 50 repositories
 +
50 x 10  = 500 repository issues

            = 550 total nodes

Requête complexe :

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

Calcul :

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 du taux

La limite de l’API GraphQL diffère des limites de taux de l’API REST.

Pourquoi les limites de taux d’API diffèrent-elles ? Avec GraphQL, un appel GraphQL peut remplacer plusieurs appels REST. Un seul appel GraphQL complexe pourrait équivaloir à milliers de demandes REST. Bien qu’un seul appel GraphQL tombe bien en dessous de la limite de taux d’API REST, la requête pourrait être tout aussi coûteuse à calculer pour les serveurs de GitHub.

Pour représenter exactement le coût de serveur d’une requête, l’API GraphQL calcule le score de limite de taux d’un appel en fonction d’une échelle de points normalisée. Facteurs de score d’une requête dans les premier et dernier arguments sur une connexion parente et ses enfants.

La formule utilise les arguments first et last sur une connexion parente et ses enfants pour pré-calculer la charge potentielle sur les systèmes de GitHub, tels que MySQL, Elasticsearch et Git.
Chaque nouvelle connexion a sa propre valeur de point. Les points sont combinés avec d’autres points de l’appel dans un score de limite de taux global.

La limitation du débit est désactivée par défaut pour votre instance GitHub Enterprise Server. Lorsque la limitation du débit est désactivée, il n’existe aucune limite quant au nombre de points GraphQL que vous pouvez utiliser.

Cependant, l’administrateur de votre site peut activer des limites de débit pour votre instance GitHub Enterprise Server. Si elle est activée, la limite de débit est configurable, avec une valeur par défaut de 200 points par heure. Pour plus d’informations, consultez « Configuration des limites de débit ».

Retour de l’état de la limite de taux d’un appel

Avec l’API REST, vous pouvez vérifier l’état de la limite de taux en inspectant les en-têtes HTTP retournés.

Avec l’API GraphQL, vous pouvez vérifier l’état de la limite de taux en interrogeant des champs sur l’objet rateLimit :

query {
  viewer {
    login
  }
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

Le champ limit retourne le nombre maximal de points que le client est autorisé à consommer dans une fenêtre de 60 minutes.
Le champ cost retourne le coût du point pour l’appel actuel qui compte par rapport à la limite de taux.
Le champ remaining retourne le nombre de points restants dans la fenêtre de limite de taux actuelle.
Le champ resetAt retourne l’heure à laquelle la fenêtre de limite de taux actuelle se réinitialise au format ISO 8601.

Calcul d’un score de limite de taux avant d’exécuter l’appel

L’interrogation de l’objet rateLimit retourne le score d’un appel, mais l’exécution de l’appel compte par rapport à la limite. Pour éviter ce dilemme, vous pouvez calculer le score d’un appel avant de l’exécuter. Le calcul suivant donne à peu près le même coût que celui retourné par rateLimit { cost }.

Ajoutez le nombre de demandes nécessaires pour assurer chaque connexion unique dans l’appel. Supposons que chaque demande atteigne les limites de l’argument first ou last.
Divisez le nombre par 100 et arrondissez le résultat pour obtenir le coût d’agrégation final. Cette étape normalise les grands nombres.

Remarque : Le coût minimal d’un appel à l’API GraphQL est 1, représentant une seule demande.

Voici un exemple de calcul de requête et de score :

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

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

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

La satisfaction de cette requête nécessite 5 101 :

Bien que nous retournions 100 dépôts, l’API doit se connecter au compte de la visionneuse une fois pour obtenir la liste des dépôts. Ainsi, les demandes de dépôts = 1
Bien que nous retournions 50 problèmes, l’API doit se connecter à chacun des 100 dépôts pour obtenir la liste des problèmes. Ainsi, les demandes de problèmes = 100
Bien que nous retournions 60 étiquettes, l’API doit se connecter à chacun des 5 000 problèmes potentiels pour obtenir la liste des étiquettes. Ainsi, les demandes d’étiquettes = 5 000
Total = 5 101

Une division par 100 et un arrondi nous donnent le score final de la requête : 51