Compartilhar via

Consulta por produtos

  • Artigo

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"
    }
  ]
}