本指南介绍了如何使用 Google Play Developer API 为您的 Play 应用创建和管理商品清单。
如需通过 Google Play 结算系统销售应用中的商品，您需要设置一个目录，列出您希望用户购买的所有商品。您可以通过 Play 管理中心完成此操作，也可以使用 Google Play Developer API 自动执行目录管理。自动化有助于确保您的目录始终保持最新，并可以扩展到手动协调不切实际的大型目录。在本指南中，您将了解如何使用 Play Developer API 为您的 Play 应用创建和管理商品清单。请参阅我们的准备工作指南，了解如何为后端集成设置 Google Play Developer API。
Catalog Management API
如需了解您可以通过 Google Play 结算系统销售的不同类型的商品，请参阅了解应用内商品类型和目录注意事项。Google 提供了两组主要的 API 以用于 Play 上的目录管理，分别对应于两个主要的商品类别：
- 一次性商品
- 订阅产品
一次性商品
通过 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 的默认上限为每天 20 万次查询。此配额限制适用于所有端点（包括清单管理 API）中的用量汇总。
- 产品修改端点还强制实施每小时 7200 次查询的限制。一次性商品和订阅以及所有修改请求（包括创建、更新、激活、删除）都需遵循这一限制。无论包含的单个请求数量或其延迟敏感度，批量修改方法调用均计为此配额的一个查询。
- 对延迟时间敏感的修改还限制为每小时 7200 次修改。对于批处理方法，每个嵌套修改请求会单独计数，以计算此配额。此配额仅对执行延迟敏感型更新的批处理 API 用户产生实际影响，因为在其他情况下，配额 2 将在此配额之前或同时用尽。
下面几个说明示例可帮助您了解不同请求的配额用量：
- 用于提取一件商品的单个
get请求将消耗 1 个配额为 1 的令牌，不会消耗配额 2 和 3 的令牌（因为它们仅涉及修改端点）。 - 一次提取最多 100 个项的批量
get请求也将消耗 1 个配额 1 令牌，不消耗配额 2 和 3 的 1 个令牌。 - 一个商品的单个
modification请求将消耗 1 个配额为 1 的令牌，1 个配额为 2 的令牌。如果请求对延迟较为敏感，它将消耗 1 个配额为 3 的令牌。由于配额 C 与配额 2 的限制相同，因此对只使用一种修改方法的用户来说没有实际影响。 - 一个针对 100 个容错项的批量
modification请求将消耗 1 个配额为 1 的令牌，1 个配额为 2 的令牌。此配额设置应留出充足的余量来保持目录更新，但如果您的算法不知道此配额并且超过了此配额，则每次额外调用时您可能会收到错误消息。 - 一个针对 100 个延迟时间敏感项的批量
modification请求将消耗 1 个配额 1 令牌、1 个配额 2 令牌，以及 100 个配额 3 令牌。
Catalog Management API 使用建议
通过遵循这些准则，您可以优化与 API 的互动，从而确保流畅高效的目录管理体验。
监控您的用量
请注意大量使用流程。例如，在集成开始时，目录管理端点更有可能使用更多配额来创建完整初始目录，如果您接近总体用量限额，这可能会影响其他端点（例如 Purchase Status 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 方法。或者，您也可以使用带有 allowMissing 参数的 monetization.subscriptions.update 方法创建订阅，如“产品更新”部分中所述。
前面的所有方法都可以创建订阅及其基础方案（在 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 上应用配置中的目录不同步的情况。这可能是由于在管理中心手动进行紧急目录更改、目录管理系统中断或您丢失了最新数据造成的。
您可以构建目录协调流程，以避免差异窗口过长。
差异比较系统考虑因素
我们建议构建一个 diff 系统来检测不一致之处并使两个系统相协调。 构建差异系统有助于保持目录保持同步时，请考虑以下事项：
- 了解数据模型：第一步是了解开发者 CMS 和 Google Play Developer API 的数据模型。这包括了解每个系统中存储的不同类型的数据，以及不同的数据元素如何相互映射。
- 定义差异规则：了解数据模型后，您需要定义差异规则。这些规则将决定如何比较两个系统中的数据。例如，您可能想要匹配产品 ID，并比较订阅的关键属性及其关联的基础方案和优惠。
- 实现 diff 算法：在定义 diff 规则后，您需要实现 diff 算法。此算法将从两个系统获取数据，并根据您定义的规则对其进行比较。如需从 Google Play 获取目录数据，您可以使用
inappproducts.list、inappproducts.batchGet、monetization.subscriptions.list和monetization.subscriptions.batchGet方法。 - 生成差异报告：差异算法将生成差异报告。 此报告会显示这两个系统之间的区别。
- 协调差异：生成差异报告后，您需要解决差异。这可能涉及更新 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 方法删除订阅。至少必须激活一个基础方案后，才能移除订阅。