本指南說明如何使用 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 為 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 的預設查詢上限為每日 200,000 次。這項配額限制適用於所有端點的用量匯總資料，包括目錄管理 API。
- 產品修改端點也會強制執行每小時 7,200 次查詢的限制。這是一次性產品與訂閱項目，以及所有修改要求 (包括建立、更新、啟用、刪除) 的單一限制。無論內含的個別要求數量或其延遲時間為何，批次修改方法呼叫都會計為這項配額的一次查詢。
- 易受延遲影響的修改作業也設有每小時 7,200 次修改的限制。以批次方法來說，為了計算這個配額，每個巢狀修改要求都會分開計數。這個配額只會影響執行延遲敏感更新的批次 API 使用者，在其他情況下則耗盡配額 2。
以下提供幾個實例說明範例，協助您瞭解不同要求的配額用量：
- 單一
get要求擷取一個項目時，系統會耗用 1 個配額 1 的權杖，但不會使用配額 2 和 3 的權杖 (因為這些要求只涉及修改端點)。 - 最多可擷取 100 個項目的批次
get要求也會耗用 1 個配額 1 的權杖，但沒有任何配額 2 和 3 的權杖。 - 向某個項目發出單次
modification要求時，系統會耗用 1 個配額 1 和 1 個配額 2 的權杖。如果要求容易受到延遲影響，也會耗用配額 3 的 1 個符記。由於配額 C 的限制與配額 2 相同，因此如果使用者只使用單一修改方法，這對使用者沒有實質影響。 - 如果批次
modification要求為 100 個延遲時間的項目，就會耗用 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 中建立產品目錄時，請留意特定限制和注意事項。瞭解這些限制且瞭解目錄結構之後，就可以決定您的同步處理策略。
目錄同步處理策略
您可以透過 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：修補程式端點用於更新部分資源，這表示您可以更新在要求主體中指定的特定欄位。通常只需要更新資源的幾個欄位時，就會使用修補程式端點。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 目錄每次變更時更新 Google Play 目錄，或使用其他資料庫。這可能是因為在主控台中手動變更目錄、發生目錄管理系統服務中斷，或是您遺失了最新資料。
您可以建立目錄對帳程序，避免長時間的差異發生。
比較系統考量事項
建議您建構差異比較系統來偵測不一致情形，並協調這兩個系統。建構 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 方法刪除訂閱項目。啟用至少一個基本方案後，就無法移除訂閱項目。