本指南將說明如何使用 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 組合，方便您在 Google Play 管理目錄。 可對應至兩個主要產品類別
- 一次性產品
- 訂閱產品
一次性產品
透過 inappproducts 端點，你可以一次性管理
包括建立、更新及刪除
以及管理價格和供應情形
視處理一次性產品交易的方式而定，你可能會建立模型
消耗性產品 (可任意購買不限次數) 或永久性產品
授權 (同一使用者不得重複設定授權)。您可以決定
一次性產品應為消耗性產品。
訂閱產品
monetization.subscriptions 端點可協助您管理訂閱項目
整合 Google Cloud 產品例如建立、更新
刪除訂閱方案，或是控管區域供應情形和價格。
除了 monetization.subscriptions 端點外，我們還提供
monetization.subscriptions.basePlans和
monetization.subscriptions.basePlans.offers 可分別管理
個訂閱項目基本方案和優惠
批次方法
inappproducts和monetization.subscriptions
端點提供許多批次方法，可讓您擷取或管理
至同一應用程式同時提供給 100 個實體。
批次方法 (搭配啟用的延遲時間容忍度) 時，支援較高的 對大型目錄開發人員來說特別實用 建立目錄或目錄協調
更新傳播延遲時間與處理量
產品建立或修改要求完成後，即無法變更
因為網路或後端的關係，使用者會立即看到自己的裝置
處理延遲。
根據預設，所有產品修改要求都受到延遲時間影響。也就是說
並經過最佳化調整，可透過後端系統快速傳播
幾分鐘內就會顯示於使用者裝置上不過，如果使用
以便正確評估這類修改要求的次數
適用於需要建立或更新多項產品的情況 (例如：
初始大型目錄建立期間)，您可以搭配
latencyTolerance欄位已設為
PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT。
這會大幅增加更新處理量。容許延遲更新
最多需要 24 小時才會套用至所有使用者裝置。
配額設定
使用 Play 開發人員時，請留意幾項配額限制 管理產品目錄的 API：
- Google Play Developer API 的預設查詢上限為 200,000 次 當天。這項配額限制適用於所有端點的用量匯總資料， 包括目錄管理 API
- 產品修改端點也強制規定的每個查詢只能有 7,200 次查詢 小時。針對一次性產品和訂閱項目，此為單一限制 以及所有的修改要求，包括建立、更新、啟用 刪除。批次修改方法呼叫會在這個配額中計為一次查詢。 無論要求的數量或延遲時間 機密性。
- 此外，這類修改作業的修改上限為 7,200 次 每小時以批次方法來說，每個巢狀修改要求數都會列入計算 分別用於這個配額這項配額有實際 只會影響對批次 API 執行易受延遲影響的使用者 在其他情況下，配額 2 的使用期限將前後結束 計算檔案大小
以下提供幾個實例說明範例，協助您瞭解 不同的要求
- 用來擷取一個項目的單次
get要求會耗用 1 個配額 1 的憑證 沒有配額 2 和 3 的權杖 (因為它們只涉及修改端點)。 - 如要擷取最多 100 個項目的批次
get要求，也會使用 1 個符記： 配額 1，但不含配額 2 和 3 的權杖。 - 一個用於單一項目的
modification要求，會耗用 1 個配額 1 的權杖 ，配額 2 的 1 個符記。要求易受延遲影響時， 會耗用 1 個配額 3 的權杖由於配額 C 與配額 2 相同 只使用一次修改，對用戶沒有實質影響 方法。 - 100 個延遲時間的批次
modification要求會耗用 1 個 配額 1 和 1 個配額 2 的憑證。這項配額設定應足以讓 增加目錄的最新狀態，但要是演算法不介意 如果超出這個配額，您可能會在每次呼叫時收到錯誤訊息。 - 100 個易受延遲影響項目的批次
modification要求將耗用 1 個配額 1、1 個配額 2 的憑證，以及 100 個配額 3 的權杖。
Catalog Management API 用量建議
只要遵守這些指南，您就能改善與 API 的互動， 確保目錄管理體驗順暢又有效率
監控您的使用情況
請留意使用率過高的問題。例如，在 完成整合的目錄管理端點 更多配額建立完整初始目錄，而且這可能會影響 在實際工作環境中使用其他端點，例如 purchase 狀態 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 Developer API 發布端點更新 即時更新目錄有時候，您可能必須在 更新 - 在同一程序中傳送電動電池電力。每項 需要不同設計選擇每項同步處理策略 可能更適合某些用途，而您可能有一組需求 就會產生兩個呼叫有時候，您可能會想製作 並在發現有新的變更時立即更新產品，例如 處理急需的產品更新 (亦即價格有誤，必須更正為 影片)。您也可以使用定期背景同步處理功能 後端和 Play 目錄會保持一致瞭解常見用途 在以下情況下，您可能會想實作不同目錄管理功能
店面目錄變更後傳送更新的時機
在理想情況下，後端 來盡量減少差異
這類更新適用於以下情況：
- 請務必確保產品符合現況。
- 你每天必須對產品進行幾項變更。
- 請務必更新已在正式販售且正在銷售的產品。
這個做法較容易實作，且能讓目錄保持同步 且金額差異最少
定期更新的使用時機
在後端以非同步方式執行產品版本的更新作業， 適合以下時機：
- 快速通知，無須確保產品都已更新。
- 您需要規劃批次更新或協調程序。
- 你已有 Content/ Catalog 管理系統來處理 而且經常更新你的目錄
如果是大型目錄，建議使用可容許延遲的批次方法 才能達到最大處理量
建立產品目錄
如果有大型目錄要上傳至 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.update 方法，搭配
allowMissing 參數，如「產品更新」一節所述。
上述所有方法都會在建立訂閱項目及基本方案時建立訂閱項目
(在訂閱物件內提供)。這些基本方案一開始
已停用。管理基本方案狀態，您可以使用
monetization.subscriptions.basePlans 端點，包括啟用
開放購買基本方案。
此外，monetization.subscriptions.basePlans.offers 端點
可讓你建立及管理優惠
產品最新消息
下列方法能讓您有效率地修改現有產品 確保你的產品與最新的調整相符
更新一次性產品
我們提供三種更新現有一次性產品的方法。
inappproducts.patch敬上 ：修補端點可用來更新部分資源。這代表您 可以更新您在要求主體中指定的特定欄位。修補程式 通常如果您只需要更新 Pod 的幾個欄位 資源。inappproducts.update敬上 ：更新端點可用來更新完整的資源。也就是說 您需要在要求主體中傳送整個資源物件。 通常在需要更新 Pod 中的所有欄位時 資源。allowMissing參數設為true且提供 產品 ID 不存在，端點會插入產品 而不會失敗inappproducts.batchUpdate敬上 ：這是更新端點的批次版本，可讓您修改 一項查詢帶出了多項產品。可與以下項目搭配使用：latencyTolerance欄位已設為PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT以提升處理量
更新訂閱產品
如要更新現有訂閱項目，可以使用
monetization.subscriptions.patch 方法，增加圍繞地圖邊緣的邊框間距。這個方法
請使用下列必要參數：
packageName：訂閱項目所屬的應用程式套件名稱。productId：訂閱項目的專屬產品 ID。regionsVersion：地區設定版本。
除非您要使用 allowMissing 參數建立新訂閱項目
，您必須提供 updateMask 參數。這個參數是
列出要更新的欄位，並以半形逗號分隔各個欄位。
舉例來說，如果您只想更新訂閱產品的商店資訊
您應將 listings 欄位指定為 updateMask 參數。
您可以使用 monetization.subscriptions.batchUpdate 同時更新多個訂閱項目。
與設為下列目標的 latencyTolerance 欄位搭配使用：
PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT，有助更高目標
處理量
如何啟用、停用、刪除基本方案，或將訂閱者遷移至
最新的基本方案價格版本會使用 monetization.subscriptions.basePlans 端點。
此外，你可以更新基本方案以及
monetization.subscriptions.basePlans.offers.patch敬上
方法。
目錄協調
您是否選擇在每次後端更新時更新 Google Play 目錄 如果您有目錄管理系統，或是定期變更目錄 Google Play 目錄以外的應用程式，在某些情況下 不符合 Play 應用程式設定中的目錄。 這可能是因為 Play 管理中心曾緊急變更目錄，發生系統服務中斷 或是目錄管理系統中最新的資料，或者遺失最新的資料。
您可以建立目錄對帳程序，避免長時間出現差異 視窗。
比較系統考量事項
建議您建構 diff 系統來偵測不一致情形，並協調 這兩個系統 建立 diff 系統時，請注意下列事項， 同步的目錄：
- 瞭解資料模型：第一步是解讀資料 開發人員 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敬上
方法。至少須有一項基本方案，才能移除訂閱項目
啟用。