このガイドでは、Google Play Developer API を使用して Google Play アプリの商品カタログを作成、管理する方法について説明します。
Google Play の課金システムを使用してアプリ内でアイテムを販売するには、ユーザーが購入できるようにするすべてのアイテムを含むカタログを設定する必要があります。この操作は Play Console で行うか、Google Play Developer API を使用してカタログ管理を自動化できます。自動化により、カタログを常に最新の状態に保ち、手動での調整が現実的ではない大規模なカタログにも対応できます。このガイドでは、Play Developer API を使用して、Google Play アプリのプロダクト カタログを作成、管理する方法について説明します。バックエンド統合用に Google Play Developer API を設定する手順については、準備ガイドをご覧ください。
カタログ管理 API
Google Play の課金システムで販売できるアイテムの種類については、アプリ内アイテムのタイプとカタログに関する考慮事項についてをご覧ください。Google は、Google Play でのカタログ管理用に 2 つの主要な API セットを提供しています。これは、2 つの主要なアイテム カテゴリに対応しています。
- 1 回限りのアイテム
- 定期購入商品
1 回限りのアイテム
1 回限りのアイテム（以前のアプリ内アイテム）では、1 回限りのアイテムのオブジェクト モデルが使用されます。これにより、1 回限りのアイテムに対して複数の購入オプションと特典を設定できます。1 回限りのアイテムのオブジェクト モデルにより、アイテムの販売方法がさらに柔軟になり、管理の煩雑さが軽減されます。既存のアプリ内アイテムは、1 回限りのアイテムのオブジェクト モデルに移行されます。詳しくは、アプリ内アイテムの移行をご覧ください。
monetization.onetimeproducts エンドポイントと inappproducts エンドポイントを使用すると、バックエンドから 1 回限りのアイテムを管理できます。これには、商品の作成、更新、削除、価格と在庫状況の管理が含まれます。1 回限りのアイテムの購入の処理方法に応じて、消費型アイテム（必要な回数だけ購入できる）または永続的な利用資格（同じユーザーが 2 回購入できない）をモデル化します。1 回限りのアイテムを消費可能にするかどうかは、デベロッパーが決定できます。
定期購入商品
monetization.subscriptions エンドポイントを使用すると、デベロッパーのバックエンドから定期購入アイテムを管理できます。サブスクリプションの作成、更新、削除や、地域別の在庫状況と価格の管理などを行うことができます。monetization.subscriptions エンドポイントに加えて、定期購入の基本プランと特典をそれぞれ管理する monetization.subscriptions.basePlans と monetization.subscriptions.basePlans.offers も提供しています。
バッチメソッド
onetimeproducts、inappproducts、monetization.subscriptions エンドポイントは、同じアプリで最大 100 個のエンティティを同時に取得または管理できるバッチメソッドを多数提供します。
バッチメソッドは、レイテンシ許容範囲が有効になっている場合に使用すると、スループットの向上をサポートします。特に、大規模なカタログのデベロッパーがカタログの初回作成やカタログの調整を行う場合に便利です。
更新の伝播レイテンシとスループット
アイテムの作成または変更リクエストが完了した後、ネットワークやバックエンドの処理の遅延により、エンドユーザーのデバイスで変更がすぐに反映されないことがあります。デフォルトでは、すべてのプロダクト変更リクエストはレイテンシの影響を受けやすいと見なされます。つまり、バックエンド システムを介して迅速に伝播するように最適化されており、通常は数分以内にエンドユーザーのデバイスに反映されます。ただし、このような変更リクエストの数には 1 時間あたりの上限があります。多数の商品を作成または更新する必要がある場合（大規模なカタログの初回作成時など）は、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定して、バッチメソッドを使用できます。これにより、更新のスループットが大幅に向上します。遅延許容型アップデートは、エンドユーザーのデバイスに反映されるまでに最大 24 時間かかります。
割り当ての構成
Google Play Developer API を使用して商品カタログを管理する際には、次の割り当て上限に注意する必要があります。
- Google Play Developer API は「バケット」と呼ばれるカテゴリに分類されており、それぞれのバケットには 1 分あたりの割り当て制限が設定されています。詳細については、割り当てをご覧ください。
- 商品変更エンドポイントにも、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 のトークン 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 の公開エンドポイントを使用すると、変更が発生したときにカタログを更新できます。場合によっては、同じプロセスで一連の変更を送信する定期的な更新アプローチが必要になることがあります。それぞれのアプローチには異なる設計上の選択肢が必要です。同期戦略は、ユースケースによって適しているものが異なります。状況によっては、両方の戦略が必要になることもあります。たとえば、緊急の商品更新（誤った価格をできるだけ早く修正する必要がある場合など）を処理するために、新しい変更を認識した瞬間に商品を更新したい場合があります。また、定期的なバックグラウンド同期を使用して、バックエンドと Google Play のカタログの整合性を常に保つこともできます。さまざまなカタログ管理戦略を実装する一般的なユースケースについて説明します。
ローカル カタログの変更時に更新情報を送信するタイミング
理想的には、バックエンドの商品カタログに変更があったらすぐに更新して、不一致を最小限に抑える必要があります。
このタイプの更新は、次のような場合に適しています。
- 商品は常に最新の状態に保つ必要があります。
- 毎日、商品にいくつかの変更を加える必要があります。
- すでに製品版として公開され、販売されているプロダクトを更新する必要がある。
このアプローチは実装が簡単で、カタログを最小限の不一致ウィンドウで同期できます。
定期的な更新を使用する場合
定期的な更新は、バックエンドのプロダクト エディションに対して非同期で実行されます。これは、次のような場合に適しています。
- 商品を短期間で更新する必要はありません。
- 一括更新または調整プロセスを計画する必要がある。
- デジタル商品を処理し、カタログを常に更新するコンテンツ管理システムまたはカタログ管理システムがすでに存在している
大規模なカタログの場合は、レイテンシ許容更新でバッチメソッドを使用して、最大スループットを実現することを検討してください。
商品カタログを作成する
Google Play にアップロードするカタログが大きい場合は、初回読み込みを自動化することをおすすめします。このタイプの重いプロセスは、レイテンシ許容バッチ メソッドと組み合わせた定期的な戦略に従う場合に最適です。
1 回限りのアイテムを作成する
初回の一度限りの商品カタログの作成には、monetization.onetimeproducts.batchUpdate または inapp_products.insert メソッドを使用し、allowMissing フィールドを true に、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定することをおすすめします。これにより、割り当て上限内でカタログを作成する時間を最小限に抑えることができます。
定期購入アイテムを作成する
初回サブスクリプションの大規模なカタログを作成する場合は、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 回限りのアイテムを更新するには、次のメソッドを使用できます。
- monetization.onetimeproducts.batchUpdate
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 のアプリ設定のカタログと同期しなくなる可能性があります。これは、コンソールでの緊急の手動カタログ変更、カタログ管理システムの停止、最新データの損失などが原因である可能性があります。
カタログ調整プロセスを構築して、不一致の期間が長くなるのを防ぐことができます。
差分システムに関する考慮事項
不整合を検出し、2 つのシステムを調整する差分システムを構築することをおすすめします。カタログの同期を維持するための差分システムを構築する際は、次の点を考慮してください。
- データモデルを理解する: 最初のステップは、デベロッパー CMS と Google Play Developer API のデータモデルを理解することです。これには、各システムに保存されているデータの種類と、異なるデータ要素がどのように相互にマッピングされるかを把握することが含まれます。
- 差分ルールを定義する: データモデルを理解したら、差分ルールを定義する必要があります。これらのルールによって、2 つのシステムのデータがどのように比較されるかが決まります。たとえば、商品 ID を照合して、定期購入とその関連する基本プランや特典のキー属性を比較できます。
- 差分アルゴリズムを実装する: 差分ルールを定義したら、差分アルゴリズムを実装する必要があります。このアルゴリズムは、2 つのシステムからデータを取得し、定義したルールに従って比較します。Google Play からカタログデータを取得するには、
monetization.onetimeproducts.list、monetization.onetimeproducts.batchGet、inappproducts.list、inappproducts.batchGet、monetization.subscriptions.list、monetization.subscriptions.batchGetの各メソッドを使用します。 - 差分レポートを生成する: 差分アルゴリズムが差分レポートを生成します。このレポートには、両方のシステムの違いが表示されます。
- 差異を調整する: 差分レポートを生成したら、差異を解決する必要があります。通常カタログを更新する方法に応じて、CMS のデータを更新したり、デベロッパー API カタログ管理エンドポイントを使用して Google Play 側でデータを更新したりする必要があります。同期されていない商品を調整するには、商品の更新セクションで説明されている更新エンドポイントを使用します。
プロダクトのサポート終了
Google Play Developer API には、プロダクトの非推奨化を支援する次のメソッドが用意されています。
1 回限りのアイテムの場合:
monetization.onetimeproducts.deletemonetization.onetimeproducts.batchDeleteinappproducts.deleteinappproducts.batchDelete
定期購入アイテムの場合:
- 定期購入の場合は
monetization.subscriptions.delete。基本プランが 1 つ以上有効になっている定期購入は削除できません。
プロダクトの非推奨化は、次のようなさまざまなシナリオで必要になることがあります。
- 誤って作成した。
- 機能またはサービスの提供終了。
カタログ管理戦略に商品のサポート終了を組み込むことをおすすめします。