Reminder: By Aug 31, 2025, all new apps and updates to existing apps must use Billing Library version 7 or newer. If you need more time to update your app, you can request an extension until Nov 1, 2025. Learn about Play Billing Library version deprecation.

本頁面由 Cloud Translation API 翻譯而成。

管理產品目錄

本指南說明如何使用 Google Play Developer API，為 Play 應用程式建立及管理產品目錄。

如要透過 Google Play 結帳系統在應用程式中販售產品，請設定目錄，列出所有要開放使用者購買的產品。您可以透過 Play 管理中心完成這項作業，也可以使用 Google Play Developer API 自動管理目錄。自動化功能可確保目錄內容永遠保持最新狀態，並擴大規模，以因應手動協調作業難以負荷的大型目錄。本指南將說明如何使用 Play Developer API，為 Play 應用程式建立及管理產品目錄。如需瞭解如何設定 Google Play Developer API 以進行後端整合，請參閱「準備工作」指南。

目錄管理 API

如要瞭解可透過 Google Play 帳單系統販售的各種產品，請參閱「瞭解各種應用程式內商品和商品目錄注意事項」。Google 提供兩組主要的 API，用於管理 Play 上的目錄，分別對應兩大產品類別：

一次性產品
訂閱產品

一次性產品

一次性產品 (原稱應用程式內商品) 使用一次性產品物件模型，可為一次性產品設定多個購買選項和優惠。一次性產品物件模型可讓您更有彈性地銷售產品，並降低管理這類產品的複雜度。現有的應用程式內商品會遷移到一次性產品物件模型。詳情請參閱「遷移應用程式內商品」一節。

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 的 0 個權杖 (因為這兩個配額只與修改端點有關)。
批次 get 要求擷取最多 100 個項目時，也會消耗配額 1 的 1 個權杖，但不會消耗配額 2 和 3 的權杖。
針對單一項目發出 modification 要求時，會耗用配額 1 的 1 個權杖和配額 2 的 1 個權杖。如果要求對延遲時間很敏感，也會耗用配額 3 的 1 個權杖。由於配額 C 的限制與配額 2 相同，因此對於只使用單一修改方法的使用者而言，這項限制沒有實際影響。
如果批次要求 100 個可容許延遲的項目，則會耗用配額 1 的 1 個權杖，以及配額 2 的 1 個權杖。modification這項配額設定應可提供充足的緩衝空間，讓您更新目錄，但如果演算法未留意這項配額，且超出這個速率，您可能會在每次額外呼叫時收到錯誤訊息。
如果批次 modification 要求包含 100 個對延遲時間敏感的項目，則會耗用配額 1 的 1 個權杖、配額 2 的 1 個權杖，以及配額 3 的 100 個權杖。

目錄管理 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 發布端點，在目錄發生變更時進行更新。有時您可能需要採取定期更新的做法，在同一個程序中傳送一連串變更。每種方法都需要不同的設計選擇。每種同步策略都比較適合某些用途，視情況而定，您可能需要同時採用兩種策略。有時你可能想在得知新變更時立即更新產品，例如處理緊急產品更新 (即盡快修正錯誤價格)。其他時候，您可以使用定期背景同步，確保後端和 Google 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 方法。或者，您也可以使用 monetization.subscriptions.patch 方法和 allowMissing 參數建立訂閱項目，詳情請參閱「產品更新」一節。

上述所有方法都會建立訂閱項目和基本方案 (在 Subscription 物件中提供)。這些基本方案一開始會處於非啟用狀態。如要管理基本方案的狀態，可以使用 monetization.subscriptions.basePlans 端點，包括啟用基本方案，讓使用者可以購買。此外，您也可以透過 monetization.subscriptions.basePlans.offers 端點建立及管理方案。

產品最新消息

您可以透過下列方法有效修改現有產品，確保產品與最新調整項目一致。

更新一次性產品

您可以透過下列方法更新現有的一次性產品。

monetization.onetimeproducts.batchUpdate
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 目錄以外有目錄管理系統或資料庫，可能會發生與 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 中的資料，或是使用 Developer API 目錄管理端點更新 Google Play 端的資料。如要調解不同步的產品，請使用「產品更新」一節所述的更新端點。

產品淘汰

Google Play Developer API 提供下列方法，協助您淘汰產品：

一次性產品：

訂閱產品：

monetization.subscriptions.delete 訂閱項目。如果已啟用至少一個基本方案，就無法移除訂閱項目。

在各種情況下，您可能都需要淘汰產品，例如：

誤建。
停止提供某項功能或服務。

建議您將產品淘汰作業納入目錄管理策略。