collections.mp.microsoft.com/v9.0/collections/publisherQuery

A publisherQuery permite que seus próprios serviços consultem os produtos e direitos de um usuário, incluindo o status da assinatura do XBOX Game Pass. Seu serviço não deve sondar regularmente as compras do usuário, para evitar limites de taxa de chamadas baseados em uma janela de tempo por usuário. Atualmente, o limite é de 100 solicitações de consulta em uma janela de cinco minutos para o mesmo usuário. Acionar um limite de taxa causa uma resposta HTTP 429 com informações sobre quando a próxima solicitação poderá ser feita. Os resultados incluem apenas produtos de propriedade direta da conta de usuário em nome da qual seu serviço está chamando, ou aos quais essa conta tem direito. Direitos compartilhados que podem aparecer no cliente não são retornados. Confira Modelo de compartilhamento de produtos para jogos. Para obter informações específicas sobre como consultar o status da assinatura do Game Pass de um usuário, confira Detectar o acesso à assinatura do XBOX Game Pass a partir do seu serviço.

A publisherQuery dá suporte apenas a chamadas de serviços de parceiros.

Aplicativos cliente ou jogos não podem chamar esse serviço diretamente.

Atualizações e melhorias na publisherQuery (Collections Query v9)

A publisherQuery é a API de consulta do Collections mais recente (v9). Se estiver migrando da b2bLicensePreview (v8), revise esta seção para conhecer as diferenças de comportamento. A publisherQuery tem as seguintes alterações e melhorias em relação à b2bLicensePreview:

Capacidade de consultar o status da assinatura do XBOX Game Pass de um usuário
Exige uma lista predefinida de produtos a serem retornados. Uma prática recomendada, mas não obrigatória com a b2bLicensePreview v8. Títulos que não seguiam essa prática recomendada frequentemente tinham problemas após o lançamento, em que a solicitação atingia o tempo limite devido ao grande escopo de conteúdo com base nos parâmetros de consulta. Isso impedia que os usuários recebessem créditos no jogo até que o serviço do jogo fosse atualizado para especificar quais ProductIds desejava na solicitação de consulta.
Campos de dados de resposta simplificados para remover valores não usados ou desnecessários
Parâmetros de solicitação simplificados com base nos comentários dos desenvolvedores

Removidos do corpo da solicitação:

Market - Todas as solicitações têm contexto para todas as regiões na publisherQuery
ExpandSatisfyingItems - Todos os resultados expandem os direitos satisfeitos na publisherQuery
EntitlementsFilter - Não é usado, pois uma lista predefinida de productIds da consulta é obrigatória

A publisherQuery não dá suporte a LegacyProductIds (ProductIds gerados a partir do XBOX Developer Portal desativado e usados como ProductId pelo serviço XBOX Inventory).

Se estiver migrando seu serviço do XBOX Inventory, você precisará mapear internamente o StoreId (valor de ProductId do Collections) para o LegacyProductId correspondente no seu próprio serviço. Caso contrário, você pode usar a b2bLicensePreview v8, que retorna tanto o StoreId quanto os LegacyProductIds. Para obter mais informações, confira o artigo correspondente Selecionar a API de consulta do Collections certa para suas necessidades

Pré-requisitos

Revise os Pré-requisitos para APIs de serviço a serviço. Esta API dá suporte aos tipos de autenticação Microsoft Entra ID e X-token de autenticação delegada. Se a configuração do produto não estiver publicada no Partner Center, as chamadas poderão ter êxito, mas não retornarão resultados.

Solicitação

Sintaxe da solicitação

Método	URI da solicitação
`POST`	`https://collections.mp.microsoft.com/v9.0/collections/publisherQuery`

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
`Authorization`	`string`	Obrigatório. O X-token de autorização delegada ou o token de acesso de serviço do Microsoft Entra ID, com base no tipo de autenticação usado.
`Signature`	`string`	Obrigatório ao autenticar com X-tokens.
`User-Agent`	`string`	Recomendado. Ajuda a identificar seu serviço para registro em log e investigações.
`Host`	`string`	Deve ser `collections.mp.microsoft.com`.
`Content-Length`	`number`	O comprimento do corpo da solicitação.
`Content-Type`	`string`	Especifica o tipo de solicitação e de resposta. Atualmente, o único valor com suporte é `application/json`.

Corpo da solicitação

Parâmetro	Tipo	Descrição	Obrigatório
`beneficiaries`	`UserIdentity`	Usuário para o qual este item está sendo consumido. Para obter mais informações, confira Autenticação com Microsoft Entra ID e User Store IDs. Não é obrigatório para autenticação com X-token.	Somente para autenticação com User Store ID
`productSkuIds`	`list<ProductSkuId>`	Lista de produtos de destino. Para obter mais informações, confira a tabela a seguir. A API publisherQuery v9 dá suporte a no máximo 100 productSkuIds por solicitação.	Sim
`continuationToken`	`string`	Se houver vários conjuntos de produtos que não cabem em `maxPageSize`, o corpo da resposta retornará um token de continuação quando o limite de página for atingido. Forneça o token de continuação nas chamadas seguintes para obter mais resultados.	Não
`maxPageSize`	`number`	O número máximo de produtos a serem retornados em uma resposta. O padrão é 100 e o valor máximo é 200 itens por página.	Não
`excludeDuplicates`	`bool`	Remove direitos duplicados quando o usuário pode ter direito a um único produto a partir de várias fontes.	Não
`validityType`	`string`	Quando definido como All, todos os produtos de um usuário são retornados, incluindo itens expirados. Valid retorna produtos que têm status ativo, data de início < agora e data de término > agora). Invalid retorna produtos que não atendem aos requisitos da opção Valid.	Não
`sbx`	`string`	Valor opcional para autenticação com UserStoreIds que especifica a área restrita (sandbox) à qual os resultados devem ser limitados. Sem esse valor, o padrão é a área restrita RETAIL. A autenticação com X-Token não precisa desse valor, pois a área restrita é especificada no X-Token.	Não
`filterSatisfiedByProductIds`	`bool`	O valor padrão é False se não for fornecido. Quando False (valor recomendado), fornece uma visão completa de um direito satisfeito a partir dos pacotes ou produtos concessores no campo satisfiedByProductIds. Quando True, filtra a maioria dos ProductIDs concessores do campo satisfiedByProductIds e é fornecido como uma opção de compatibilidade, conforme necessário para os serviços.	Não

O objeto ProductSkuId contém os parâmetros a seguir.

Parâmetro	Tipo	Descrição	Obrigatório
`productId`	`string`	Também chamado de Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD.	Sim
`skuId`	`string`	O identificador de SKU específico, se houver várias ofertas do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010.	Não

Exemplo de solicitação

A API publisherQuery v9 dá suporte a no máximo 100 productSkuIds por solicitação. Se você fornecer mais de 100 productIds em productSkuIds, a API retornará um erro HTTP 400.

O maxPageSize padrão é 100, mas no exemplo ele é menor para demonstrar a solicitação dos itens restantes.

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

Resposta

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
`continuationToken`	`string`	Esse token é retornado quando o limite de página é atingido. Você pode especificar esse token de continuação nas chamadas seguintes para recuperar os produtos restantes.	Não
`items`	`PublisherQueryItemContractV9`	Uma matriz de produtos do usuário especificado. Para obter mais informações, confira a tabela a seguir.	Não

O objeto PublisherQueryItemContractV9 contém os parâmetros a seguir.

Parâmetro	Tipo	Descrição	Obrigatório
`acquiredDate`	`datetime`	Data em que o usuário adquiriu o item.	Sim
`acquisitionType`	`string`	Indica como o usuário possui esse direito. Para obter mais informações, confira Valores e significados de acquisitionType do produto.	Não
`endDate`	`datetime`	A data de término do item.	Sim
`id`	`string`	Uma ID que distingue este item da coleção dos outros itens que o usuário possui. Essa ID é exclusiva por produto.	Sim
`modifiedDate`	`datetime`	A data em que este item foi modificado pela última vez. Com produtos consumíveis, esse valor muda quando o saldo de quantidade do usuário muda por meio de outra compra do produto consumível ou quando uma solicitação de consumo é emitida.	Sim
`productId`	`string`	Também chamado de Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD.	Sim
`productKind`	`string`	Indica o tipo de produto. Para obter mais informações, confira Valores e significados do tipo de produto.	Sim
`quantity`	`number`	A quantidade do item. Produtos não consumíveis são sempre 1. Para produtos consumíveis, o valor representa o saldo restante que pode ser consumido ou atendido para o usuário.	Não
`recurrenceData`	`string`	ID do item usada como parâmetro `recurrenceId` das APIs de gerenciamento de recorrência. Mesmo valor de `id` da API RecurrenceQuery e de `recurrenceId` em um evento de Clawback.	Sim
`satisfiedByProductIds`	`list<string>`	Se o usuário tiver direito a este produto por causa de um pacote ou assinatura, os `ProductIds` desses produtos pais serão fornecidos aqui. OBSERVAÇÃO: usar o parâmetro de solicitação `filterSatisfiedByProductIds` como `True` resultará na ausência de alguns resultados neste parâmetro.	Não
`skuId`	`string`	O identificador de SKU específico, se houver várias ofertas do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010.	Sim
`startDate`	`datetime`	A data em que o item começa a ser válido.	Sim
`status`	`string`	O status do item. Para obter mais informações, confira Valores e significados do status do produto.	Sim
`tags`	`list<string>`	N/D.	Sim
`transactionId`	`GUID`	A ID da transação resultante da compra deste item. Pode ser usada para relatar um item como atendido. Esse valor é a OrderID associada ao momento em que o usuário comprou o item. Não deve ser usada como identificador exclusivo do direito deste usuário	Não
`trialData`	`TrialInformation`	Informações sobre este produto: se é uma avaliação e o tempo restante.	Sim

O objeto TrialInformation contém os parâmetros mostrados na tabela a seguir.

Parâmetro	Tipo	Descrição	Obrigatório
`isInTrialPeriod`	`bool`	Indica se o produto está em um período de avaliação, como uma assinatura	Sim
`isTrial`	`bool`	Indica se este produto está licenciado por meio de uma avaliação	Sim
`trialTimeRemaining`	`timespan`	Indica o tempo restante de validade da avaliação, no formato DD:HH:MM:SS.MS	Não

Valores e significados do tipo de produto

Valor	Descrição
`Application`	Um aplicativo na Microsoft Store que não está listado como jogo.
`Consumable`	Um consumível gerenciado pela Store, em que o saldo (ou quantidade) do usuário é mantido e gerenciado no serviço Collections. Na compra, a quantidade é adicionada ao saldo do usuário e pode ser removida por meio de uma solicitação de consumo. Os usuários podem comprar esse tipo de consumível novamente sem que ele seja atendido primeiro.
`Durable`	Um conteúdo para download comprado uma vez e de propriedade do usuário até a data de término do produto. Também é o tipo de produto para pacotes de complementos e pacotes de Season Pass.
`Game`	Um produto de jogo base.
`Pass`	Alguns tipos de assinatura, como o Game Pass
`UnmanagedConsumable`	Também chamado de consumível gerenciado pelo desenvolvedor. Deve ser atendido pelo jogo ou pelo serviço do jogo antes que o usuário possa comprar o produto novamente.
`Pass`	Uma assinatura gerenciada pela Store. Diferente de um tipo de assinatura de complemento configurado na página Complementos de um aplicativo no Partner Center.

Valores e significados do status do produto

Valor	Descrição
`Active`	O usuário tem direito ativo ao produto (incluindo itens em pré-venda). O usuário deve ter acesso a ele.
`Revoked`	Geralmente indica que o usuário solicitou um reembolso.
`Expired`	O produto fazia parte de um direito (geralmente uma assinatura) que já expirou.
`Banned`	N/D.
`Suspended`	N/D.

Valores e significados de acquisitionType do produto

Valor	Descrição
`Single`	Compra digital direta ou resgate de código.
`Recurring`	De propriedade do usuário ou com direito por meio de uma assinatura.
`Conditional`	De propriedade do usuário, mas requer outros produtos para continuar o uso. Ex.: jogos obtidos pelo Games With Gold

Noções básicas sobre os resultados de direitos satisfeitos com o campo `satisfiedByProductIds`

Se a matriz satisfiedByProductIds estiver vazia, o usuário tem um direito direto ao item, proveniente de uma compra direta. Caso contrário, se a matriz satisfiedByProductIds tiver um ou mais ProductIds, o usuário tem direito ao item por meio desses produtos (pacotes, assinaturas etc.). Se o usuário tiver um direito direto e um direito satisfeito a um item, e excludeDuplicates na solicitação for True, o direito direto terá prioridade e satisfiedByProductIds ficará vazio.

Exemplo de resposta

HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}

Solicitando os resultados restantes com o token de continuação

Se a consulta tiver mais resultados do que podem ser retornados em uma única resposta (controlado pelo maxPageSize), a resposta da consulta inicial terá um continuationToken. Você pode então usar esse continuationToken em uma solicitação subsequente, adicionando o token de continuação a uma cópia do corpo da solicitação anterior. Exemplo de solicitação de continuação:

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

Mesmo que você especifique o sinalizador excludeDuplicates, ao usar um token de continuação é possível obter entradas de direitos com status diferentes. Portanto, verifique se há entradas duplicadas nos resultados e se elas têm um status diferente de Active.

Confira também

Gerenciar produtos a partir dos seus serviços Autenticar seu serviço com as APIs da Microsoft Store Gerenciar produtos consumíveis a partir do seu serviço

Porting

Build Paths

collections.mp.microsoft.com/v9.0/collections/publisherQuery

Atualizações e melhorias na publisherQuery (Collections Query v9)

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Valores e significados do tipo de produto

Valores e significados do status do produto

Valores e significados de acquisitionType do produto

Noções básicas sobre os resultados de direitos satisfeitos com o campo `satisfiedByProductIds`

Exemplo de resposta

Solicitando os resultados restantes com o token de continuação

Confira também

​Atualizações e melhorias na publisherQuery (Collections Query v9)

​Pré-requisitos

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Valores e significados do tipo de produto

​Valores e significados do status do produto

​Valores e significados de acquisitionType do produto

​Noções básicas sobre os resultados de direitos satisfeitos com o campo satisfiedByProductIds

​Exemplo de resposta

​Solicitando os resultados restantes com o token de continuação

​Confira também

Atualizações e melhorias na publisherQuery (Collections Query v9)

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Valores e significados do tipo de produto

Valores e significados do status do produto

Valores e significados de acquisitionType do produto

Noções básicas sobre os resultados de direitos satisfeitos com o campo `satisfiedByProductIds`

Exemplo de resposta

Solicitando os resultados restantes com o token de continuação

Confira também