提醒：截至 2025 年 8 月 31 日，所有新应用和现有应用的更新都必须使用 Billing Library 7 或更高版本。如果您需要更多时间来更新应用，可以申请延期至 2025 年 11 月 1 日。了解 Play Billing Library 版本弃用信息。

管理您的产品目录

本指南介绍了如何使用 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 方法删除订阅。一旦至少有一个基本计划被激活，就无法移除订阅。