DOCS

Limitation de débit de l'API GraphQL

Découvrez comment Zonos calcule le coût des requêtes selon leur complexité.

Zonos limite les requêtes à l'API GraphQL selon leur complexité plutôt que selon leur nombre. Cette approche garantit une utilisation équitable tout en vous permettant de demander exactement les données dont vous avez besoin.

Pourquoi une limitation de débit basée sur la complexité? 

Les API REST traditionnelles utilisent une limitation de débit basée sur le nombre de requêtes : 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é l'écart considérable de charge sur le serveur.

L'approche de GraphQL, fondée sur la complexité des requêtes, règle ce problème en calculant les coûts selon les données réellement demandées et les opérations effectuées. Vous avez ainsi plus de latitude pour demander ce dont vous avez besoin, tout en assurant une charge prévisible sur le serveur.

Limite de débit 

Zonos utilise un système de points où chaque requête déduit des points selon sa complexité. Vous disposez d'une réserve de points disponibles qui :

  • se recharge à raison de 750 points par seconde (7 500 points par 10 secondes);
  • a une capacité maximale de 75 000 points.

Vous pouvez ainsi effectuer à l'occasion des rafales de requêtes complexes tout en maintenant un rythme de requêtes soutenable. Si votre intégration a besoin de limites plus élevées, communiquez avec le soutien Zonos.

Calcul du coût d'une requête 

Le coût de chaque requête GraphQL est calculé avant son exécution :

Coûts de base

  • Requête : 5 points
  • Mutation : 10 points
  • Objet : 1 point par objet renvoyé
  • Champs scalaires : 0 point (gratuits)

Les champs scalaires comme les chaînes, les entiers, les identifiants et les booléens n'augmentent pas le coût. Vous ne payez que pour l'opération de base et les objets renvoyés.

Exemple : requête simple

1query {
2 landedCost(id: "123") {
3 id
4 createdBy
5 shipToCountry
6 }
7}

Ventilation du coût : 5 (requête de base) + 1 (objet landed cost) = 6 points

Les champs scalaires (id, createdBy, shipToCountry) sont gratuits.

Exemple : requête avec plusieurs objets

1{
2 orders(first: 10, filter: { status: COMPLETED }) {
3 edges {
4 cursor
5 node {
6 id
7 }
8 }
9 }
10}

Ventilation du coût : 5 (requête de base) + 10 (10 commandes × 1 point chacune) = 15 points

Exemple : mutation

1mutation {
2 landedCostCalculate(input: { ... }) {
3 id
4 }
5}

Ventilation du coût : 10 (mutation de base) + environ 50 (objets renvoyés) = 60 points

Un calcul de landed cost typique coûte environ 60 points de complexité.

Exemple : soumission de landed cost réelle

Une soumission complète au moment du paiement exécute tout le flux de travail en une seule requête : créer l'origine et la destination, ajouter les articles du panier, faire la mise en carton, obtenir le tarif de l'envoi et calculer le landed cost.

1mutation {
2 partyCreateWorkflow(
3 input: [
4 {
5 type: ORIGIN
6 location: {
7 countryCode: US
8 administrativeAreaCode: "UT"
9 postalCode: "84790"
10 }
11 }
12 {
13 type: DESTINATION
14 location: {
15 countryCode: GB
16 line1: "10 Downing Street"
17 locality: "London"
18 postalCode: "SW1A 2AA"
19 }
20 }
21 ]
22 ) {
23 id
24 }
25 itemCreateWorkflow(
26 input: [
27 {
28 amount: 65
29 currencyCode: USD
30 countryOfOrigin: US
31 quantity: 2
32 description: "Cotton hoodie"
33 hsCode: "6110.20"
34 }
35 {
36 amount: 18
37 currencyCode: USD
38 countryOfOrigin: CN
39 quantity: 1
40 description: "Ceramic coffee mug"
41 hsCode: "6912.00"
42 }
43 ]
44 ) {
45 id
46 }
47 cartonizeWorkflow {
48 id
49 }
50 shipmentRatingCreateWorkflow(
51 input: {
52 amount: 25
53 currencyCode: USD
54 serviceLevelCode: "ups.worldwide_expedited"
55 }
56 ) {
57 id
58 }
59 landedCostCalculateWorkflow(
60 input: { endUse: FOR_RESALE, method: DDP, tariffRate: ZONOS_PREFERRED }
61 ) {
62 id
63 amountSubtotals {
64 duties
65 taxes
66 fees
67 landedCostTotal
68 }
69 }
70}

La réponse inclut zonos-query-complexity: 58. Avec les limites par défaut, cela signifie :

  • Débit soutenu : 750 ÷ 58 ≈ 12 soumissions de landed cost par seconde
  • Rafale : une réserve pleine de 75 000 points couvre environ 1 290 soumissions avant que vous soyez limité au débit de recharge

Demander plus de champs sur le landed cost, comme le détail des duties et des taxes, ajoute des objets et augmente le coût.

Consulter la complexité d'une requête 

Chaque réponse de l'API inclut un en-tête zonos-query-complexity qui indique le coût de votre requête :

1zonos-query-complexity: 58

Cet 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 le coût de vos requêtes et repérer les modèles coûteux.

Mettez en place une logique de nouvelle tentative

Si vous atteignez les limites de débit, mettez en place un délai d'attente exponentiel (backoff) et une logique de nouvelle tentative. Comme la réserve se recharge à raison de 750 points par seconde, calculez des temps d'attente appropriés selon la complexité de votre requête.

Regroupez efficacement

GraphQL vous permet de formuler plusieurs requêtes en un seul appel :

1{
2 landedCost(id: "landed_cost_123") {
3 id
4 createdAt
5 }
6 order(orderId: "order_123") {
7 id
8 status
9 createdAt
10 }
11}

Bonnes pratiques 

Demandez uniquement ce dont vous avez besoin

La complexité d'une requête est proportionnelle aux données que vous demandez. Structurez vos requêtes pour ne récupérer que les champs et les objets que vous utiliserez réellement.

1query {
2 order(orderId: "order_123") {
3 id
4 status
5 createdAt
6 updatedAt
7 items {
8 id
9 name
10 quantity
11 amount
12 }
13 shipments {
14 id
15 }
16 }
17}

Paginez les grands ensembles de données

Lorsque vous demandez plusieurs objets, utilisez des tailles de page raisonnables :

1{
2 orders(first: 100, filter: { status: COMPLETED }) {
3 edges {
4 cursor
5 node {
6 id
7 }
8 }
9 }
10}

Demandez de 10 à 50 éléments à la fois et parcourez les résultats page par page au besoin, plutôt que de demander des centaines d'objets en une seule requête.

Évitez l'imbrication inutile

Chaque objet imbriqué augmente votre complexité. Ne demandez des données imbriquées que lorsque vous en avez réellement besoin.

Réserver une démo

Cette page vous a-t-elle été utile?