このページは Cloud Translation API によって翻訳されました。

商品カタログを管理する

このガイドでは、Google Play Developer API を使用して Play アプリの商品カタログを作成し、管理する方法について説明します。

Google Play の課金システムを使用してアプリ内でアイテムを販売するには、ユーザーが購入できるようにするすべてのアイテムを含むカタログを設定する必要があります。これは Google Play Console から行うことができます。また、Google Play Developer API を使用してカタログ管理を自動化することもできます。自動化により、カタログを常に最新の状態に保ち、手動での調整が不可能な大規模なカタログにスケーリングできます。このガイドでは、Google Play Developer API を使用して Google Play アプリの商品カタログを作成、管理する方法について説明します。バックエンド統合用に Google Play Developer API を設定する方法については、準備ガイドをご覧ください。

Catalog Management API

Google Play の課金システムで販売できるさまざまな種類の商品については、アプリ内アイテムのタイプとカタログに関する考慮事項についてをご覧ください。Google Play のカタログ管理には、次の 2 つの主な API セットがあります。これは、2 つの主なプロダクトカテゴリに対応しています。

1 回限りのアイテム
定期購入商品

1 回限りのアイテム

inappproducts エンドポイントを使用すると、バックエンドから 1 回限りの商品を管理できます。これには、商品の作成、更新、削除、価格と在庫状況の管理が含まれます。1 回限りのアイテムの購入方法に応じて、消費型アイテム（必要な回数だけ購入可能）または永続的な利用資格（同じユーザーが 2 回購入することはできない）をモデル化します。1 回限りのアイテムを消費可能にするかしないかを指定できます。

定期購入商品

monetization.subscriptions エンドポイントは、デベロッパーのバックエンドからサブスクリプションプロダクトを管理するのに役立ちます。サブスクリプションの作成、更新、削除、地域別の在庫状況と価格の管理などを行うことができます。monetization.subscriptions エンドポイントに加えて、定期購入の基本プランと特典をそれぞれ管理するための monetization.subscriptions.basePlans と monetization.subscriptions.basePlans.offers も用意されています。

バッチメソッド

inappproducts エンドポイントと monetization.subscriptions エンドポイントには、同じアプリ内の最大 100 個のエンティティを同時に取得または管理できる一連のバッチメソッドが用意されています。

バッチ方法は、レイテンシトラーランスを有効にして使用すると、より高いスループットをサポートします。大規模なカタログのデベロッパーが、最初のカタログの作成やカタログの調整を行う場合に特に便利です。

更新伝播レイテンシとスループット

商品の作成または変更リクエストが完了しても、ネットワークまたはバックエンドの処理の遅延により、エンドユーザーのデバイスに変更がすぐに反映されない場合があります。デフォルトでは、すべての商品変更リクエストはレイテンシの影響を受けます。つまり、バックエンドシステムを介して迅速に伝播するように最適化されており、通常は数分以内にエンドユーザーデバイスに反映されます。ただし、このような変更リクエストの数には 1 時間あたりの上限があります。大量の商品を作成または更新する必要がある場合（大規模なカタログの最初の作成時など）は、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定してバッチメソッドを使用できます。これにより、更新スループットが大幅に向上します。レイテンシに強いアップデートがエンドユーザーデバイスに反映されるまでには、最長で 24 時間かかります。

割り当ての構成

Play Developer API を使用して商品カタログを管理する場合は、次の割り当て上限に注意してください。

Google Play Developer API で実行するクエリは、デフォルトで 1 日あたり 200,000 件に制限されています。この割り当て上限は、カタログ管理 API を含むすべてのエンドポイントでの使用量の集計に適用されます。
商品変更エンドポイントには、1 時間あたり 7,200 件のクエリの上限も適用されます。これは、1 回限りのアイテムと定期購入の両方、および作成、更新、有効化、削除など、すべての変更リクエストに適用される単一の上限です。バッチ変更メソッドの呼び出しは、含まれる個々のリクエストの数やレイテンシの機密性に関わらず、この割り当てでは 1 つのクエリとしてカウントされます。
レイテンシに敏感な変更にも、1 時間あたり 7,200 件の変更の上限があります。バッチメソッドの場合、この割り当ての目的では、ネストされた変更リクエストはすべて個別にカウントされます。この割り当ては、レイテンシに敏感な更新を実行するバッチ API のユーザーにのみ実質的な影響があります。他のケースでは、割り当て 2 がこの割り当てより前に、または同時に使い果たされます。

さまざまなリクエストの割り当て使用量を理解するための例をいくつか示します。

1 つのアイテムを取得する 1 つの get リクエストでは、割り当て 1 のトークンを 1 つ消費し、割り当て 2 と 3 のトークンは消費しません（これらは変更エンドポイントにのみ関係するため）。
最大 100 個のアイテムを取得するバッチ get リクエストでも、割り当て 1 のトークンを 1 つ消費し、割り当て 2 と 3 のトークンは消費しません。
1 つのアイテムに対する 1 つの modification リクエストでは、割り当て 1 のトークンと割り当て 2 のトークンが 1 つずつ消費されます。リクエストがレイテンシの影響を受けやすい場合、割り当て 3 のトークンも 1 つ消費されます。割り当て C には割り当て 2 と同じ上限があるため、単一の変更方法のみを使用するユーザーには実質的な影響はありません。
レイテンシに強い 100 個のアイテムに対するバッチ modification リクエストでは、割り当て 1 の 1 トークンと、割り当て 2 の 1 トークンが消費されます。この割り当て設定では、カタログを最新の状態に保つために十分な余裕が確保されますが、アルゴリズムがこの割り当てを意識せず、このレートを超えると、追加の呼び出しごとにエラーが発生する可能性があります。
レイテンシに敏感な 100 個のアイテムに対するバッチ modification リクエストでは、割り当て 1 の 1 トークン、割り当て 2 の 1 トークン、割り当て 3 の 100 トークンが消費されます。

Catalog Management API の使用に関する推奨事項

これらのガイドラインに準拠することで、API とのやり取りを最適化し、カタログ管理をスムーズかつ効率的に行うことができます。

使用量をモニタリングする

使用量の多いプロセスに注意する必要があります。たとえば、統合の開始時に、カタログ管理エンドポイントは完全な初期カタログを作成するためにより多くの割り当てを使用する傾向があります。これは、全体的な使用上限に近づいている場合、購入ステータス API などの他のエンドポイントの製品環境での使用に影響する可能性があります。API の割り当てを超えないように、割り当て使用量をモニタリングする必要があります。使用状況をモニタリングする方法はいくつかあります。たとえば、Google Cloud APIs の割り当てダッシュボード、または任意の社内またはサードパーティの API モニタリングツールを使用できます。

API の割り当て使用量を最適化する

API エラーの発生を最小限に抑えるため、レートの使用量を最適化することを強くおすすめします。これを効果的に実装するには、次のことをおすすめします。

適切なカタログ管理戦略を選択します。API 割り当てを理解したら、カタログ管理の目標を効率的に達成するために、アプリケーションに適した戦略を選択する必要があります。
変更を反映するために必要な最小限の呼び出しのみを行います。
冗長な変更呼び出しや不要な変更呼び出しを API に送信しないでください。この場合、バックエンドカタログに変更ログを保持する必要があります。
商品の変更で 1 時間あたり 7,200 件のクエリの上限を超えないようにします。短期間に大量の商品を変更する必要がある同期プロセスを構築する場合（初期カタログの作成など）は、これらのプロセスが 1 時間あたりの上限を超えることが予想される場合は、必要に応じて待機を実装して、使用量を安全なレベルに減らしてください。レイテンシに強い更新でバッチメソッドを使用して、スループットを向上させることを検討してください。
スケーリングに向けて事前に準備します。アプリケーションの規模が大きくなるにつれて、API とさまざまなエンドポイントの使用量をスケールアップする必要がある場合があります。最大使用量に近づいたときに割り当てを増やす方法について詳しくは、Google Play Developer API の割り当てに関するドキュメントをご覧ください。
負荷の高いプロセスを戦略的にスケジュールします。負荷の高いカタログプロセスは、使用量のピーク時を避けてスケジュールするようにしてください。たとえば、週の販売ピーク時にカタログの完全同期を実行しないようにします。

割り当てエラー処理ロジックを追加する

カタログ管理ロジックをどれほど効率的に構築しても、1 日の割り当ては統合の独立したモジュールで使用されるエンドポイントで共有されるため、予期しない割り当て上限に耐えられるようにする必要があります。エラー処理に割り当てスロットリングエラーを含め、適切な待機を実装してください。Google Play Developer API に対して行われたすべての呼び出しでレスポンスが生成されます。呼び出しが失敗した場合は、HTTP レスポンスステータスコードと errors オブジェクトを含む失敗レスポンスが返されます。このオブジェクトには、エラードメインとデバッグメッセージに関する詳細情報が含まれます。たとえば、1 日あたりの上限を超えると、次のようなエラーが発生することがあります。

{
  "code" : 403,
  "errors" : [ {
    "domain" : "usageLimits",
    "message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
  Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
  "reason" : "dailyLimitExceeded",
  "extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
  } ],
}

カタログ管理の実装

デベロッパーは、Google Play Developer API の商品公開エンドポイントを使用して、バックエンドと Google Play 間でカタログを同期します。Google Play カタログがバックエンドのカタログの最新情報と常に同期されていることを確認することで、ユーザーエクスペリエンスを向上させることができます。例:

利用可能な特典のリスト全体を参照し、特典と基本プランのタグを管理して、独自の利用資格と特典の表示ロジックに影響を与えることができます。
ユーザーに表示されるさまざまな価格帯と商品の詳細を確認し、整合性を確認できます。
新しい購入を処理する際に、バックエンドで商品の詳細をすぐに確認できるため、ユーザーにとって重要なフロー中に Google Play Developer API を追加で呼び出してレイテンシを増やしたり、失敗のリスクを高めたりする必要がなくなります。

Google Play で商品カタログを作成する際には、特定の制限と考慮事項に留意する必要があります。これらの上限を理解し、カタログの構造を決めたら、同期戦略を決定します。

カタログ同期戦略

Google Play Developer API の公開エンドポイントを使用すると、変更が発生したときにカタログを更新できます。場合によっては、同じプロセスで多数の変更を送信する定期的な更新アプローチが必要になることがあります。アプローチごとに必要な設計選択は異なります。各同期戦略は、ユースケースによっては他の戦略よりも適している場合があります。また、状況に応じて、両方の戦略が必要になることもあります。緊急の商品更新（誤った価格をできるだけ早く修正する必要があるなど）を処理する場合など、新しい変更に気付いた時点で商品を更新したい場合があります。定期的なバックグラウンド同期を使用して、バックエンドと Play カタログの整合性を常に維持することもできます。これらのさまざまなカタログ管理戦略を実装する一般的なユースケースについて説明します。

ローカルカタログの変更時に更新を送信するタイミング

理想的には、不一致を最小限に抑えるために、バックエンドの商品カタログに変更があったらすぐに更新する必要があります。

このタイプの更新は、次のような場合に適しています。

商品は常に最新の状態に保つ必要があります。
商品に毎日いくつかの変更を加える必要があります。
すでに生産され、販売されている商品を更新する必要があります。

このアプローチは実装が簡単で、金額の差異ウィンドウを最小限に抑えながらカタログを同期できます。

定期的な更新を使用する場合

定期的な更新は、バックエンドの製品エディションと非同期で実行されます。次の場合に適しています。

商品が直ちに更新されるようにする必要はありません。
一括更新または調整プロセスを計画する必要があります。
デジタルプロダクトを処理し、カタログを常に更新するコンテンツ管理システムまたはカタログ管理システムがすでにある

カタログが大きい場合は、レイテンシに強い更新でバッチメソッドを使用して、スループットを最大化することを検討してください。

注: 変更後すぐに Google Play 商品カタログに更新を送信できますが、変更がアプリ内ですぐにユーザーに利用可能になるわけではありません。ネットワークやバックエンドの処理の遅延により、プロセスに遅延が生じる可能性があります。同様に、定期的な更新は遅延が発生しますが、必要に応じてカタログを頻繁に更新するように設計することもできます。これにより、オンデマンドアップデートと同様のレイテンシでユーザーに変更を公開できます。また、バッチメソッドの latencyTolerance フィールドでは、更新の迅速な伝播と高いスループットのどちらを最適化するかを選択できます。最終的には、これらの 2 つのオプションの選択は、お客様の特定の要件と制限に基づいて行う必要があります。

商品カタログを作成する

Google Play にアップロードするカタログが大量にある場合は、最初の読み込みを自動化することをおすすめします。このタイプの負荷の高いプロセスは、定期的な戦略とレイテンシに強いバッチ方法を組み合わせて使用する場合が最適です。

1 回限りのアイテムを作成する

商品の大規模なカタログを初めて 1 回作成する場合は、allowMissing フィールドを true に、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定して inappproducts.batchUpdate メソッドを使用することをおすすめします。これにより、割り当て上限内でカタログの作成にかかる時間を最小限に抑えることができます。

カタログが小さい場合は、inapp_products.insert メソッドを使用できます。または、サービスに関する最新情報のセクションで説明されているように、allowMissing パラメータを使用して inappproducts.update メソッドを使用することもできます。このアプローチの利点は、スクリプトをステートフルにする必要がなくなり、何か問題が発生した場合に最初から再起動できることです。

定期購入アイテムを作成する

サブスクリプションの最初の大規模なカタログ作成では、allowMissing フィールドを true に、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定して monetization.subscriptions.batchUpdate メソッドを使用することをおすすめします。これにより、割り当て上限内でカタログの作成にかかる時間を最小限に抑えることができます。

小規模な定期購入カタログの場合、Play Developer API は monetization.subscriptions.create メソッドを提供します。また、サービスアップデートのセクションで説明されているように、allowMissing パラメータを使用して monetization.subscriptions.patch メソッドを使用してサブスクリプションを作成することもできます。

上記のメソッドはすべて、基本プラン（Subscription オブジェクト内で指定）とともに定期購入を作成します。これらの基本プランは、最初は無効になっています。基本プランのステータスを管理するには、monetization.subscriptions.basePlans エンドポイントを使用します。たとえば、基本プランを有効にして購入できるようにします。また、monetization.subscriptions.basePlans.offers エンドポイントを使用すると、オファーを作成して管理できます。

サービスの更新情報

次の方法では、既存の商品を効率的に変更して、最新の調整に合わせて商品を調整できます。

1 回限りの商品を更新する

既存の 1 回限りの商品を更新するには、次の 3 つの方法があります。

inappproducts.patch : パッチエンドポイントは、リソースの部分的な更新に使用されます。つまり、リクエスト本文で指定した特定のフィールドを更新できます。パッチエンドポイントは、リソースの一部フィールドのみを更新する必要がある場合に使用します。
inappproducts.update: 更新エンドポイントは、リソース全体を更新するために使用されます。つまり、リクエスト本文でリソースオブジェクト全体を送信する必要があります。更新エンドポイントは通常、リソース内のすべてのフィールドを更新する必要がある場合に使用されます。allowMissing パラメータが true に設定され、指定された商品 ID がまだ存在しない場合、エンドポイントはエラーを返す代わりに商品を挿入します。
inappproducts.batchUpdate : これは更新エンドポイントのバッチバージョンで、1 つのクエリで複数の商品を変更できます。スループットを高めるには、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定して使用します。

定期購入商品を更新する

既存のサブスクリプションを更新するには、monetization.subscriptions.patch メソッドを使用します。このメソッドは、次の必須パラメータを受け取ります。

packageName: サブスクリプションが属するアプリのパッケージ名。
productId: サブスクリプションの一意のプロダクト ID。
regionsVersion: リージョン構成のバージョン。

allowMissing パラメータを使用して新しい定期購入を作成する場合は、updateMask パラメータを指定する必要があります。このパラメータは、更新するフィールドのカンマ区切りのリストです。

たとえば、定期購入商品のリスティングのみを更新する場合は、listings フィールドを updateMask パラメータに指定します。

monetization.subscriptions.batchUpdate を使用すると、複数の定期購入を同時に更新できます。スループットを向上させるには、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定して使用します。

基本プランを有効化、無効化、削除する、または定期購入者を最新の基本プランの料金バージョンに移行するには、monetization.subscriptions.basePlans エンドポイントを使用します。

また、monetization.subscriptions.basePlans.offers.patch メソッドを使用して基本プランの特典を更新することもできます。

カタログの調整

バックエンドのカタログが変更されるたびに Google Play カタログを更新するか、定期的に更新するかにかかわらず、Google Play のカタログの外部にカタログ管理システムまたはデータベースがある場合、Google Play のアプリ設定のカタログと同期が取れなくなる可能性があります。これは、Console でカタログを手動で緊急に変更した場合、カタログ管理システムが停止した場合、最新のデータが失われた場合に発生する可能性があります。

カタログの調整プロセスを構築すると、不一致期間の長期化を回避できます。

差分システムの考慮事項

不整合を検出して 2 つのシステムを調整する差分システムを構築することをおすすめします。カタログの同期を維持するために差分システムを作成する際は、次の点を考慮してください。

データモデルを理解する: 最初のステップは、デベロッパー CMS と Google Play Developer API のデータモデルを理解することです。これには、各システムに保存されているさまざまなデータの種類と、さまざまなデータ要素が相互にマッピングされる方法を把握することが含まれます。
差分ルールを定義する: データモデルを理解したら、差分ルールを定義する必要があります。これらのルールによって、2 つのシステムのデータの比較方法が決まります。たとえば、商品 ID を照合して、定期購入とその関連するベースプランとオファーの主要な属性を比較できます。
差分アルゴリズムを実装する: 差分ルールを定義したら、差分アルゴリズムを実装する必要があります。このアルゴリズムは、2 つのシステムからデータを取得し、定義したルールに従って比較します。Google Play からカタログデータを取得するには、inappproducts.list、inappproducts.batchGet、monetization.subscriptions.list、monetization.subscriptions.batchGet メソッドを使用します。
差分レポートを生成する: 差分アルゴリズムによって差分レポートが生成されます。このレポートには、両方のシステムの違いが表示されます。
差異を調整する: 差分レポートを生成したら、差異を解決する必要があります。通常のカタログ更新方法に応じて、CMS でデータを更新する場合もあれば、Developer API カタログ管理エンドポイントを使用して Google Play 側でデータを更新する場合もあります。同期されていない商品を調整するには、[商品の更新] セクションで説明されているように更新エンドポイントを使用します。

プロダクトのサポート終了

Google Play Developer API には、デベロッパーが商品のサポートを終了する際に役立つメソッドがいくつか用意されています。1 回限りの商品の場合は inappproducts.delete と inappproducts.batchDelete、定期購入の場合は monetization.subscriptions.delete です。プロダクトの非推奨化は、次のようなさまざまなシナリオで必要になる場合があります。

誤って作成された。
機能やサービスの廃止。

商品のサポート終了は、カタログ管理戦略に組み込むことをおすすめします。

1 回限りのアイテムのサポート終了

Google Play Developer API を使用して 1 回限りのプロダクトを削除するには、inappproducts.delete メソッドまたは inappproducts.batchDelete メソッドを使用する必要があります。

定期購入商品のサポート終了

サブスクリプションを削除するには、monetization.subscriptions.delete メソッドを使用します。1 つ以上の基本プランを有効にすると、定期購入を削除できなくなります。