Consulta por produtos

  • Artigo

Use esse método na API da coleção da Microsoft Store para obter todos os produtos que pertence a um cliente em relação a aplicativos que estejam associados com sua ID de cliente do Azure AD. Você pode analisar sua consulta para um determinado produto ou usar outros filtros.

Esse método é projetado para ser chamado pelo seu serviço em resposta a uma mensagem de seu 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 esse método, você precisará:

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

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

Solicitação

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

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

Corpo da solicitação

Parâmetro Type Descrição Obrigatório
beneficiários listar<UserIdentity> Uma lista de objetos UserIdentity que representam os usuários que estão sendo consultados para 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ágina for atingido. Forneça esse token de continuação em chamadas subsequentes para recuperar produtos restantes. Não
maxPageSize número O número máximo de produtos para retornar uma resposta. O valor máximo e padrão é 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 retorna apenas complementos que correspondem ao aplicativo especificado. Não
productSkuIds list<ProductSkuId> Se especificado, o serviço retornará apenas os produtos aplicáveis aos pares produto/SKU fornecidos. Para obter mais informações, consulte a tabela abaixo. Não
productTypes cadeia de caracteres de lista<> Especifica quais tipos de produtos retornar nos resultados da consulta. Os tipos de produto com suporte são Application, Durable, Game e UnmanagedConsumable. Sim
validityType string Quando definido como All, todos os produtos para um usuário serão retornados, incluindo itens expirados. Quando definido como Valid, somente os produtos que são válidos serão retornados nesse momento (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 Type Descrição Obrigatório
identityType string Especifique o valor de cadeia de caracteres b2b. Sim
identityValue string O chave ID da Microsoft Store que representa a identidade do usuário cujos produtos você deseja consultar. Sim
localTicketReference string O identificador solicitado para os produtos retornados. Itens retornados no corpo da resposta terão uma correspondência localTicketReference. Recomendamos que você use o mesmo valor do que a declaração userId na chave ID da Microsoft Store. Sim

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

Parâmetro Type Descrição Obrigatório
productId string O ID da Store para um produto no catálogo da Microsoft Store. Um exemplo de ID da loja para um produto é 9NBLGGH42CFD. Sim
skuId string O ID da Store para SKU de produto no catálogo da Microsoft Store. Um exemplo de ID da loja para 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 Type Descrição Obrigatório
continuationToken string Se houver vários conjuntos de produtos, esse token será retornado quando o limite de página for atingido. Você pode especificar esse token de continuação em chamadas subsequentes para recuperar 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 Type Descrição Obrigatório
acquiredDate DATETIME A data em que o usuário adquiriu o item. Sim
campaignId string A ID da campanha que foi fornecida para este item no momento da compra. Não
devOfferId string A ID de oferta de uma compra realizada em aplicativo. Não
endDate DATETIME A data de término do item. Sim
fulfillmentData 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 do produto é product123. Não
itemId string A ID que identifica esse item de coleção em relação a outros itens que o usuário tem. Essa ID é exclusiva por produto. Sim
localTicketReference string A ID de localTicketReference anteriormente fornecida no corpo da solicitação. Sim
modifiedDate DATETIME A data em que este item foi modificado pela última vez. Sim
orderId string Se presente, a ID do pedido do qual este item foi obtido. Não
orderLineItemId string Se presente, o item de linha da ordem específica para a qual o item foi obtido. Não
ownershipType string A cadeia de caracteres OwnedByBeneficiary. Sim
productId string A ID da Store para o 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: Application, Durable e UnmanagedConsumable. Sim
purchasedCountry string N/D Não
purchaser IdentityContractV6 Se presente, representa a identidade do comprador do item. Veja os detalhes para esse objeto abaixo. Não
quantidade número A quantidade do item. Atualmente, sempre será 1. Não
skuId string A ID da Store para o SKU do produto no catálogo da Microsoft Store. Um exemplo de ID da loja para SKU é 0010. Sim
skuType string O tipo de SKU. Os valores possíveis incluem Trial, Full e Rental. Sim
startDate DATETIME A data em que a validade do item é iniciada. Sim
status string O status do item. Os valores possíveis incluem Active, Expired, Revoked e Banned. Sim
marcas cadeia de caracteres de lista<> N/D Sim
transactionId guid A ID de transação como resultado da compra desse item. Pode ser usada para declarar um item como providenciado. Sim

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

Parâmetro Type Descrição Obrigatório
identityType string Contém o valor pub. Sim
identityValue string O valor da sequência de 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: 699681ce-662c-4841-920a-f2269b2b4e6c
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"
    }
  ]
}