DOCS

Limitação de taxa da API GraphQL

Saiba como Zonos calcula os custos de consulta com base na complexidade.

A Zonos limita a taxa de solicitações à API GraphQL com base na complexidade da consulta, e não na contagem de solicitações. Isso garante um uso justo, ao mesmo tempo que permite solicitar exatamente os dados necessários.

Por que limitar a taxa com base na complexidade? 

As APIs REST tradicionais usam limitação de taxa baseada em solicitação, onde cada solicitação consome os mesmos créditos, independentemente de você buscar um campo ou centenas, e de ler ou modificar dados, apesar da diferença significativa na carga do servidor.

A abordagem baseada na complexidade de consulta do GraphQL resolve isso calculando os custos com base nos dados reais solicitados e nas operações realizadas. Isso oferece mais flexibilidade para solicitar o que você precisa, ao mesmo tempo que fornece carga previsível do servidor.

Limite de taxa 

Zonos usa um sistema baseado em pontos onde cada consulta deduz pontos com base em sua complexidade. Você tem um conjunto de pontos disponíveis que:

  • Recarrega 750 pontos por segundo (7.500 pontos a cada 10 segundos)
  • Tem capacidade máxima de 75.000 pontos

Isso permite que você faça rajadas ocasionais de consultas complexas, mantendo um ritmo de solicitação sustentável. Se a sua integração precisar de limites mais altos, entre em contato com o suporte da Zonos.

Como o custo da consulta é calculado 

Cada solicitação GraphQL tem um custo calculado antes da execução:

Custos básicos

  • Consulta: 5 pontos
  • Mutação: 10 pontos
  • Objeto: 1 ponto por objeto retornado
  • Campos escalares: 0 pontos (grátis)

Campos escalares como strings, inteiros, IDs e booleanos não aumentam o custo. Você paga apenas pela operação base e pelos objetos devolvidos.

Exemplo: consulta simples

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

Divisão de custos: 5 (consulta base) + 1 (objeto Landed cost) = 6 pontos

Os campos escalares (id, createdBy, shipToCountry) são gratuitos.

Exemplo: Consulta com vários objetos

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

Divisão de custos: 5 (consulta base) + 10 (10 pedidos × 1 ponto cada) = 15 pontos

Exemplo: Mutação

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

Divisão de custos: 10 (mutação base) + aproximadamente 50 (objetos retornados) = 60 pontos

Um cálculo típico de Landed cost custa cerca de 60 pontos em complexidade.

Exemplo: Cotação de Landed cost no mundo real

Uma cotação completa de checkout executa todo o fluxo de trabalho em uma única solicitação: cria a origem e o destino, adiciona os itens do carrinho, faz a cartonização, cota o frete do envio e calcula o 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}

A resposta inclui zonos-query-complexity: 58. Com os limites padrão, isso significa:

  • Taxa sustentada: 750 ÷ 58 ≈ 12 cotações de Landed cost por segundo
  • Rajada: um balde cheio de 75.000 pontos cobre aproximadamente 1.290 cotações antes que você fique limitado à taxa de recarga

Solicitar mais campos no Landed cost, como duties e taxes detalhados, adiciona objetos e aumenta o custo.

Visualizando a complexidade da consulta 

Cada resposta da API inclui um cabeçalho zonos-query-complexity mostrando o custo da sua consulta:

1zonos-query-complexity: 58

Este cabeçalho informa exatamente quantos pontos a consulta consumiu. Use-o para monitorar seu uso de API e otimizar consultas caras.

Lidando com limites de taxa 

Se você exceder seu limite de taxa, receberá uma mensagem de erro. Para lidar com limites de taxa de forma eficaz:

Monitore sua complexidade

Verifique o cabeçalho zonos-query-complexity nas respostas para entender os custos da sua consulta e identificar padrões caros.

Implemente lógica de repetição

Se você atingir os limites de taxa, implemente a espera exponencial e a lógica de nova tentativa. Como o balde é reabastecido em 750 pontos por segundo, calcule os tempos de espera apropriados com base na complexidade da sua consulta.

Agrupe em lotes com eficiência

GraphQL permite solicitar múltiplas consultas em uma única solicitação:

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}

Melhores práticas 

Solicite apenas o que você precisa

A complexidade da consulta é proporcional aos dados solicitados. Estruture suas consultas para buscar apenas os campos e objetos que você realmente usará.

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}

Pagine grandes conjuntos de dados

Ao solicitar vários objetos, use tamanhos de página razoáveis:

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

Solicite de 10 a 50 itens por vez e pagine os resultados conforme necessário, em vez de solicitar centenas de objetos em uma única consulta.

Evite aninhamentos desnecessários

Cada objeto aninhado aumenta sua complexidade. Solicite dados aninhados apenas quando realmente precisar deles.

Esta página foi útil?