Skip to main content

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 主機

概念文件

另請參閱

XStore
XStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync
基本商店作業
授與玩家附加元件內容的存取權
Last modified on October 6, 2026