Zonos가 복잡도를 기준으로 쿼리 비용을 계산하는 방법을 알아보세요.
Zonos는 요청 횟수가 아니라 쿼리 복잡도를 기준으로 GraphQL API 요청 속도를 제한합니다. 이를 통해 공정한 사용을 보장하면서도 필요한 데이터만 정확히 요청할 수 있습니다.
기존 REST API는 요청 기반 속도 제한을 사용합니다. 이 방식에서는 필드 하나를 가져오든 수백 개를 가져오든, 데이터를 읽든 수정하든 서버 부하에 큰 차이가 있는데도 모든 요청이 같은 크레딧을 소비합니다.
GraphQL의 쿼리 복잡도 기반 방식은 실제로 요청한 데이터와 수행한 작업을 기준으로 비용을 계산해 이 문제를 해결합니다. 서버 부하를 예측 가능하게 유지하면서도 필요한 데이터를 더 유연하게 요청할 수 있습니다.
Zonos는 각 쿼리의 복잡도에 따라 포인트를 차감하는 포인트 기반 시스템을 사용합니다. 사용 가능한 포인트 풀은 다음과 같습니다.
따라서 지속 가능한 요청 속도를 유지하면서 가끔 복잡한 쿼리를 한꺼번에 보낼 수 있습니다. 통합에 더 높은 한도가 필요하면 Zonos 지원팀에 문의하세요.
모든 GraphQL 요청은 실행 전에 비용이 계산됩니다.
문자열, 정수, ID, 불리언 같은 스칼라 필드는 비용에 포함되지 않습니다. 기본 작업과 반환되는 객체에 대해서만 비용이 부과됩니다.
query {
landedCost(id: "123") {
id
createdBy
shipToCountry
}
비용 내역: 5(기본 쿼리) + 1(landed cost 객체) = 6포인트
스칼라 필드(id, createdBy, shipToCountry)는 무료입니다.
{
orders(first: 10, filter: { status: COMPLETED }) {
edges {
cursor
node {
비용 내역: 5(기본 쿼리) + 10(주문 10개 × 각 1포인트) = 15포인트
mutation {
landedCostCalculate(input: { ... }) {
비용 내역: 10(기본 뮤테이션) + 약 50(반환되는 객체) = 60포인트
일반적인 landed cost 계산의 복잡도 비용은 약 60포인트입니다.
전체 체크아웃 견적은 하나의 요청으로 전체 워크플로를 실행합니다. 출발지와 도착지를 생성하고, 장바구니 품목을 추가하고, 포장 단위를 구성하고, 배송 요금을 산정한 뒤 landed cost를 계산합니다.
partyCreateWorkflow(
input: [
type: ORIGIN
location: {
countryCode: US
administrativeAreaCode: "UT"
postalCode: "84790"
type: DESTINATION
countryCode: GB
line1: "10 Downing Street"
locality: "London"
postalCode: "SW1A 2AA"
]
) {
itemCreateWorkflow(
amount: 65
currencyCode: USD
countryOfOrigin: US
quantity: 2
description: "Cotton hoodie"
hsCode: "6110.20"
amount: 18
countryOfOrigin: CN
quantity: 1
description: "Ceramic coffee mug"
hsCode: "6912.00"
cartonizeWorkflow {
shipmentRatingCreateWorkflow(
input: {
amount: 25
serviceLevelCode: "ups.worldwide_expedited"
landedCostCalculateWorkflow(
input: { endUse: FOR_RESALE, method: DDP, tariffRate: ZONOS_PREFERRED }
amountSubtotals {
duties
taxes
fees
landedCostTotal
응답에는 zonos-query-complexity: 58이 포함됩니다. 기본 한도에서는 다음과 같습니다.
zonos-query-complexity: 58
landed cost에서 항목별 duties, taxes 같은 필드를 더 요청하면 객체가 늘어나 비용이 증가합니다.
모든 API 응답에는 쿼리 비용을 보여 주는 zonos-query-complexity 헤더가 포함됩니다.
zonos-query-complexity
이 헤더는 쿼리가 소비한 포인트를 정확히 알려 줍니다. 이를 활용해 API 사용량을 모니터링하고 비용이 큰 쿼리를 최적화하세요.
요청 속도 한도를 초과하면 오류 메시지를 받게 됩니다. 요청 속도 제한을 효과적으로 처리하려면 다음을 참고하세요.
복잡도 모니터링
응답의 zonos-query-complexity 헤더를 확인해 쿼리 비용을 파악하고 비용이 큰 패턴을 찾아내세요.
재시도 로직 구현
요청 속도 한도에 도달하면 지수 백오프와 재시도 로직을 구현하세요. 버킷은 초당 750포인트씩 다시 채워지므로, 쿼리 복잡도에 맞춰 적절한 대기 시간을 계산하세요.
효율적인 일괄 처리
GraphQL에서는 하나의 요청에 여러 쿼리를 담아 보낼 수 있습니다.
landedCost(id: "landed_cost_123") {
createdAt
order(orderId: "order_123") {
status
필요한 데이터만 요청하기
쿼리 복잡도는 요청하는 데이터의 양에 비례합니다. 실제로 사용할 필드와 객체만 가져오도록 쿼리를 구성하세요.
updatedAt
items {
name
quantity
amount
shipments {
대규모 데이터 페이지 나누기
여러 객체를 요청할 때는 적절한 페이지 크기를 사용하세요.
orders(first: 100, filter: { status: COMPLETED }) {
한 번의 쿼리로 수백 개의 객체를 요청하기보다는 한 번에 10~50개씩 요청하고 필요에 따라 결과를 페이지 단위로 넘기세요.
불필요한 중첩 피하기
중첩된 객체가 하나 추가될 때마다 복잡도가 높아집니다. 중첩 데이터는 실제로 필요할 때만 요청하세요.
GraphQL API 요청 속도 제한
GraphQL API 요청 속도 제한
Zonos가 복잡도를 기준으로 쿼리 비용을 계산하는 방법을 알아보세요.
Zonos는 요청 횟수가 아니라 쿼리 복잡도를 기준으로 GraphQL API 요청 속도를 제한합니다. 이를 통해 공정한 사용을 보장하면서도 필요한 데이터만 정확히 요청할 수 있습니다.
복잡도 기반 요청 속도 제한을 사용하는 이유
기존 REST API는 요청 기반 속도 제한을 사용합니다. 이 방식에서는 필드 하나를 가져오든 수백 개를 가져오든, 데이터를 읽든 수정하든 서버 부하에 큰 차이가 있는데도 모든 요청이 같은 크레딧을 소비합니다.
GraphQL의 쿼리 복잡도 기반 방식은 실제로 요청한 데이터와 수행한 작업을 기준으로 비용을 계산해 이 문제를 해결합니다. 서버 부하를 예측 가능하게 유지하면서도 필요한 데이터를 더 유연하게 요청할 수 있습니다.
요청 속도 한도
Zonos는 각 쿼리의 복잡도에 따라 포인트를 차감하는 포인트 기반 시스템을 사용합니다. 사용 가능한 포인트 풀은 다음과 같습니다.
따라서 지속 가능한 요청 속도를 유지하면서 가끔 복잡한 쿼리를 한꺼번에 보낼 수 있습니다. 통합에 더 높은 한도가 필요하면 Zonos 지원팀에 문의하세요.
쿼리 비용 계산 방식
모든 GraphQL 요청은 실행 전에 비용이 계산됩니다.
기본 비용
문자열, 정수, ID, 불리언 같은 스칼라 필드는 비용에 포함되지 않습니다. 기본 작업과 반환되는 객체에 대해서만 비용이 부과됩니다.
예시: 단순 쿼리
query {landedCost(id: "123") {idcreatedByshipToCountry}}비용 내역: 5(기본 쿼리) + 1(landed cost 객체) = 6포인트
스칼라 필드(
id,createdBy,shipToCountry)는 무료입니다.예시: 여러 객체를 반환하는 쿼리
{orders(first: 10, filter: { status: COMPLETED }) {edges {cursornode {id}}}}비용 내역: 5(기본 쿼리) + 10(주문 10개 × 각 1포인트) = 15포인트
예시: 뮤테이션
mutation {landedCostCalculate(input: { ... }) {id}}비용 내역: 10(기본 뮤테이션) + 약 50(반환되는 객체) = 60포인트
일반적인 landed cost 계산의 복잡도 비용은 약 60포인트입니다.
예시: 실제 landed cost 견적
전체 체크아웃 견적은 하나의 요청으로 전체 워크플로를 실행합니다. 출발지와 도착지를 생성하고, 장바구니 품목을 추가하고, 포장 단위를 구성하고, 배송 요금을 산정한 뒤 landed cost를 계산합니다.
mutation {partyCreateWorkflow(input: [{type: ORIGINlocation: {countryCode: USadministrativeAreaCode: "UT"postalCode: "84790"}}{type: DESTINATIONlocation: {countryCode: GBline1: "10 Downing Street"locality: "London"postalCode: "SW1A 2AA"}}]) {id}itemCreateWorkflow(input: [{amount: 65currencyCode: USDcountryOfOrigin: USquantity: 2description: "Cotton hoodie"hsCode: "6110.20"}{amount: 18currencyCode: USDcountryOfOrigin: CNquantity: 1description: "Ceramic coffee mug"hsCode: "6912.00"}]) {id}cartonizeWorkflow {id}shipmentRatingCreateWorkflow(input: {amount: 25currencyCode: USDserviceLevelCode: "ups.worldwide_expedited"}) {id}landedCostCalculateWorkflow(input: { endUse: FOR_RESALE, method: DDP, tariffRate: ZONOS_PREFERRED }) {idamountSubtotals {dutiestaxesfeeslandedCostTotal}}}응답에는
zonos-query-complexity: 58이 포함됩니다. 기본 한도에서는 다음과 같습니다.landed cost에서 항목별
duties,taxes같은 필드를 더 요청하면 객체가 늘어나 비용이 증가합니다.쿼리 복잡도 확인
모든 API 응답에는 쿼리 비용을 보여 주는
zonos-query-complexity헤더가 포함됩니다.zonos-query-complexity: 58이 헤더는 쿼리가 소비한 포인트를 정확히 알려 줍니다. 이를 활용해 API 사용량을 모니터링하고 비용이 큰 쿼리를 최적화하세요.
요청 속도 제한 처리
요청 속도 한도를 초과하면 오류 메시지를 받게 됩니다. 요청 속도 제한을 효과적으로 처리하려면 다음을 참고하세요.
복잡도 모니터링
응답의
zonos-query-complexity헤더를 확인해 쿼리 비용을 파악하고 비용이 큰 패턴을 찾아내세요.재시도 로직 구현
요청 속도 한도에 도달하면 지수 백오프와 재시도 로직을 구현하세요. 버킷은 초당 750포인트씩 다시 채워지므로, 쿼리 복잡도에 맞춰 적절한 대기 시간을 계산하세요.
효율적인 일괄 처리
GraphQL에서는 하나의 요청에 여러 쿼리를 담아 보낼 수 있습니다.
{landedCost(id: "landed_cost_123") {idcreatedAt}order(orderId: "order_123") {idstatuscreatedAt}}모범 사례
필요한 데이터만 요청하기
쿼리 복잡도는 요청하는 데이터의 양에 비례합니다. 실제로 사용할 필드와 객체만 가져오도록 쿼리를 구성하세요.
query {order(orderId: "order_123") {idstatuscreatedAtupdatedAtitems {idnamequantityamount}shipments {id}}}대규모 데이터 페이지 나누기
여러 객체를 요청할 때는 적절한 페이지 크기를 사용하세요.
{orders(first: 100, filter: { status: COMPLETED }) {edges {cursornode {id}}}}한 번의 쿼리로 수백 개의 객체를 요청하기보다는 한 번에 10~50개씩 요청하고 필요에 따라 결과를 페이지 단위로 넘기세요.
불필요한 중첩 피하기
중첩된 객체가 하나 추가될 때마다 복잡도가 높아집니다. 중첩 데이터는 실제로 필요할 때만 요청하세요.
이 페이지가 도움이 되었나요?