本指南介绍了如何使用 Google Play Developer API 为您的 Play 应用创建和管理产品目录。
要通过 Google Play 的结算系统在应用中销售产品,您需要设置一个目录,其中包含所有要供用户购买的产品。这可以通过 Play 管理中心完成,或者您可以使用 Google Play Developer API 自动管理目录。自动化有助于确保您的目录始终保持最新,并且可以扩展到手动协调不切实际的大型目录。在本指南中,您将了解如何使用 Play Developer API 为您的 Play 应用创建和管理产品目录。请参阅我们的准备工作指南,了解如何为后端集成设置 Google Play Developer API。
目录管理 API
要了解您可以通过 Google Play 结算系统销售的不同产品类型,请阅读了解应用内产品类型和目录注意事项。Google 提供了两组主要的 Play 目录管理 API,对应于两个主要产品类别:
- 一次性产品
- 订阅产品
一次性产品
通过 inappproducts
端点,您可以从后端管理一次性产品。这包括创建、更新和删除产品,以及管理价格和可用性。根据您处理一次性产品购买的方式,您可以将产品建模为消耗型产品(可以按需购买多次)或永久权利(同一用户不能购买两次)。您可以决定哪些一次性产品应可消耗,哪些不可消耗。
订阅产品
monetization.subscriptions
端点可帮助您从开发者后端管理订阅产品。您可以创建、更新和删除订阅,或者控制其区域可用性和定价。除了 monetization.subscriptions
端点之外,我们还提供 monetization.subscriptions.basePlans
和 monetization.subscriptions.basePlans.offers
,分别用于管理订阅的基本计划和优惠。
批量方法
inappproducts
和 monetization.subscriptions
端点提供了多种批量方法,允许同时检索或管理同一应用下的最多 100 个实体。
批量方法在启用延迟容忍时支持更高的吞吐量,对于大型目录的开发者来说,在初始目录创建或目录协调方面特别有用。
更新传播延迟与吞吐量
产品创建或修改请求完成后,由于网络或后端处理延迟,更改可能不会立即在用户设备上可见。默认情况下,所有产品修改请求都是延迟敏感的。这意味着它们经过优化,可在后端系统中快速传播,通常在几分钟内反映到用户设备上。但是,此类修改请求的数量存在每小时限制。对于需要创建或更新大量产品的情况(例如,在初始创建大型目录期间),您可以使用批量方法并将 latencyTolerance
字段设置为 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
。这将显著提高更新吞吐量。延迟容忍的更新最多需要 24 小时才能传播到用户设备。
配额配置
使用 Play Developer API 管理产品目录时,应注意以下几个配额限制:
- Google Play Developer API 的默认每日查询限制为 200,000 次。此配额限制适用于所有端点的使用总量,包括目录管理 API。
- 产品修改端点还强制执行每小时 7,200 次查询的限制。这是一次性产品和订阅以及所有修改请求(包括创建、更新、激活、删除)的单一限制。批量修改方法调用在此配额中算作一次查询,无论其中包含的单个请求数量或其延迟敏感度如何。
- 延迟敏感的修改也有每小时 7,200 次修改的限制。对于批量方法,每个嵌套的修改请求在此配额中分别计算。此配额仅对执行延迟敏感更新的批量 API 用户具有实际意义,因为在其他情况下,配额 2 将在此配额之前或同时耗尽。
以下是一些示例,用于理解不同请求的配额使用情况:
- 单个
get
请求获取一个项目将消耗配额 1 的 1 个令牌,配额 2 和 3 的令牌为 0(因为它们仅涉及修改端点)。 - 批量
get
请求获取最多 100 个项目也将消耗配额 1 的 1 个令牌,配额 2 和 3 的令牌为 0。 - 单个项目的
modification
请求将消耗配额 1 的 1 个令牌,配额 2 的 1 个令牌。如果请求是延迟敏感的,它还将消耗配额 3 的 1 个令牌。由于配额 C 的限制与配额 2 相同,因此对于仅使用单个修改方法的用户来说,它没有实际意义。 - 针对 100 个延迟容忍项目的批量
modification
请求将消耗配额 1 的 1 个令牌,配额 2 的 1 个令牌。此配额设置应提供充足的余量来保持您的目录更新,但如果您的算法没有意识到此配额并超出此速率,则每次额外调用都可能收到错误。 - 针对 100 个延迟敏感项目的批量
modification
请求将消耗配额 1 的 1 个令牌,配额 2 的 1 个令牌,以及配额 3 的 100 个令牌。
目录管理 API 使用建议
遵守这些指南,您可以优化与 API 的交互,确保流畅高效的目录管理体验。
监控您的使用情况
您应该注意高使用率的流程。例如,在集成开始时,您的目录管理端点更可能消耗更多配额来创建完整的初始目录,如果您接近总使用量限制,这可能会影响其他端点(例如购买状态 API)的生产使用。您需要监控配额消耗情况,以确保您没有超出 API 配额。有几种方法可以监控使用情况。例如,您可以使用 Google Cloud API 配额控制台,或您选择的任何其他内部或第三方 API 监控工具。
优化 API 配额使用
强烈建议优化速率消耗,以最大限度地减少 API 出错的可能性。为了有效地实现这一点,我们建议您:
- 选择合适的目录管理策略。一旦您了解了 API 配额,就需要为您的应用选择合适的策略,以高效地实现您的目录管理目标。
- 只进行反映您更改所需的最低调用次数。
- 不要向 API 发送冗余或不必要的修改调用。这可能需要您在后端目录中保留一个更改日志。
- 控制在每小时 7,200 次查询的产品修改限制内。您可能希望构建同步流程,需要在短时间内进行大量产品修改(例如,初始目录创建)。如果您预计这些流程会超出每小时限制,请根据需要实施等待,以将使用速度降低到安全水平。考虑使用批量方法和延迟容忍更新来获得更高的吞吐量。
- 主动准备扩展。随着您的应用增长,您可能需要扩大 API 和各种端点的使用。请阅读Google Play Developer API 配额文档,了解当您接近最大使用量时如何增加配额的详细信息。
- 战略性地安排繁重流程。尽量避开关键使用高峰期安排繁重的目录处理流程,例如您可以避免在每周销售高峰时段运行完整的目录同步。
添加配额错误处理逻辑
无论您构建的目录管理逻辑多么高效,考虑到每日配额由集成中独立模块使用的端点共享,您都应该使其对意外配额限制具有弹性。确保在错误处理中包含配额限制错误,并实现适当的等待。每次对 Google Play Developer API 的调用都会生成响应。如果调用失败,您将收到包含 HTTP 响应状态代码和 errors
对象的失败响应,提供有关错误域和调试消息的进一步详细信息。例如,如果您超出每日限制,您可能会遇到类似于以下内容的错误:
{
"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,您可能希望自动化初始加载过程。如果遵循定期策略并结合延迟容忍的批量方法,这种繁重的过程效果最好。
创建一次性产品
对于一次性产品的大型初始目录创建,我们建议使用 inappproducts.batchUpdate
方法,将 allowMissing
字段设置为 true
,并将 latencyTolerance
字段设置为 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
。这将最大限度地缩短在配额限制内创建目录所需的时间。
对于较小的目录,您可以使用 inapp_products.insert
方法。或者,您可以使用 inappproducts.update
方法并带上 allowMissing
参数,如“产品更新”部分所述。这种方法的优点在于,您的脚本无需是有状态的,并且如果出现任何问题,可以从头开始重新启动。
创建订阅产品
对于大型初始订阅目录创建,我们建议使用 monetization.subscriptions.batchUpdate
方法,将 allowMissing
字段设置为 true
,并将 latencyTolerance
字段设置为 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT
。这将最大限度地缩短在配额限制内创建目录所需的时间。
对于较小的订阅目录,Play Developer API 提供了 monetization.subscriptions.create
方法。或者,您可以使用 monetization.subscriptions.patch
方法并带上 allowMissing
参数来创建订阅,如“产品更新”部分所述。
所有先前的方法都会创建订阅及其基本计划(在 Subscription 对象内提供)。这些基本计划最初是非活动的。要管理基本计划的状态,您可以使用 monetization.subscriptions.basePlans
端点,包括激活基本计划使其可供购买。此外,monetization.subscriptions.basePlans.offers
端点允许您创建和管理优惠。
产品更新
以下方法可让您高效地修改现有产品,确保您的产品与最新调整保持一致。
更新一次性产品
您可以使用三种方法来帮助更新现有的一次性产品。
inappproducts.patch
:patch 端点用于部分更新资源。这意味着您可以更新请求正文中指定的特定字段。patch 端点通常用于仅需要更新资源少量字段的情况。inappproducts.update
:update 端点用于完整更新资源。这意味着您需要在请求正文中发送完整的资源对象。update 端点通常用于需要更新资源中所有字段的情况。当allowMissing
参数设置为true
且提供的产品 ID 不存在时,端点将插入产品而不是失败。inappproducts.batchUpdate
:这是 update 端点的批量版本,允许您通过一次查询修改多个产品。将其与设置为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 目录之外拥有目录管理系统或数据库,则可能会出现与 Play 上的应用配置目录不同步的情况。这可能是由于在 Console 中进行了紧急手动目录更改、您的目录管理系统发生中断,或者您丢失了最新数据。
您可以构建一个目录协调流程,以避免长时间出现差异。
Diff 系统注意事项
我们建议构建一个 Diff 系统来检测不一致性并协调这两个系统。构建 Diff 系统以帮助保持目录同步时,请考虑以下几点:
- 理解数据模型:第一步是理解开发者 CMS 和 Google Play Developer API 的数据模型。这包括了解每个系统中存储的不同类型数据,以及不同数据元素如何相互映射。
- 定义 Diff 规则:理解数据模型后,您需要定义 Diff 规则。这些规则将决定如何比较两个系统中的数据。例如,您可能希望匹配产品 ID 并比较订阅及其关联基本计划和优惠的关键属性。
- 实现 Diff 算法:定义 Diff 规则后,您需要实现 Diff 算法。该算法将获取两个系统中的数据并根据您定义的规则进行比较。要从 Google Play 获取目录数据,您可以使用
inappproducts.list
、inappproducts.batchGet
、monetization.subscriptions.list
和monetization.subscriptions.batchGet
方法。 - 生成 Diff 报告:Diff 算法将生成一份 Diff 报告。该报告将显示两个系统之间的差异。
- 协调差异:生成 Diff 报告后,您需要解决差异。这可能涉及更新 CMS 中的数据,或者根据您通常更新目录的方式,使用 Developer API 目录管理端点更新 Google Play 方面的数据。要协调不同步的产品,请使用“产品更新”部分中描述的更新端点。
产品弃用
Google Play Developer API 提供几种方法来帮助开发者弃用其产品:用于一次性产品的 inappproducts.delete
和 inappproducts.batchDelete
,以及用于订阅的 monetization.subscriptions.delete
。在各种情况下可能需要弃用产品,例如:
- 误创建。
- 停止某个功能或服务。
我们建议将产品弃用纳入您的目录管理策略中。
弃用一次性产品
要使用 Google Play Developer API 删除一次性产品,您需要使用 inappproducts.delete
或 inappproducts.batchDelete
方法。
弃用订阅产品
您可以使用 monetization.subscriptions.delete
方法删除订阅。一旦至少有一个基本计划被激活,就无法移除订阅。