此页面由 Cloud Translation API 翻译。

管理商品清单

项目：/google/play/billing/_project.yaml 文档：/google/play/billing/_book.yaml

本指南介绍了如何使用 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，分别对应于两个主要商品类别：

一次性商品
订阅产品

一次性商品

一次性商品（以前称为“应用内商品”）使用一次性商品对象模型，可让您为一次性商品配置多种购买选项和优惠。一次性商品对象模型可让您更灵活地销售商品，并降低管理商品的复杂性。您现有的应用内商品将迁移到一次性商品对象模型。如需了解详情，请参阅迁移应用内商品。

借助 monetization.onetimeproducts 和 inappproducts 端点，您可以从后端管理一次性商品。这包括创建、更新和删除商品，以及管理价格和库存状况。根据您处理一次性商品购买交易的方式，您将对消耗型商品（可根据需要多次购买）或永久性授权（同一用户无法购买两次）进行建模。您可以决定哪些一次性商品应为消耗型商品，哪些不应为消耗型商品。

订阅产品

借助 monetization.subscriptions 端点，您可以从开发者后端管理订阅商品。您可以执行创建、更新和删除订阅等操作，也可以控制订阅的地区性库存状况和价格。除了 monetization.subscriptions 端点之外，我们还提供 monetization.subscriptions.basePlans 和 monetization.subscriptions.basePlans.offers，分别用于管理订阅的基础方案和优惠。

批处理方法

onetimeproducts、inappproducts 和 monetization.subscriptions 端点提供了一些批量方法，可用于同时检索或管理同一应用下的最多 100 个实体。

批量方法在与启用的延迟容忍度搭配使用时，可支持更高的吞吐量，对于大型目录开发者来说，在初始目录创建或目录协调方面特别有用。

更新传播延迟时间与吞吐量

在商品创建或修改请求完成后，由于网络或后端处理延迟，最终用户可能无法立即在设备上看到相应更改。默认情况下，所有商品修改请求都对延迟时间非常敏感。这意味着它们经过优化，可在后端系统中快速传播，通常会在几分钟内反映在最终用户设备上。不过，此类修改请求的数量存在每小时限制。如果您需要创建或更新大量商品（例如，在初始创建大型商品目录期间），可以使用将 latencyTolerance 字段设置为 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT 的批量方法。这将显著提高更新吞吐量。延迟容忍型更新最多需要 24 小时才能传播到最终用户设备。

配额配置

使用 Play Developer API 管理商品目录时，您应注意以下几项配额限制：

Google Play Developer API 会按“存储分区”分门别类，每个存储分区都有各自的每分钟配额限制。如需了解详情，请参阅配额。
产品修改端点还强制执行每小时 7,200 次查询的限制。此限制适用于一次性商品和订阅，也适用于所有修改请求，包括创建、更新、激活和删除。无论批量修改方法调用中包含的单个请求数量是多少，也无论这些请求对延迟时间的敏感程度如何，这些调用都计为一次查询。
延迟时间敏感型修改的限制为每小时 7,200 次。对于批量方法，每个嵌套的修改请求都会单独计入此配额。此配额仅对执行延迟敏感型更新的批量 API 用户具有实际意义，因为在其他情况下，配额 2 将在此配额之前或同时用尽。

以下是一些示例，可帮助您了解不同请求的配额用量：

获取一项内容的单个 get 请求将消耗 1 个配额 1 的令牌，但不消耗配额 2 和 3 的令牌（因为它们仅涉及修改端点）。
批量 get 请求（用于提取最多 100 项内容）也会消耗 1 个配额 1 令牌，而不会消耗配额 2 和 3 的令牌。
针对一项内容发出的单个 modification 请求将消耗 1 个配额 1 令牌和 1 个配额 2 令牌。如果请求对延迟时间较为敏感，则还会消耗 1 个配额 3 的令牌。由于配额 C 的限制与配额 2 相同，因此对于仅使用单一修改方法的用户而言，配额 C 没有实际意义。
针对 100 个延迟容忍型商品的批量 modification 请求将消耗 1 个配额 1 令牌和 1 个配额 2 令牌。此配额设置应可提供充足的余量来保持目录更新，但如果您的算法未意识到此配额并超出此速率，您可能会在每次额外调用时收到错误。
如果批量 modification 请求包含 100 个对延迟时间敏感的项目，则会消耗 1 个配额 1 令牌、1 个配额 2 令牌和 100 个配额 3 令牌。

Catalog Management 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，可能需要自动执行初始加载。如果采用周期性策略并结合容忍延迟的批处理方法，这种重型进程的效果最佳。

创建一次性商品

对于初始的一次性商品清单创建，我们建议使用 monetization.onetimeproducts.batchUpdate 或 inapp_products.insert 方法，并将 allowMissing 字段设置为 true，将 latencyTolerance 字段设置为 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT。这样可以最大限度地缩短在配额限制内创建目录所需的时间。

创建订阅商品

对于初始订阅大型目录创建，我们建议使用 monetization.subscriptions.batchUpdate 方法，并将 allowMissing 字段设置为 true，将 latencyTolerance 字段设置为 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT。这样可以最大限度地缩短在配额限制内创建目录所需的时间。

对于较小的订阅目录，Play Developer API 提供了 monetization.subscriptions.create 方法。或者，您也可以使用 allowMissing 参数通过 monetization.subscriptions.patch 方法创建订阅，如“产品更新”部分中所述。

之前的所有方法都会创建订阅及其基础方案（在 Subscription 对象中提供）。这些基础方案最初处于非有效状态。如需管理基础方案的状态，您可以使用 monetization.subscriptions.basePlans 端点，包括启用基础方案以使其可供购买。此外，您还可以使用 monetization.subscriptions.basePlans.offers 端点创建和管理优惠。

产品最新动态

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

更新一次性商品

您可以使用以下方法来更新现有的一次性商品。

monetization.onetimeproducts.batchUpdate
inappproducts.patch：修补端点用于部分更新资源。这意味着您可以更新在请求正文中指定的特定字段。如果您只需要更新资源的几个字段，通常会使用 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 获取目录数据，您可以使用 monetization.onetimeproducts.list、monetization.onetimeproducts.batchGet、inappproducts.list、inappproducts.batchGet、monetization.subscriptions.list 和 monetization.subscriptions.batchGet 方法。
生成差异报告：差异算法将生成差异报告。此报告将显示这两个系统之间的差异。
协调差异：生成差异报告后，您需要解决差异。这可能需要更新 CMS 中的数据，也可能需要使用开发者 API 的目录管理端点更新 Google Play 方面的数据，具体取决于您通常如何更新目录。如需协调不同步的商品，请使用“商品更新”部分中所述的更新端点。

产品弃用

Google Play Developer API 提供以下方法来帮助您弃用商品：

对于一次性商品：

对于订阅产品：

monetization.subscriptions.delete（针对订阅）。一旦至少有一个基础方案处于有效状态，便无法移除相应订阅。

在各种情况下，可能需要弃用产品，例如：

误创建。
停止提供某项功能或服务。

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