XStoreQueryAssociatedProductsAsync
取得使用者可在目前遊戲中購買之產品的商店清單資訊。語法
參數
storeContextHandle _In_類型:XStoreContextHandle 由 XStoreCreateContext 傳回之使用者的商店內容控制代碼。 productKinds _In_
類型:XStoreProductKind 要傳回的產品類型。 maxItemsToRetrievePerPage _In_
類型:uint32_t 每頁要擷取的項目數目上限。 每頁傳回的項目數目可介於 0 到
maxItemsToRetrievePerPage 之間。
如需詳細資訊,請參閱分頁。
async _Inout_類型:XAsyncBlock* 定義正在進行之非同步工作的 XAsyncBlock。 使用 XAsyncBlock 來輪詢呼叫的狀態並擷取呼叫結果。 如需詳細資訊,請參閱 XAsyncBlock。
傳回值
類型:HRESULT HRESULT 成功或錯誤碼。備註
若要取得此函式的商店清單資訊與執行結果,請在呼叫此函式之後呼叫 XStoreQueryAssociatedProductsResult。 XStoreQueryAssociatedProductsResult 包含一個XStoreProductQueryHandle,您可以呼叫 XStoreEnumerateProductsQuery 來列舉它。
您無法事先得知此查詢會傳回的產品數目。
此 API 只會傳回使用者可在 Microsoft Store 中瀏覽或在遊戲內購買的產品。
結果不包含任何已隱藏、已過期或已從商店移除的產品。
如果您需要這類產品的詳細資料,請使用 XStoreQueryProductsAsync 並傳入該產品的 Store ID。
分頁
此函式會跨多個頁面傳回產品 (單一頁面最多maxItemsToRetrievePerPage 個項目)。
使用 XStoreProductsQueryHasMorePages 和 XStoreProductsQueryNextPageAsync/XStoreProductsQueryNextPageResult 來處理所有分頁結果。
在 XStoreProductsQueryHasMorePages 傳回 false 之前,分頁都尚未完成。
分頁在沙箱與 RETAIL 之間的行為可能不同。
在沙箱中,項目會累積到
maxItemsToRetrievePerPage 個之後才傳回一頁。
在 RETAIL 中,每頁傳回 0 到 1 個項目是很常見的情況。所有使用此 API 的遊戲都務必在發行前實作並測試分頁。若要在沙箱中測試分頁行為,請暫時將 maxItemsToRetrievePerPage 設為小於已發佈至您沙箱之產品數目的值。
若要在遊戲發行前於 RETAIL 中測試,請使用 Partner Center 中「定價和可用性」頁面上的 Enable Private Audience 選項來發佈產品。
若要在遊戲發行後於 RETAIL 中測試,請使用套件測試版本 (package flight)。需求
標頭: XStore.h (包含在 XGameRuntime.h 中) 程式庫: xgameruntime.lib 支援的平台: Windows、XBOX One 系列主機和 XBOX Series 主機概念文件
- 在遊戲中實作遊戲內購買
- 基本商店作業
- 授與玩家附加元件內容的存取權
- GDK 商務系統概觀
- Microsoft Store API 的細微速率限制
- 商店開發權利工具 (DevEntitlementTool.exe)
另請參閱
XStoreXStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync
基本商店作業
授與玩家附加元件內容的存取權
