할당량

이 문서에는 Merchant API에 적용되는 할당량이 나와 있습니다.

Merchant API는 모든 사용자를 위해 안정적이고 공정한 환경을 보장하기 위해 할당량을 사용합니다. 할당량은 단일 API 사용자가 시스템에 과도한 부하를 가하지 않도록 방지하여 높은 성능을 보장합니다. 이러한 할당량을 이해하는 것은 제품 데이터를 관리하고 Google에서 비즈니스를 확장하는 데 중요합니다.

일반적인 개념

Merchant API 할당량은 할당량 그룹을 통해 관리됩니다.

API 메서드는 할당량 그룹에 매핑됩니다. 이 매핑의 구조는 다음과 같이 다를 수 있습니다.

  • 그룹당 단일 메서드: 일부 할당량 그룹은 단일 API 메서드에 적용됩니다. 예를 들어 목록 데이터 소스 메서드 accounts.dataSources.list에는 전용 할당량 그룹이 있습니다.
  • 그룹당 여러 메서드 (번들링): 관련 메서드는 단일 할당량 그룹으로 번들링되는 경우가 많습니다. 해당 그룹 내의 모든 메서드는 동일한 일별 및 분당 한도를 공유합니다. 일반적인 예는 다음과 같습니다.
    • merchant-accounts-read-methods와 같은 관련 메서드 및 리소스의 모든 읽기 작업을 그룹화합니다.
    • merchant-accounts-write-methods과 같은 관련 메서드 및 리소스의 모든 쓰기 작업을 그룹화합니다.

각 메서드 호출은 유형에 관계없이 한 번씩 집계됩니다. 항목이 250개인 list 요청은 get 요청 250개가 아닌 한 번으로 계산됩니다.

기본 제공 HTTP 일괄 처리는 할당량에 영향을 미치지 않습니다. 요청 일괄 처리 내의 각 단일 요청은 할당량에 대해 1로 계산됩니다. 예를 들어 500개의 insert 요청이 포함된 일괄 요청은 500개의 개별 insert 메서드 요청으로 청구됩니다.

전용 리전 일괄 처리 예외: 전문 리전 일괄 처리 메서드(batchCreate, batchUpdate, batchDelete)는 페이로드에 포함된 리전 작업 수와 관계없이 merchant_regions 할당량 그룹에 대해 단일 API 호출로 계산됩니다.

통합을 효과적으로 관리하려면 사용하려는 각 API 메서드와 연결된 특정 할당량 그룹을 검토해야 합니다. 이러한 세부정보는 할당량 목록 메서드에서 확인할 수 있습니다. 자세한 내용은 모니터링 및 가시성을 참고하세요.

정책 업데이트

Merchant API는 업데이트와 관련하여 다음 정책을 적용합니다.

  • 기본적으로 제품은 하루에 최대 2번까지 업데이트할 수 있습니다. 분당 할당량을 준수하려면 하루 종일 통화를 균등하게 분산해야 합니다.
  • 기본적으로 하위 계정은 하루에 최대 두 번만 업데이트할 수 있습니다. 일일 하위 계정 업데이트 할당량은 허용된 총 하위 계정을 기준으로 한 집계 한도입니다.
  • 기본적으로 하위 계정의 데이터 소스 메서드(예: list 또는 create)는 하위 계정당 하루에 최대 두 번만 호출할 수 있습니다.

비율 할당량

각 할당량 그룹에는 다음과 같은 두 가지 유형의 한도 (및 일일 사용량)가 있습니다.

  • 일일 한도 (quotaLimit): 하루에 허용되는 최대 요청 수입니다. 일일 할당량 한도는 오후 12시(UTC)에 재설정됩니다.
  • 분당 한도 (quotaMinuteLimit): 분당 허용되는 최대 요청 수로, 요청 비율을 제어합니다. 분당 할당량 제한은 순환 기간을 사용하며, 이 기간은 해당 메서드와 리소스에 대한 첫 번째 API 호출이 이루어진 순간부터 시작됩니다. 예를 들어 오전 10시 1분 30초에 호출하면 해당 메서드의 분당 할당량 기간은 오전 10시 2분 30초까지입니다.
  • 일일 사용량 (quotaUsage): 이미 요청되었으며 당일 일일 한도에 포함된 요청 수입니다. 필드가 누락된 경우 이 그룹에 아직 할당량이 사용되지 않은 것입니다.

이전에 설명한 세 필드 (quotaLimit, quotaMinuteLimit, quotaUsage)는 quotas.list 메서드의 응답에서 확인할 수 있습니다.

구체적인 일일 및 분당 한도는 할당량 그룹마다 크게 다릅니다. 제품 데이터 읽기와 같이 예상 볼륨이 높거나 시스템 비용이 낮은 작업에는 일반적으로 한도가 더 높습니다. 반대로 계정 수정과 같이 더 집약적이거나 민감한 작업에는 더 낮은 한도가 적용될 수 있습니다.

할당량 할당 및 계층 구조

이 섹션에서는 Merchant API가 할당량 사용량을 추적하고 적용하는 주체를 설명합니다.

일반적으로 할당량은 API 요청을 하는 사용자를 기준으로 청구됩니다.

  • 독립형 계정: API 호출을 인증하는 독립형 계정의 경우 해당 요청은 해당 계정의 할당량에 포함됩니다.
    • 예: 판매자 신발 매장 A (계정 ID: 12345)가 자체 서비스 계정을 사용하여 인증하고 자체 계정 (accounts/12345)을 타겟팅하는 products.insert를 호출합니다. 할당량은 신발 매장 A의 할당량 풀에서 사용됩니다.
  • 고급 계정: 고급 계정으로 인증하면 하위 계정을 타겟팅하는 경우에도 고급 계정 풀의 할당량이 소모됩니다.
    • 예: 대행사 소매 관리 계정 (고급 계정 ID: 12345)이 하위 계정 의류 매장 B (계정 ID: 11111)를 관리합니다. 대행사는 자체 사용자 인증 정보를 사용하여 인증하고 의류 매장 B (accounts/11111)를 타겟팅하는 products.insert를 호출합니다. 할당량은 하위 계정 풀이 아닌 상위 대행사의 풀 (고급 계정 ID: 12345)에서 사용됩니다.
  • 하위 계정: 하위 계정의 사용자 인증 정보를 사용하여 API 호출이 인증되면 할당량이 해당 하위 계정의 개별 풀에 청구됩니다. 이 계정은 부모 고급 계정에서 관리하지만 독립형 계정과 동일한 방식으로 작동합니다.
    • 예: 이전과 동일한 설정을 사용하는 경우 의류 매장 B(계정 ID: 11111)가 하위 계정을 위해 특별히 설정된 사용자 인증 정보를 사용하여 자체 계정 (accounts/11111)을 타겟팅하는 products.insert를 호출하면 의류 매장 B의 개별 할당량 풀에서 할당량이 소진되어 상위 대행사의 풀은 그대로 유지됩니다.

일반 규칙의 예외

할당량 할당 일반 규칙에는 몇 가지 구체적인 예외가 적용됩니다.

  • Accounts.list: 이 메서드의 할당량은 판매자 센터 계정 ID가 아닌 호출을 실행하는 인증된 사용자 또는 서비스 계정에 청구됩니다. 할당량 사용량이 표준 판매자 센터 API 진단 페이지에 표시되지 않습니다. 고급 계정이 있는 경우 고급 계정 할당량에 포함되는 accounts.listSubaccounts 메서드를 사용하는 것이 좋습니다.
  • Issueresolution methods: 이러한 메서드는 다른 계정에서 요청을 인증하는 경우에도 문제가 요청된 계정의 할당량에 항상 포함됩니다.

할당 계층 구조

  • 비교 쇼핑 서비스 (CSS): CSS는 제품 혜택을 집계하고 사용자를 소매업체 웹사이트로 안내하여 구매를 유도하는 웹사이트입니다. API 호출 시 인증에 사용한 특정 CSS 그룹, CSS 도메인, 계정 또는 하위 계정에 할당량이 적용됩니다.

    예:

    • Europe Shopping Group (계정 ID: 10001)이라는 CSS 그룹이 연결된 CSS 도메인을 나열하려고 합니다. 자체 사용자 인증 정보로 인증하여 이 API 호출을 하면 할당량이 Europe Shopping Group 할당량 풀에서 직접 사용됩니다.
    • CSS 도메인 TopDeals CSS (계정 ID: 20002)가 연결된 판매자 계정(accounts/30003) 중 하나를 타겟팅하는 메서드를 호출하여 라벨을 할당하도록 인증합니다. 할당량은 판매자 계정 풀이 아닌 TopDeals CSS 할당량 풀에서 사용됩니다.

  • 마켓: 마켓은 여러 개인 판매자를 호스팅하는 온라인 플랫폼입니다. 판매자별로 개별 하위 계정을 만들 수 있는 특수한 고급 계정으로 작동합니다.

다음 다이어그램은 CSS 그룹, CSS, 마켓, 고급 계정, 독립형 계정, 하위 계정의 계층 구조를 보여줍니다.

CSS 그룹은 전반적인 인증 수준이며, 그 안에 개별 CSS, 해당 CSS 내의 계정, 가장 개별적인 수준인 하위 계정이 있을 수 있습니다.

자동 할당량 조정

Merchant API에는 특정 서비스를 위한 자동 할당량 관리 시스템이 있으며, 이 시스템은 사용량, 제품, 계정 크기에 따라 성장하는 판매자의 할당량 한도를 조정합니다. Merchant API는 이러한 할당량을 매일 다시 계산합니다.

자동 할당량 조정에 포함되는 할당량 그룹은 다음과 같습니다.

제품 서비스

  • products 및 productInputs 리소스와 관련된 메서드의 모든 할당량 그룹입니다.
  • 일일 통화 할당량은 일반적으로 판매자가 보유한 제품 할당량의 2배로 설정됩니다. 이는 판매자가 제품을 하루에 최대 두 번 업데이트해야 할 수 있다고 가정합니다.
  • 개별 제품은 두 번 이상 업데이트할 수 있지만 전체 일일 API 호출은 집계된 일일 호출 할당량을 초과할 수 없습니다.

계정 서비스

  • Merchant API의 다양한 세부 계정 관련 리소스와 관련된 메서드의 모든 할당량 그룹입니다.
  • 일일 호출 할당량이 해당 계정에 허용되는 최대 하위 계정 수로 설정됩니다. 이렇게 하면 하루에 하위 계정당 최대 2회의 읽기 호출이 허용됩니다.

데이터 소스 서비스

  • 고급 계정이 하위 계정에서 실행하는 Merchant API의 데이터 소스 관련 리소스(예: list 또는 create)와 관련된 메서드의 모든 할당량 그룹입니다.
  • 일일 호출 할당량은 일반적으로 고급 계정에 있는 하위 계정 수의 2배로 설정됩니다. 이는 판매자가 각 하위 계정의 데이터 소스를 하루에 최대 두 번까지 업데이트할 수 있다고 가정합니다.

앞서 설명한 서비스만 할당량이 자동으로 조정됩니다. 다른 서비스에는 기본 할당량이 있으며, 할당량 증가는 수동으로 요청해야 합니다. 자세한 내용은 할당량 상향 프로세스 섹션을 참고하세요.

할당량을 초과하면 어떻게 되나요?

할당량을 초과하면 API 응답과 판매자 센터 계정의 진단 페이지에 오류가 표시됩니다.

  • 분당: quota/request_rate_too_high
{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}
  • 일일: quota/daily_limit_exceeded
{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

다음 오류는 판매자 센터 한도이며 Merchant API 할당량과는 관련이 없습니다. 상품, 피드 또는 하위 계정의 추가 할당량을 요청해 보세요.

  • too_many_items: 판매자 할당량 초과
  • too_many_subaccounts: 최대 하위 계정 수에 도달함

모니터링 및 가시성

계정의 현재 호출 할당량과 사용량을 확인하려면 계정 이름과 함께 quotas.list를 호출합니다.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

다음을 바꿉니다.

  • ACCOUNT_ID: 판매자 센터 ID
  • ACCESS_TOKEN: API 호출을 실행하는 승인 토큰

요청에 성공하면 API는 할당량 그룹의 리소스 name, 다양한 할당량, 그룹 할당량이 적용되는 메서드가 포함된 quotaGroups 리소스 목록을 반환합니다.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

할당량 상향 프로세스

추가 할당량을 요청하려면 지원팀에 문의 양식을 열고, 필수 '문제/질문' 필드에서 '할당량 상향 요청'을 선택한 후 판매자 센터 ID, 타겟 메서드, 비즈니스 근거 등 필수 필드를 모두 작성합니다.

  • 자동 할당량이 있는 리소스 (고급 계정의 경우 products, accounts, datasources): 새 시장 출시 또는 트래픽이 많은 쇼핑 시즌과 같은 특별한 시나리오에 대해서만 일시적인 증가를 요청할 수 있습니다. 이러한 유형의 리소스에 대해서는 영구 할당량 증가가 허용되지 않습니다.
  • 자동 할당량이 없는 다른 모든 리소스: 필요에 따라 할당량 증가를 요청합니다.

구현에 충분한 할당량이 있는지 주기적으로 확인하고 할당량이 자동으로 조정되는 방식을 확인하는 것이 좋습니다. quotas.list 메서드를 사용하여 각 API 메서드 그룹의 현재 일일 할당량 한도, 분당 한도, 현재 일일 사용량을 확인합니다.

권장사항

이러한 권장사항을 구현하면 통합이 원활하게 실행되고, 예기치 않은 할당량 오류를 방지하며, 판매자 센터 리소스를 효율적으로 사용할 수 있습니다.

요청 배포 최적화

  • 요청을 균등하게 분산: 대량의 요청을 한 번에 보내지 마세요. 분당 할당량 한도 (quotaMinuteLimit)를 초과하지 않도록 일일 API 호출을 하루 종일 균등하게 분산하세요.
  • 사전 제한: 애플리케이션에서 클라이언트 측 비율 제한 (제한)을 구현합니다. 과도한 트래픽을 거부할 때 Google 서버에만 의존하지 마세요. 소스에서 요청 비율을 제어합니다.

적절한 오류 처리

  • HTTP 429 처리: 애플리케이션이 429 요청이 너무 많음 오류 (quota/request_rate_too_high)를 처리할 수 있어야 합니다.
  • 지터링을 사용한 지수 백오프: 실패한 요청(특히 429 이후)을 재시도할 때는 지수 백오프 (대기 시간 증가)를 사용하고 '지터' (무작위 지연)를 추가합니다. 지터는 여러 클라이언트 인스턴스가 정확히 동시에 재시도하여 서버에 다시 과부하를 주는 '재시도 폭풍'을 방지합니다.
  • 재시도 힌트 준수: API 응답에 재시도 세부정보나 헤더가 포함된 경우 이를 사용하여 호출을 재개할 시점을 결정합니다.

중복 호출 최소화

  • 오래된 호출 방지 (404 NOT_FOUND): 더 이상 존재하지 않는 리소스를 요청하거나 삭제하지 마세요. 실패한 호출도 API 할당량을 소비합니다. 판매자 센터 API 진단에서 NOT_FOUND 오류를 모니터링하여 오래된 상태 추적 또는 불필요한 폴링을 감지합니다.
  • 업데이트 전 확인: 업데이트 요청을 보내기 전에 데이터가 실제로 변경되었는지 확인합니다. 동일한 값을 쓰는 업데이트는 보내지 마세요.
  • 캐싱 사용: 변경되지 않은 데이터에 대한 반복적인 get 또는 list 호출을 방지하기 위해 적절한 경우 읽기 응답 (예: 제품 세부정보, 설정)을 로컬로 캐시합니다.
  • 고급 계정 및 하위 계정: 고급 계정인 경우 통화가 고급 계정의 공유 풀에 포함되도록 하려면 고급 계정 수준에서 인증하세요.
  • listSubaccounts 사용: 고급 계정의 경우 accounts.list 대신 accounts.listSubaccounts을 사용합니다. accounts.list 할당량은 호출 사용자 (MC ID 아님)에게 청구되며 표준 진단에는 표시되지 않습니다. listSubaccounts는 MCA 할당량에 포함됩니다.
이전
Overview
다음
Merchant Center limits