Pourquoi une limitation de débit basée sur la complexité ?
Les API REST traditionnelles utilisent une limitation de débit basée sur les requêtes où chaque requête consomme les mêmes crédits, que vous récupériez un champ ou des centaines, et que vous lisiez ou modifiiez des données — malgré la différence significative de charge serveur.
L'approche GraphQL basée sur la complexité des requêtes résout cela en calculant les coûts selon les données réellement demandées et les opérations effectuées. Cela vous offre plus de flexibilité pour demander ce dont vous avez besoin tout en fournissant une charge serveur prévisible.
Limite de débit
Zonos utilise un système basé sur des points où chaque requête déduit des points selon sa complexité. Vous disposez d'un pool de points disponibles qui :
- Se recharge à 3 000 points par seconde (30 000 points par 10 secondes)
- A une capacité maximale de 300 000 points
Cela vous permet d'effectuer occasionnellement des rafales de requêtes complexes tout en maintenant un rythme de requêtes durable.
Comment le coût de requête est calculé
Chaque requête GraphQL a un coût calculé avant l'exécution :
Coûts de base
- Requête : 5 points
- Mutation : 10 points
- Objet : 1 point par objet renvoyé
- Champs scalaires : 0 point (gratuit)
Les champs scalaires comme les chaînes, entiers, identifiants et booléens n'ajoutent pas au coût. Vous ne payez que pour l'opération de base et les objets renvoyés.
Exemple : requête simple
query { landedCost(id: "123") { id createdBy shipToCountry }}Ventilation du coût : 5 (requête de base) + 1 (objet landed cost) = 6 points
Les champs scalaires (id, name, currency) sont gratuits.
Exemple : requête avec plusieurs objets
{ orders(first: 10, filter: { status: COMPLETED }) { edges { cursor node { id } } }}Ventilation du coût : 5 (requête de base) + 10 (10 commandes × 1 point chacune) = 15 points
Exemple : mutation
mutation { landedCostCalculate(input: { ... }) { id }}Ventilation du coût : 10 (mutation de base) + environ 50 (objets renvoyés) = 60 points
Un calcul Landed Cost typique coûte environ 60 points en complexité.
Consulter la complexité de requête
Chaque réponse API inclut un en-tête zonos-query-complexity indiquant le coût de votre requête :
zonos-query-complexity: 58Cet en-tête indique exactement combien de points la requête a consommés. Utilisez-le pour surveiller votre utilisation de l'API et optimiser les requêtes coûteuses.
Gérer les limites de débit
Si vous dépassez votre limite de débit, vous recevrez un message d'erreur. Pour gérer efficacement les limites de débit :
Surveillez votre complexité
Vérifiez l'en-tête zonos-query-complexity dans les réponses pour comprendre vos coûts de requête et identifier les modèles coûteux.
Implémentez une logique de nouvelle tentative
Si vous atteignez les limites de débit, implémentez un backoff exponentiel et une logique de nouvelle tentative. Comme le pool se recharge à 3 000 points par seconde, calculez des temps d'attente appropriés selon la complexité de votre requête.
Regroupez efficacement
GraphQL vous permet de demander plusieurs requêtes en une seule requête :
{ landedCost(id: "landed_cost_123") { id createdAt } order(orderId: "order_123") { id status createdAt }}Bonnes pratiques
Demandez uniquement ce dont vous avez besoin
La complexité de requête est proportionnelle aux données que vous demandez. Structurez vos requêtes pour récupérer uniquement les champs et objets que vous utiliserez réellement.
query { order(orderId: "order_123") { id status createdAt updatedAt items { id name quantity amount } shipments { id } }}Paginez les grands ensembles de données
Lors de la demande de plusieurs objets, utilisez des tailles de page raisonnables :
{ orders(first: 100, filter: { status: COMPLETED }) { edges { cursor node { id } } }}Demandez 10 à 50 éléments à la fois et paginez les résultats selon les besoins, plutôt que de demander des centaines d'objets en une seule requête.
Évitez l'imbrication inutile
Chaque objet imbriqué ajoute à votre complexité. Ne demandez des données imbriquées que lorsque vous en avez réellement besoin.
Limitation de débit API GraphQL
Découvrez comment Zonos calcule les coûts de requête selon la complexité.
Zonos limite les requêtes API GraphQL selon la complexité de la requête plutôt que le nombre de requêtes. Cela garantit une utilisation équitable tout en vous permettant de demander exactement les données dont vous avez besoin.