割り当て

このドキュメントでは、Merchant API に適用される割り当てについて説明します。

Merchant API では、すべてのユーザーに安定した公平な環境を提供するために割り当てを使用しています。割り当てにより、1 人の API ユーザーがシステムに過剰な負荷をかけることを防ぎ、高いパフォーマンスを確保します。これらの割り当てを理解することは、Google で商品データを管理し、ビジネスを拡大するうえで重要です。

一般的なコンセプト

Merchant API の割り当ては、割り当てグループを通じて管理されます。

API メソッドは割り当てグループにマッピングされます。このマッピングの構造は、次のようにさまざまです。

  • グループごとに 1 つのメソッド: 一部の割り当てグループは、1 つの API メソッドに適用されます。たとえば、データソースを一覧表示するメソッド accounts.dataSources.list には、独自の専用の割り当てグループがあります。
  • グループごとに複数のメソッド(バンドル): 多くの場合、関連するメソッドは 1 つの割り当てグループにバンドルされます。そのグループ内のすべてのメソッドは、同じ 1 日あたりの上限と 1 分あたりの上限を共有します。一般的な例:
    • 関連するメソッドとリソース(merchant-accounts-read-methods など)のすべての読み取りオペレーションをグループ化します。
    • 関連するメソッドとリソース(merchant-accounts-write-methods など)のすべての書き込みオペレーションをグループ化する。

各メソッド呼び出しは、タイプに関係なく 1 回としてカウントされます。250 個のアイテムの list リクエストは、250 個の get リクエストではなく、1 回のみカウントされます。

組み込みの HTTP バッチ処理は割り当てに影響しません。バッチ リクエスト内の各リクエストは、割り当てに対して 1 つとしてカウントされます。たとえば、500 件の insert リクエストを含むバッチ リクエストは、500 件の個別の insert メソッド リクエストとして課金されます。

専用リージョン バッチ処理の例外: 専用リージョン バッチ メソッド(batchCreate、batchUpdate、batchDelete)は、ペイロードに含まれるリージョン オペレーションの数に関係なく、merchant_regions 割り当てグループに対して 1 回の API 呼び出しとしてカウントされます。

統合を効果的に管理するには、使用する各 API メソッドに関連付けられた特定の割り当てグループを確認する必要があります。これらの詳細は、割り当てリストメソッドで確認できます。詳細については、モニタリングと可視性をご覧ください。

ポリシーの更新

Merchant API では、更新に関して次のポリシーが適用されます。

  • デフォルトでは、商品を 1 日に 2 回まで更新できます。1 分あたりの割り当てを遵守するために、1 日を通して呼び出しを均等に分散する必要があります。
  • デフォルトでは、サブアカウントを更新できるのは 1 日に 2 回までです。1 日のサブアカウント更新割り当ては、許可されているサブアカウントの合計数に基づく集計上限です。
  • デフォルトでは、list や create などのサブアカウントのデータソース メソッドは、サブアカウントごとに 1 日に 2 回までしか呼び出せません。

レートに基づく割り当て

各割り当てグループには、2 種類の上限(と 1 日の使用量)があります。

  • 1 日あたりの上限(quotaLimit): 1 日に許可されるリクエストの最大数。1 日あたりの割り当て上限は、正午(UTC)にリセットされます。
  • 1 分あたりの上限(quotaMinuteLimit): 1 分間に許可されるリクエストの最大数。リクエストのレートを制御します。1 分あたりの割り当て上限ではローリング ウィンドウが使用されます。この場合、そのメソッドとリソースに対する最初の API 呼び出しが行われた時点から適用期間が開始されます。たとえば、午前 10 時 1 分 30 秒に呼び出しを行うと、そのメソッドの 1 分あたりの割り当てウィンドウは午前 10 時 2 分 30 秒まで実行されます。
  • 1 日の使用量(quotaUsage): すでに実行され、現在の 1 日あたりの上限にカウントされているリクエストの数。このフィールドがない場合、このグループの割り当てはまだ消費されていません。

前述の 3 つのフィールド(quotaLimit、quotaMinuteLimit、quotaUsage)は、quotas.list メソッドのレスポンスで確認できます。

1 日あたりの上限と 1 分あたりの上限は、割り当てグループによって大きく異なります。商品データの読み取りなど、想定されるボリュームが多いオペレーションやシステム費用が低いオペレーションでは、通常、上限が高くなります。逆に、アカウントの変更など、より集中的または機密性の高いオペレーションでは、上限が低くなる可能性があります。

割り当てと階層

このセクションでは、Merchant API が割り当ての使用状況を追跡して適用する対象について説明します。

一般に、割り当ては API リクエストを行うユーザーに基づいて課金されます。

  • スタンドアロン アカウント: API 呼び出しを認証するスタンドアロン アカウントの場合、そのリクエストはそのアカウントの割り当てにカウントされます。
    • 例: 販売者 Shoe Store A(アカウント ID: 12345)が、独自のサービス アカウントを使用して認証を行い、独自のアカウント(accounts/12345)をターゲットとする products.insert を呼び出します。割り当ては、Shoe Store A の割り当てプールから消費されます。
  • アドバンス アカウント: アドバンス アカウントとして認証すると、サブアカウントをターゲットにしている場合でも、アドバンス アカウントのプールから割り当てが消費されます。
    • 例: 代理店の小売管理アカウント(アドバンス アカウント ID: 12345)が、サブアカウントの衣料品店 B(アカウント ID: 11111)を管理しています。代理店は独自の認証情報を使用して認証を行い、衣料品店 B(accounts/11111)をターゲットとする products.insert を呼び出します。割り当ては、サブアカウントのプールではなく、親代理店のプール(アドバンス アカウント ID: 12345)から消費されます。
  • サブアカウント: サブアカウントの認証情報を使用して API 呼び出しが認証されると、そのサブアカウントの個別のプールに割り当てが課金されます。これは、親のアドバンス アカウントによって管理されている場合でも、スタンドアロン アカウントと同じように動作します。
    • 例: 前述と同じ設定を使用している場合、衣料品店 B(アカウント ID: 11111)が、サブアカウント専用に設定された認証情報を使用して認証を行い、自身のアカウント(accounts/11111)をターゲットとする products.insert を呼び出すと、割り当ては衣料品店 B の個別の割り当てプールから消費され、親代理店のプールは消費されません。

一般ルールの例外

割り当ての一般的なルールには、いくつかの例外があります。

  • Accounts.list: このメソッドの割り当ては、Merchant Center アカウント ID ではなく、呼び出しを行う認証済みユーザーまたはサービス アカウントに対して課金されます。割り当ての使用量は、標準の Merchant Center API 診断ページには表示されません。アドバンス アカウントをお持ちの場合は、accounts.listSubaccounts メソッドを使用することをおすすめします。このメソッドは、アドバンス アカウントの割り当てにカウントされます。
  • 問題解決メソッド: これらのメソッドは、別のリクエストを認証している場合でも、問題がリクエストされているアカウントの割り当てに常にカウントされます。

割り当ての階層

  • ショッピング比較サービス(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、それらのアカウント、サブアカウントを最も個別のレベルとして含めることができます。

割り当ての自動調整

Merchant API には、特定のサービス向けの自動割り当て管理システムがあり、使用状況、商品、アカウントの規模に基づいて、成長中の販売者の割り当て上限を調整します。Merchant API は、これらの割り当てを毎日再計算します。

割り当ての自動調整に含まれる割り当てグループは次のとおりです。

製品サービス

  • products リソースと productInputs リソースに関連するメソッドのすべての割り当てグループ。
  • 1 日の呼び出し割り当ては、通常、販売者のオファーの数の 2 倍に設定されます。これは、販売者が各商品を 1 日に最大 2 回更新する必要があることを前提としています。
  • 個々の商品は 2 回以上更新できますが、1 日の API 呼び出しの合計数が 1 日の呼び出し割り当ての合計数を超えないようにしてください。

アカウント サービス

  • Merchant API のさまざまな詳細なアカウント関連リソースに関連するメソッドのすべての割り当てグループ。
  • 1 日の呼び出し割り当ては、そのアカウントで許可されているサブアカウントの最大数に設定されます。これにより、サブアカウントごとに 1 日あたり最大 2 回の読み取り呼び出しが可能になります。

データソース サービス

  • アドバンス アカウントがサブアカウントに対して実行する、Merchant API のデータソース関連リソース(list や create など)に関連するメソッドのすべての割り当てグループ。
  • 1 日の呼び出し割り当ては、通常、アドバンス アカウントのサブアカウント数の 2 倍に設定されます。これは、販売者が各サブアカウントのデータソースを 1 日に最大 2 回更新できることを前提としています。

割り当ての自動調整が行われるのは、前述のサービスのみです。他のサービスにはデフォルトの割り当てがあり、増加をリクエストする場合は手動で行う必要があります。詳細については、割り当て増加プロセスのセクションをご覧ください。

割り当てを超過した場合

割り当てを超えると、API レスポンスと Merchant Center アカウントの診断ページにエラーが表示されます。

  • 1 分あたり: 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"
                }
            }
        ]
    }
}
  • 1 日あたり: 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 Center の制限であり、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: Merchant Center ID
  • ACCESS_TOKEN: API 呼び出しを行うための認証トークン

リクエストが成功すると、API は quotaGroups リソースのリストを返します。このリストには、割り当てグループのリソース name、さまざまな割り当て、グループ割り当てが適用されるメソッドが含まれます。

{
    "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"
        }
    ]
}

割り当て増加プロセス

追加の割り当てをリクエストするには、サポートへのお問い合わせフォームを開き、必須の [問題 / 質問の内容] フィールドで [割り当て増加リクエスト] を選択し、Merchant Center ID、ターゲット メソッド、ビジネス上の理由など、すべての必須フィールドに入力します。

  • 自動割り当てが適用されるリソース(products、accounts、アドバンス アカウントの datasources)の場合: 新しい市場でのリリースやトラフィックの多いショッピング シーズンなど、特別なシナリオでのみ一時的な引き上げをリクエストできます。これらのタイプのリソースについては、割り当ての永続的な増加は受け付けていません。
  • 自動割り当てのない他のすべてのリソースの場合: 必要に応じて割り当ての増加をリクエストします。

割り当てを定期的に確認して、実装に十分な割り当てがあることを確認し、割り当てが自動的に調整される仕組みを確認することをおすすめします。quotas.list メソッドを使用すると、各 API メソッド グループの現在の 1 日あたりの割り当て上限、1 分あたりの上限、現在の 1 日あたりの使用量を確認できます。

ベスト プラクティス

これらのベスト プラクティスを実装すると、統合がスムーズに実行され、予期しない割り当てエラーが回避され、Merchant Center のリソースが効率的に利用されます。

リクエストの分散を最適化する

  • リクエストを均等に分散する: 大量のリクエストをバーストで送信しないようにします。1 日の API 呼び出しを 1 日を通して均等に分散し、1 分あたりの割り当て上限(quotaMinuteLimit)を超えないようにします。
  • プロアクティブなスロットリング: アプリケーションにクライアントサイドのレート制限(スロットリング)を実装します。過剰なトラフィックを拒否するために Google のサーバーのみに依存しないでください。送信元でリクエスト率を制御する。

適切なエラー処理

  • HTTP 429 を処理する: アプリケーションは、429 Too Many Requests エラー(quota/request_rate_too_high)を処理できるように準備する必要があります。
  • ジッターを伴う指数バックオフ: 失敗したリクエストを再試行する場合(特に 429 の後)、指数バックオフ(待機時間の増加)を使用し、「ジッター」(ランダムな遅延)を追加します。ジッターは、複数のクライアント インスタンスがまったく同じタイミングで再試行し、サーバーに再度過負荷をかける「再試行ストーム」を防ぎます。
  • 再試行ヒントを尊重する: API レスポンスに再試行の詳細またはヘッダーが含まれている場合は、それらを使用して呼び出しを再開するタイミングを決定します。

冗長な呼び出しを最小限に抑える

  • 古い呼び出しを防止する(404 NOT_FOUND): 存在しないリソースをリクエストまたは削除しないようにします。失敗した呼び出しでも API 割り当てが消費されます。Merchant Center API 診断で NOT_FOUND エラーをモニタリングして、古い状態のトラッキングや不要なポーリングを検出します。
  • 更新前に確認する: 更新リクエストを送信する前に、データが実際に変更されているかどうかを確認します。同じ値を書き込む更新を送信しないようにします。
  • キャッシュを使用する: 変更されていないデータに対して get または list の呼び出しを繰り返さないように、必要に応じて読み取りレスポンス(商品の詳細、設定など)をローカルにキャッシュします。
  • アドバンス アカウントとサブアカウント: アドバンス アカウントを使用している場合、アドバンス アカウントの共有プールに対して呼び出しをカウントするには、アドバンス アカウント レベルで認証します。
  • listSubaccounts を使用する: アドバンス アカウントの場合は、accounts.list ではなく accounts.listSubaccounts を使用します。accounts.list 割り当ては、呼び出し元のユーザー(MC ID ではない)に課金され、標準の診断には表示されません。listSubaccounts は MCA の割り当てにカウントされます。