Skip to main content

XStoreQueryAssociatedProductsAsync

Obtém informações da listagem da loja para produtos que os usuários podem comprar dentro do jogo atual.

Sintaxe

Parâmetros

storeContextHandle   _In_
Tipo: XStoreContextHandle
O identificador de contexto da loja para o usuário retornado por XStoreCreateContext. productKinds   _In_
Tipo: XStoreProductKind
O tipo de produtos a serem retornados. maxItemsToRetrievePerPage   _In_
Tipo: uint32_t
O número máximo de itens a serem recuperados por página. O número de itens retornados por página pode variar de 0 a maxItemsToRetrievePerPage. Para obter mais informações, consulte Paginação. async   _Inout_
Tipo: XAsyncBlock*
Um XAsyncBlock que define o trabalho assíncrono que está sendo realizado. Use o XAsyncBlock para sondar o status da chamada e recuperar os resultados da chamada. Para obter mais informações, consulte XAsyncBlock.

Valor retornado

Tipo: HRESULT Código de sucesso ou erro HRESULT.

Comentários

Para obter as informações da listagem da loja e o resultado da execução desta função, chame XStoreQueryAssociatedProductsResult depois de chamar esta função. XStoreQueryAssociatedProductsResult contém um XStoreProductQueryHandle que você enumera chamando XStoreEnumerateProductsQuery. Não é possível saber antecipadamente o número de produtos que esta consulta retorna. Esta API retorna apenas produtos que os usuários podem procurar na Microsoft Store ou comprar dentro do jogo. Os resultados não incluem nenhum produto oculto, expirado ou removido da loja. Se você precisar de detalhes de um produto desse tipo, use XStoreQueryProductsAsync e passe a Store ID do produto.

Paginação

Esta função retorna produtos em várias páginas (até maxItemsToRetrievePerPage itens em uma única página). Use XStoreProductsQueryHasMorePages e XStoreProductsQueryNextPageAsync/XStoreProductsQueryNextPageResult para processar todos os resultados paginados. A paginação não está concluída até que XStoreProductsQueryHasMorePages retorne false.
A paginação pode se comportar de forma diferente entre áreas restritas e RETAIL. Em uma área restrita, os itens se acumulam até maxItemsToRetrievePerPage antes que uma página seja retornada. Em RETAIL, é comum que de 0 a 1 item seja retornado por página.É importante que todos os jogos que usam esta API implementem e testem a paginação antes do lançamento.Para testar o comportamento da paginação em uma área restrita, defina temporariamente maxItemsToRetrievePerPage como um valor menor que o número de produtos publicados na sua área restrita. Para testar em RETAIL antes do lançamento do seu jogo, publique produtos usando a opção Enable Private Audience na página ‘Pricing and availability’ do Partner Center. Para testar em RETAIL após o lançamento do seu jogo, use um package flight.
O código a seguir mostra como recuperar os resultados da consulta de produtos em várias páginas. Certifique-se de que o identificador da consulta seja passado adiante pela recursão de paginação para evitar vazamentos.

Requisitos

Cabeçalho: XStore.h (incluído em XGameRuntime.h) Biblioteca: xgameruntime.lib Plataformas com suporte: Windows, consoles da família XBOX One e consoles XBOX Series

Documentação conceitual

Confira também

XStore
XStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync
Operações básicas da loja
Conceder aos jogadores acesso ao conteúdo de complementos
Last modified on October 6, 2026