管理您的产品目录

本指南介绍如何使用 Google Play 开发者 API 创建和管理 Play 应用的产品目录。

要通过 Google Play 计费系统在您的应用中销售产品，您需要设置一个包含您希望让用户购买的所有产品的目录。这可以通过 Play 管理中心完成，或者您可以使用 Google Play 开发者 API 自动化目录管理。自动化可以帮助确保您的目录始终保持最新状态，并且可以扩展到手动协调不切实际的大型目录。在本指南中，您将了解如何使用 Play 开发者 API 创建和管理 Play 应用的产品目录。请查看我们的 准备工作 指南，了解有关如何为您的后端集成设置 Google Play 开发者 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 开发者 API 管理您的产品目录时，您应该注意几个配额限制。

  1. Google Play 开发者 API 每天默认限制 200,000 个查询。此配额限制适用于所有端点的使用情况汇总，包括目录管理 API。
  2. 产品修改端点还强制执行每小时 7,200 个查询的限制。这是针对一次性产品和订阅以及所有修改请求（包括创建、更新、激活、删除）的单个限制。批量修改方法调用在此配额中计为一个查询，无论包含的单个请求数量或其延迟敏感性如何。
  3. 延迟敏感型修改每小时也限制为 7,200 次修改。对于批量方法，出于此配额的目的，每个嵌套修改请求都单独计数。此配额仅对执行延迟敏感更新的批量 API 用户具有实际意义，因为在其他情况下，配额 2 将在此配额之前或同时用尽。

以下是一些说明性示例，用于了解不同请求的配额使用情况。

  • 获取单个项目的单个get请求将消耗 1 个配额 1 代币，而不会消耗配额 2 和 3 的代币（因为它们仅涉及修改端点）。
  • 获取最多 100 个项目的批量get请求也将消耗 1 个配额 1 代币，而不会消耗配额 2 和 3 的代币。
  • 单个项目的单个modification请求将消耗 1 个配额 1 代币，1 个配额 2 代币。如果请求对延迟敏感，它还将消耗 1 个配额 3 代币。由于配额 C 与配额 2 的限制相同，因此对于仅使用单个修改方法的用户而言，它没有实际意义。
  • 100 个延迟容忍项目的批量modification请求将消耗 1 个配额 1 代币，1 个配额 2 代币。此配额设置应留有足够的余量来保持您的目录更新，但如果您的算法没有意识到此配额并超过此速率，则您可能会因每次额外调用而收到错误。
  • 100 个延迟敏感项目的批量modification请求将消耗 1 个配额 1 代币，1 个配额 2 代币和 100 个配额 3 代币。

目录管理 API 使用建议

通过遵守这些准则，您可以优化与 API 的交互，确保流畅高效的目录管理体验。

监控您的使用情况

您应该注意大量使用过程。例如，在集成开始时，您的目录管理端点更有可能消耗更多配额来创建完整的初始目录，这可能会影响其他端点（例如购买状态 API）的生产使用，如果您接近整体使用限制。您需要监控您的配额消耗，以确保您没有超过 API 配额。有多种方法可以监控使用情况。例如，您可以使用 Google Cloud APIs 配额控制面板，或您选择的任何其他内部或第三方 API 监控工具。

优化 API 配额使用

强烈建议优化速率消耗，以最大限度地减少 API 错误的可能性。为了有效地实现这一点，我们建议您

  • 选择正确的目录管理策略。了解 API 配额后，您需要为您的应用程序选择正确的策略，以有效地实现您的目录管理目标。
  • 仅发出反映更改所需的最小调用量。
  • 不要向 API 发送冗余或不必要的修改调用。这可能需要您在后端目录中保留更改日志。
  • 保持在每小时 7,200 个查询的产品修改限制内。您可能需要构建同步过程，这些过程需要您在短时间内进行大量产品修改（例如，初始目录创建）。如果您预计这些过程会超过每小时限制，则根据需要实施等待以将使用率降低到安全级别。考虑使用具有延迟容忍更新的批量方法来实现更高的吞吐量。
  • 主动准备扩展。随着应用程序的增长，您可能需要扩展对 API 和各种端点的使用。阅读Google Play 开发者 API 配额文档，了解在接近最大使用量时如何增加配额的详细信息。
  • 战略性地安排繁重的流程。尝试在关键使用高峰期安排您的繁重目录流程，例如，您可以避免在一周的销售高峰期运行完整的目录同步。

添加配额错误处理逻辑

无论您如何高效地构建目录管理逻辑，都应该使其能够应对意外的配额限制，因为每日配额由集成独立模块中使用的端点共享。确保在错误处理中包含配额限制错误，并实施适当的等待。对 Google Play 开发者 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 开发者 API 产品发布端点来保持其目录在其后端和 Google Play 之间的同步。确保您的 Google Play 目录始终与您后端的目录最新信息保持一致，这有利于创造更好的用户体验。例如

  • 您将能够查阅可用优惠的完整列表，并管理优惠和基本套餐标签以影响您自己的资格和优惠显示逻辑。
  • 您可以检查用户在不同平台上看到的不同价格点和产品详细信息，并确保它们一致。
  • 在处理新购买时，您可以在后端掌握产品详细信息，无需增加延迟和失败风险，而无需在用户关键流程中向 Google Play 开发者 API 发出额外调用。

在 Google Play 上创建产品目录时，您应该记住一些限制和注意事项。了解这些限制并了解您希望如何构建目录后，就可以确定您的同步策略了。

目录同步策略

Google Play 开发者 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 开发者 API 提供了 monetization.subscriptions.create 方法。或者，您可以使用 monetization.subscriptions.update 方法以及 allowMissing 参数创建订阅，如“产品更新”部分所述。

所有上述方法都会创建订阅及其基础套餐（包含在 Subscription 对象中）。这些基础套餐最初处于非活动状态。要管理基础套餐的状态，您可以使用 monetization.subscriptions.basePlans 端点，包括激活基础套餐以使其可供购买。此外，monetization.subscriptions.basePlans.offers 端点允许您创建和管理优惠。

产品更新

以下方法使您可以有效地修改现有产品，确保您的产品与您最新的调整保持一致。

更新一次性产品

您可以使用三种方法来更新现有的一次性产品。

  • inappproducts.patch：此修补程序端点用于部分更新资源。这意味着您可以更新请求正文中指定的特定字段。当您只需要更新资源的几个字段时，通常使用修补程序端点。
  • inappproducts.update：此更新端点用于完整更新资源。这意味着您需要在请求正文中发送整个资源对象。当您需要更新资源中的所有字段时，通常使用更新端点。当 allowMissing 参数设置为 true 且提供的产品 ID 尚不存在时，端点将插入产品而不是失败。
  • inappproducts.batchUpdate：这是更新端点的批量版本，它允许您使用单个查询修改多个产品。将其与设置为 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 上应用配置中的目录不同步的情况。这可能是由于控制台中紧急的手动目录更改、您的目录管理系统中断或您丢失了最新数据造成的。

您可以构建目录协调流程以避免长时间的差异窗口。

差异系统考虑因素

我们建议构建差异系统以检测不一致之处并协调这两个系统。构建差异系统以帮助保持目录同步时，需要考虑以下几点：

  • 了解数据模型：第一步是了解开发者 CMS 和 Google Play 开发者 API 的数据模型。这包括了解每个系统中存储的不同类型的数据，以及不同的数据元素如何相互映射。
  • 定义差异规则：了解数据模型后，您需要定义差异规则。这些规则将决定如何比较两个系统中的数据。例如，您可能希望匹配产品 ID 并比较订阅及其关联的基础套餐和优惠的关键属性。
  • 实现差异算法：定义差异规则后，您需要实现差异算法。此算法将采用来自两个系统的数据，并根据您定义的规则进行比较。要从 Google Play 获取目录数据，您可以使用 inappproducts.list、inappproducts.batchGet、monetization.subscriptions.list 和 monetization.subscriptions.batchGet 方法。
  • 生成差异报告：差异算法将生成差异报告。此报告将显示两个系统之间的差异。
  • 协调差异：生成差异报告后，您需要解决差异。这可能涉及更新 CMS 中的数据，也可能涉及使用开发者 API 目录管理端点更新 Google Play 端的数据，具体取决于您通常如何更新目录。要协调不同步的产品，请使用“产品更新”部分中描述的更新端点。

产品弃用

Google Play 开发者 API 提供了几种方法来帮助开发者弃用其产品：inappproducts.delete 和 inappproducts.batchDelete 用于一次性产品，以及 monetization.subscriptions.delete 用于订阅。在各种情况下可能需要弃用产品，例如：

  • 错误创建。
  • 停止某个功能或服务。

我们建议将产品弃用纳入您的目录管理策略。

弃用一次性产品

要使用 Google Play 开发者 API 删除一次性产品，您需要使用 inappproducts.delete 或 inappproducts.batchDelete 方法。

弃用订阅产品

您可以使用 monetization.subscriptions.delete 方法删除订阅。一旦至少激活了一个基础套餐，就不能删除订阅。