管理您的产品目录

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

要通过 Google Play 的计费系统在您的应用中销售产品，您需要设置一个包含您希望提供给用户购买的所有产品的目录。这可以通过 Play Console 完成，或者您可以使用 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 的 0 个令牌（因为它们仅涉及修改端点）。
  • 获取最多 100 个项目的批量get请求也将消耗配额 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 开发者 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 参数来创建订阅。

所有上述方法都会创建订阅及其基础套餐（在订阅对象中提供）。这些基础套餐最初处于非活动状态。要管理基础套餐的状态，您可以使用 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 方法删除订阅。一旦至少激活了一个基础套餐，就不能删除订阅。