Play Catalog API 開發人員指南

注意： Play Catalog API 將於 2026 年 7 月 22 日推出

透過 Play 目錄 API，在 Google Play 註冊的第三方應用程式商店 (3PAS) 可以輪詢 Google Play 應用程式目錄的更新。如果應用程式在上次每日目錄匯出後經過修改或移除，來電者可以擷取目錄詳細資料。

注意： Play 目錄 API 是每日目錄匯出的選用補充工具，提供的資訊與每日目錄匯出相同。如果不需要 24 小時內的最新資料，就不必整合這個 API。

注意： Play 目錄 API 只能用於擷取最近變更的資料。但無法用於擷取完整目錄。目錄匯出功能可用於取得所有應用程式的完整目錄。

如需端點、方法和資源結構定義的完整清單，請參閱 Play 目錄 API 參考資料。

事前準備

您必須先完成主要的入門指南，設定 API 存取權、服務憑證和 Google Cloud 專案，才能呼叫 Play Catalog API。

---

API 設計與架構

系統每 24 小時會產生一次 Play 目錄匯出資料。Play 目錄 API 提供日內輪詢機制，可擷取自上次匯出以來發生的更新：

1. 輪詢更新事件：您可以使用 appstorecatalog.recentUpdateEvents.list 查詢 startTime 和 endTime 視窗，找出已修改或刪除的套件名稱。
2. 擷取詳細檢視畫面：針對每個經過修改的套件名稱，呼叫 appstorecatalog.recentAppViews.get 擷取詳細的 CatalogAppView 中繼資料。

這項 API 為唯讀，且只能傳回過去 36 小時內發生的事件。這兩種方法共用每秒查詢次數限制，上限為 2。

---

1. 輪詢目錄更新事件

如要擷取特定時間範圍內變更的套件清單，請呼叫 appstorecatalog.recentUpdateEvents.list 方法。

系統只會傳回符合資格應用程式的更新事件。合格應用程式必須符合下列條件：

• 已選擇將目錄納入通話應用程式商店。
• 已發布並在美國 Google Play 商店上架。

注意： 建議經常輪詢更新事件，例如每分鐘一次。如果輪詢頻率不高，可能會一次傳回大量更新事件，導致難以即時處理。

瞭解更新類型

• 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 一律會傳回最新修改內容的應用程式檢視畫面。