Reminder: By Aug 31, 2024, all new apps and updates to existing apps must use Billing Library version 6 or newer. If you need more time to update your app, you will be able to request an extension until Nov 1, 2024. Learn more.

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

商品カタログを管理する

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

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

Catalog Management API

Google Play の課金システムで販売できるさまざまなタイプのアイテムについては、アプリ内アイテムタイプとカタログに関する考慮事項についてをご覧ください。Google は、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 と同じ上限があるため、1 つの変更方法のみを使用するユーザーには実質的な影響がありません。
レイテンシが許容されるアイテム 100 個に対する modification バッチリクエストは、割り当て 1 のトークンと割り当て 2 のトークンをそれぞれ 1 つずつ使用します。この割り当てを設定すると、カタログを最新の状態に保つために十分なマージンを確保できますが、アルゴリズムがこの割り当てを認識しておらず、この割り当てを超えると、追加の呼び出しごとにエラーが発生する可能性があります。
レイテンシの影響を受けやすいアイテム 100 個のバッチ modification リクエストは、割り当て 1 を 1 トークン、割り当て 2 を 1 トークン、割り当て 3 を 100 トークンを消費します。

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

これらのガイドラインに準拠することで、API の操作を最適化し、スムーズで効率的なカタログ管理を実現できます。

使用状況をモニタリングする

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

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

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

適切なカタログ管理戦略を選択する。API の割り当てを理解したら、カタログ管理の目標を効率的に達成するために、アプリケーションに適した戦略を選択する必要があります。
変更を反映するために必要な最小限の通話のみを行う。
冗長または不要な変更呼び出しを API に送信しないでください。これにより、バックエンドカタログに変更履歴を保持しなければならない場合があります。
商品修正の時間あたりの上限である 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.update メソッドを使用して定期購入を作成することもできます。

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

サービスの更新情報

次の方法を使用すると、既存のアイテムを効率的に変更し、最新の調整とサービスを一致させることができます。

1 回限りのアイテムを更新する

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

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

定期購入商品を更新する

既存の定期購入を更新するには、monetization.subscriptions.patch メソッドを使用します。このメソッドは、次の必須パラメータを受け取ります。

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

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

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

monetization.subscriptions.batchUpdate を使用すると、複数のサブスクリプションを同時に更新できます。スループットを向上させるには、PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定した latencyTolerance フィールドと併用します。

基本プランの有効化、無効化、削除、定期購入者を最新の基本プランの価格バージョンに移行するには、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 からカタログデータを取得するには、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 つ有効にすると、定期購入は削除できません。