Play Catalog API 开发者指南

注意：Play Catalog API 将于 2026 年 7 月 22 日发布

借助 Play Catalog API，在 Google Play 上注册的第三方应用商店 (3PAS) 可以轮询 Google Play 应用目录的更新。调用方可以检索自上次每日目录导出以来，已修改或已下架应用的目录详细信息。

注意：Play Catalog API 是对每日目录导出的可选补充，所提供的信息内容完全一致。如果您不需要新鲜度高于 24 小时的数据，则无需与此 API 集成。

注意：Play Catalog API 只能用于检索最近更改过的数据， 不能用于检索完整目录。若要获取所有应用的完整目录，应使用目录导出功能。

如需查看端点、方法和资源架构的完整列表，请参阅 Play Catalog API 参考文档。

准备工作

您必须先完成主要的使用入门指南，设置 API 访问权限、服务凭据和 Google Cloud 项目，然后才能调用 Play Catalog API。

---

API 设计与架构

Play 目录导出每 24 小时生成一次。Play Catalog API 提供了一种日内轮询机制，用于检索自上次导出以来发生的更新：

1. 轮询更新事件：您可以使用 startTime 和 endTime 窗口查询 appstorecatalog.recentUpdateEvents.list，以查找哪些软件包名称已被修改或删除。
2. 获取详细视图：对于每个已修改的软件包名称，您都可以调用 appstorecatalog.recentAppViews.get 来获取详细的 CatalogAppView 元数据。

该 API 为只读，并且只能返回过去 36 小时内发生的事件。该 API 的 QPS 上限为 2，两个方法共用这一上限。

---

1. 轮询目录更新事件

如需检索在特定时间窗口内发生更改的软件包列表，请调用 appstorecatalog.recentUpdateEvents.list 方法。

仅返回符合条件的应用的更新事件。符合条件的应用必须：

• 已选择纳入调用应用商店的目录。
• 已在 Google Play 商店中发布，并已在美国 (US) 上架。

注意：建议频繁轮询更新事件，例如每分钟轮询一次。如果轮询频率较低，可能会导致一次性返回大量更新事件，从而难以及时处理这些事件。

了解更新类型

• MODIFICATION：当符合条件的应用被修改、首次发布、开始面向美国提供，或新近选择加入您的目录时触发。
• DELETION：当应用取消发布、选择不纳入目录、被暂停、被屏蔽或停止面向美国提供时触发。

---

2. 检索目录应用视图

对于通过 MODIFICATION 事件返回的每个软件包，您都可以通过调用 appstorecatalog.recentAppViews.get 方法来获取其更新后的目录详细信息。

注意：未找到错误
如果在过去 36 小时内，所请求的软件包名称未发生任何更新事件，则 appstorecatalog.recentAppViews.get 方法会抛出 NOT_FOUND 错误 (404)。在这种情况下，您应回退到使用每日完整目录导出功能。

---

3. 最佳实践与同步

为确保您商店中的目录数据库保持一致，请遵循以下集成指南：

• 每日导出同步：使用每日目录导出导入符合条件的应用的完整列表。
• （可选）日内同步：使用移动时间窗口定期（例如每分钟）轮询 appstorecatalog.recentUpdateEvents.list 端点。确保您使用 nextPageToken 处理分页。
  • 流程更新：
    • 对于 MODIFICATION 事件，请使用 appstorecatalog.recentAppViews.get 获取更新后的 CatalogAppView，并更新本地数据库。
    • 对于 DELETION 事件，请从商店的商品详情中移除相应应用，或对用户隐藏该应用。
  • 处理重复的修改事件：您可能会看到同一应用的多个 MODIFICATION 事件。这意味着该应用在查询的时间窗口内被多次修改。 appstorecatalog.recentAppViews.get 将始终返回最新一次修改的应用视图。