DOCS

GraphQL API 요청 속도 제한

Zonos가 복잡도를 기준으로 쿼리 비용을 계산하는 방법을 알아보세요.

Zonos는 요청 횟수가 아니라 쿼리 복잡도를 기준으로 GraphQL API 요청 속도를 제한합니다. 이를 통해 공정한 사용을 보장하면서도 필요한 데이터만 정확히 요청할 수 있습니다.

복잡도 기반 요청 속도 제한을 사용하는 이유 

기존 REST API는 요청 기반 속도 제한을 사용합니다. 이 방식에서는 필드 하나를 가져오든 수백 개를 가져오든, 데이터를 읽든 수정하든 서버 부하에 큰 차이가 있는데도 모든 요청이 같은 크레딧을 소비합니다.

GraphQL의 쿼리 복잡도 기반 방식은 실제로 요청한 데이터와 수행한 작업을 기준으로 비용을 계산해 이 문제를 해결합니다. 서버 부하를 예측 가능하게 유지하면서도 필요한 데이터를 더 유연하게 요청할 수 있습니다.

요청 속도 한도 

Zonos는 각 쿼리의 복잡도에 따라 포인트를 차감하는 포인트 기반 시스템을 사용합니다. 사용 가능한 포인트 풀은 다음과 같습니다.

  • 초당 750포인트(10초당 7,500포인트)씩 다시 채워집니다
  • 최대 용량은 75,000포인트입니다

따라서 지속 가능한 요청 속도를 유지하면서 가끔 복잡한 쿼리를 한꺼번에 보낼 수 있습니다. 통합에 더 높은 한도가 필요하면 Zonos 지원팀에 문의하세요.

쿼리 비용 계산 방식 

모든 GraphQL 요청은 실행 전에 비용이 계산됩니다.

기본 비용

  • 쿼리: 5포인트
  • 뮤테이션: 10포인트
  • 객체: 반환되는 객체당 1포인트
  • 스칼라 필드: 0포인트(무료)

문자열, 정수, ID, 불리언 같은 스칼라 필드는 비용에 포함되지 않습니다. 기본 작업과 반환되는 객체에 대해서만 비용이 부과됩니다.

예시: 단순 쿼리

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

비용 내역: 5(기본 쿼리) + 1(landed cost 객체) = 6포인트

스칼라 필드(id, createdBy, shipToCountry)는 무료입니다.

예시: 여러 객체를 반환하는 쿼리

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

비용 내역: 5(기본 쿼리) + 10(주문 10개 × 각 1포인트) = 15포인트

예시: 뮤테이션

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

비용 내역: 10(기본 뮤테이션) + 약 50(반환되는 객체) = 60포인트

일반적인 landed cost 계산의 복잡도 비용은 약 60포인트입니다.

예시: 실제 landed cost 견적

전체 체크아웃 견적은 하나의 요청으로 전체 워크플로를 실행합니다. 출발지와 도착지를 생성하고, 장바구니 품목을 추가하고, 포장 단위를 구성하고, 배송 요금을 산정한 뒤 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}

응답에는 zonos-query-complexity: 58이 포함됩니다. 기본 한도에서는 다음과 같습니다.

  • 지속 처리량: 750 ÷ 58 ≈ 초당 landed cost 견적 12건
  • 순간 처리량: 75,000포인트가 가득 찬 버킷으로 약 1,290건의 견적을 처리할 수 있으며, 그 이후에는 재충전 속도로 제한됩니다

landed cost에서 항목별 duties, taxes 같은 필드를 더 요청하면 객체가 늘어나 비용이 증가합니다.

쿼리 복잡도 확인 

모든 API 응답에는 쿼리 비용을 보여 주는 zonos-query-complexity 헤더가 포함됩니다.

1zonos-query-complexity: 58

이 헤더는 쿼리가 소비한 포인트를 정확히 알려 줍니다. 이를 활용해 API 사용량을 모니터링하고 비용이 큰 쿼리를 최적화하세요.

요청 속도 제한 처리 

요청 속도 한도를 초과하면 오류 메시지를 받게 됩니다. 요청 속도 제한을 효과적으로 처리하려면 다음을 참고하세요.

복잡도 모니터링

응답의 zonos-query-complexity 헤더를 확인해 쿼리 비용을 파악하고 비용이 큰 패턴을 찾아내세요.

재시도 로직 구현

요청 속도 한도에 도달하면 지수 백오프와 재시도 로직을 구현하세요. 버킷은 초당 750포인트씩 다시 채워지므로, 쿼리 복잡도에 맞춰 적절한 대기 시간을 계산하세요.

효율적인 일괄 처리

GraphQL에서는 하나의 요청에 여러 쿼리를 담아 보낼 수 있습니다.

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}

모범 사례 

필요한 데이터만 요청하기

쿼리 복잡도는 요청하는 데이터의 양에 비례합니다. 실제로 사용할 필드와 객체만 가져오도록 쿼리를 구성하세요.

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}

대규모 데이터 페이지 나누기

여러 객체를 요청할 때는 적절한 페이지 크기를 사용하세요.

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

한 번의 쿼리로 수백 개의 객체를 요청하기보다는 한 번에 10~50개씩 요청하고 필요에 따라 결과를 페이지 단위로 넘기세요.

불필요한 중첩 피하기

중첩된 객체가 하나 추가될 때마다 복잡도가 높아집니다. 중첩 데이터는 실제로 필요할 때만 요청하세요.

이 페이지가 도움이 되었나요?