Consulta por produtos

Artigo
07/05/2024

Use esse método na API de coleção da Microsoft Store para obter todos os produtos que um cliente possui para aplicativos associados à sua ID de cliente do Azure AD. Você pode definir o escopo de sua consulta para um produto específico ou usar outros filtros.

Esse método foi projetado para ser chamado pelo serviço em resposta a uma mensagem do aplicativo. Seu serviço não deve sondar regularmente todos os usuários em um agendamento.

A biblioteca Microsoft.StoreServices fornece a funcionalidade desse método por meio da API StoreServicesClient.CollectionsQueryAsync.

Pré-requisitos

Para usar este método, você precisará de:

Um token de acesso do Azure AD que tem o valor https://onestore.microsoft.comdo URI da audiência.
Uma chave de ID da Microsoft Store que representa a identidade do usuário cujos produtos você deseja obter.

Para obter mais informações, consulte Gerenciar direitos de produto de um serviço.

Solicitar

Sintaxe da solicitação

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

Cabeçalho da solicitação

Cabeçalho	Tipo	Descrição
Autorização	string	Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário.
Host	string	Deve ser definido com o valor collections.mp.microsoft.com.
Content-Length	número	O tamanho do corpo da solicitação.
Content-Type	string	Especifica o tipo de solicitação e resposta. Atualmente, o único valor com suporte é application/json.

Corpo da solicitação

Parâmetro	Tipo	Descrição	Obrigatório
Beneficiários	listar<UserIdentity>	Uma lista de objetos UserIdentity que representam os usuários que estão sendo consultados em busca de produtos. Para obter mais informações, consulte a tabela abaixo.	Sim
continuationToken	string	Se houver vários conjuntos de produtos, o corpo da resposta retornará um token de continuação quando o limite de páginas for atingido. Forneça esse token de continuação aqui em chamadas subsequentes para recuperar os produtos restantes.	Não
maxPageSize	número	O número máximo de produtos a serem devolvidos em uma resposta. O valor padrão e máximo é 100.	Não
modifiedAfter	datetime	Se especificado, o serviço retorna apenas produtos que foram modificados após essa data.	Não
parentProductId	string	Se especificado, o serviço retornará apenas complementos que correspondam ao aplicativo especificado.	Não
productSkuIds	lista<ProductSkuId>	Se especificado, o serviço retorna apenas produtos aplicáveis aos pares de produto/SKU fornecidos. Para obter mais informações, consulte a tabela abaixo.	Não
tipos de produtos	cadeia de caracteres de lista<>	Especifica quais tipos de produtos devem ser retornados nos resultados da consulta. Os tipos de produtos com suporte são Application, Durable, Game e UnmanagedConsumable.	Sim
tipo de validade	string	Quando definido como Todos, todos os produtos de um usuário serão devolvidos, incluindo itens expirados. Quando definido como Válido, somente os produtos válidos neste momento são retornados (ou seja, eles têm um status ativo, data < de início agora e data de término é > agora).	Não

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

Parâmetro	Tipo	Descrição	Obrigatório
identityType	string	Especifique o valor da cadeia de caracteres b2b.	Sim
identityValue	string	A chave de ID da Microsoft Store que representa a identidade do usuário para o qual você deseja consultar produtos.	Sim
localTicketReference	string	O identificador solicitado para os produtos devolvidos. Os itens retornados no corpo da resposta terão um localTicketReference correspondente. Recomendamos que você use o mesmo valor que a declaração userId na chave de ID da Microsoft Store.	Sim

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

Parâmetro	Tipo	Descrição	Obrigatório
productId	string	A ID da Loja de um produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um produto é 9NBLGGH42CFD.	Sim
skuId	string	A ID da Loja para o SKU de um produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um SKU é 0010.	Sim

Exemplo de solicitação

POST https://collections.mp.microsoft.com/v6.0/collections/query HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Q…….
Host: collections.mp.microsoft.com
Content-Length: 2531
Content-Type: application/json

{
  "maxPageSize": 100,
  "beneficiaries": [
    {
      "localTicketReference": "1055521810674918",
      "identityValue": "eyJ0eXAiOiJ……",
      "identityType": "b2b"
    }
  ],
  "modifiedAfter": "\/Date(-62135568000000)\/",
  "productSkuIds": [
    {
      "productId": "9NBLGGH5WVP6",
      "skuId": "0010"
    }
  ],
  "productTypes": [
    "UnmanagedConsumable"
  ],
  "validityType": "All"
}

Resposta

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
continuationToken	string	Se houver vários conjuntos de produtos, esse token será retornado quando o limite de páginas for atingido. Você pode especificar esse token de continuação em chamadas subsequentes para recuperar os produtos restantes.	Não
itens	CollectionItemContractV6	Uma matriz de produtos para o usuário especificado. Para obter mais informações, consulte a tabela abaixo.	Não

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

Parâmetro	Tipo	Descrição	Obrigatório
adquirida Data	datetime	A data em que o usuário adquiriu o item.	Sim
campaignId	string	O ID da campanha que foi fornecido no momento da compra para este item.	Não
devOfferId	string	A ID da oferta de uma compra no aplicativo.	Não
endDate	datetime	A data de término do item.	Sim
dados de atendimento	cadeia de caracteres de lista<>	N/D	Não
inAppOfferToken	string	A cadeia de caracteres de ID do produto especificada pelo desenvolvedor atribuída ao item no Partner Center. Um exemplo de ID de produto é product123.	Não
itemId	string	Uma ID que identifica esse item de coleta de outros itens que o usuário possui. Esse ID é exclusivo por produto.	Sim
localTicketReference	string	A ID do localTicketReference fornecido anteriormente no corpo da solicitação.	Sim
modifiedDate	datetime	A data em que este item foi modificado pela última vez.	Sim
orderId	string	Se presente, o ID do pedido do qual este item foi obtido.	Não
orderLineItemId	string	Se presente, o item de linha do pedido específico para o qual esse item foi obtido.	Não
tipo de propriedade	string	A cadeia de caracteres OwnedByBeneficiary.	Sim
productId	string	A ID da Loja do produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um produto é 9NBLGGH42CFD.	Sim
productType	string	Um dos seguintes tipos de produto: Aplicativo, Durável e Consumível não gerenciado.	Sim
compradoPaís	string	N/D	Não
comprador	IdentityContractV6	Se presente, isso representa a identidade do comprador do item. Veja os detalhes desse objeto abaixo.	Não
quantity	número	A quantidade do item. Atualmente, isso sempre será 1.	Não
skuId	string	A ID da Loja para o SKU do produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um SKU é 0010.	Sim
skuType	string	Tipo do SKU. Os valores possíveis incluem Trial, Full e Rental.	Sim
startDate	datetime	A data em que o item começa a ser válido.	Sim
status	string	O status do item. Os valores possíveis incluem Ativo, Expirado, Revogado e Banido.	Sim
marcas	cadeia de caracteres de lista<>	N/D	Sim
transactionId	guid	A ID da transação como resultado da compra deste item. Pode ser usado para relatar um item como processado.	Sim

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

Parâmetro	Tipo	Descrição	Obrigatório
identityType	string	Contém o valor pub.	Sim
identityValue	string	O valor da cadeia de caracteres do publisherUserId da chave de ID da Microsoft Store especificada.	Sim

Exemplo de resposta

HTTP/1.1 200 OK
Content-Length: 7241
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: a9988cf9-652b-4791-beba-b0e732121a12
MS-CV: xu2HW6SrSkyfHyFh.0.1
MS-ServerId: 020022359
Date: Tue, 22 Sep 2015 20:28:18 GMT

{
  "items" : [
    {
      "acquiredDate" : "2015-09-22T19:22:51.2068724+00:00",
      "devOfferId" : "f9587c53-540a-498b-a281-8a349491ed47",
      "endDate" : "9999-12-31T23:59:59.9999999+00:00",
      "fulfillmentData" : [],
      "inAppOfferToken" : "consumable2",
      "itemId" : "4b8fbb13127a41f299270ea668681c1d",
      "localTicketReference" : "1055521810674918",
      "modifiedDate" : "2015-09-22T19:22:51.2513155+00:00",
      "orderId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31",
      "ownershipType" : "OwnedByBeneficiary",
      "productId" : "9NBLGGH5WVP6",
      "productType" : "UnmanagedConsumable",
      "purchaser" : {
        "identityType" : "pub",
        "identityValue" : "user123"
      },
      "skuId" : "0010",
      "skuType" : "Full",
      "startDate" : "2015-09-22T19:22:51.2068724+00:00",
      "status" : "Active",
      "tags" : [],
      "transactionId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31"
    }
  ]
}

Partilhar via

Consulta por produtos

Pré-requisitos

Solicitar

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Comentários

Recursos adicionais

Partilhar via

Consulta por produtos

Pré-requisitos

Solicitar

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Exemplo de resposta

Tópicos relacionados

Comentários

Recursos adicionais