本指南介绍了如何使用 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 的默认上限为每天 20 万次查询。此配额限制适用于所有端点（包括目录管理 API）中的使用情况汇总。
- 商品修改端点还会强制执行每小时 7,200 次查询的限制。这是一个单一限制，适用于一次性商品和订阅，以及所有修改请求（包括创建、更新、激活和删除）。对于此配额，批量修改方法调用会计为一次查询，无论其中包含的单个请求数量或延迟时间敏感性如何。
- 对延迟时间敏感的修改也限制为每小时 7,200 次。对于批量方法，每个嵌套修改请求都会单独计入此配额。此配额仅对执行对延迟敏感的更新的批量 API 用户有实际意义，因为在其他情况下，配额 2 会在此配额用尽之前或同时用尽。
以下几个示例说明了如何了解不同请求的配额用量：
- 用于提取一个项的单个
get请求将消耗配额 1 的 1 个令牌，但不会消耗配额 2 和 3 的令牌（因为它们仅与修改端点相关）。 - 一个最多提取 100 个项的批量
get请求也会消耗配额 1 的 1 个令牌，但不会消耗配额 2 和 3 的令牌。 - 针对一件商品的单个
modification请求将消耗配额 1 的 1 个令牌和配额 2 的 1 个令牌。如果请求对延迟时间较为敏感，则还会消耗配额 3 的 1 个令牌。由于配额 C 与配额 2 的限制相同，因此对于仅使用单个修改方法的用户而言，它没有实际意义。 - 针对 100 个支持延迟的项发出的批量
modification请求将消耗配额 1 的 1 个令牌，以及配额 2 的 1 个令牌。此配额设置应该足以让您的目录保持更新，但如果您的算法没有意识到此配额，并且超出了此速率，那么每进行一次额外调用，您都可能会收到一条错误消息。 - 针对 100 个对延迟时间敏感的项发出一个批量
modification请求将消耗配额 1 的 1 个令牌、配额 2 的 1 个令牌和配额 3 的 100 个令牌。
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 方法。或者，您也可以使用 monetization.subscriptions.patch 方法和 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 上应用配置中的目录不同步。这可能是因为您在 Play 管理中心内紧急手动更改了目录、目录管理系统发生了中断，或者您丢失了最新数据。
您可以构建目录对账流程，以避免差异窗口期延长。
差异系统注意事项
我们建议您构建一个差异系统来检测不一致之处并协调这两个系统。在构建差异系统以帮助保持目录同步时，请考虑以下事项：
- 了解数据模型：第一步是了解开发者 CMS 和 Google Play Developer API 的数据模型。这包括了解每个系统中存储的不同类型的数据，以及不同数据元素之间的映射方式。
- 定义差异规则：了解数据模型后，您需要定义差异规则。这些规则将决定如何比较两个系统中的数据。例如，您可能需要匹配商品 ID，并比较订阅及其关联的基础方案和优惠的关键属性。
- 实现差异算法：定义差异规则后，您需要实现差异算法。此算法会获取这两个系统中的数据，并根据您定义的规则进行比较。如需从 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 方法删除订阅。至少激活一个基础方案后，便无法移除订阅。