Consultar productos

  • Artículo

Usa este método en la API de recopilación de Microsoft Store para obtener todos los productos que posee un cliente para las aplicaciones asociadas al identificador de cliente de Azure AD. Puedes definir el ámbito de la consulta para un producto concreto, o bien usar otros filtros.

Este método está diseñado para que el servicio lo llame en respuesta a un mensaje de la aplicación. El servicio no debe sondear regularmente a todos los usuarios en una programación.

La biblioteca Microsoft.StoreServices proporciona la funcionalidad de este método a través de la API StoreServicesClient.CollectionsQueryAsync.

Requisitos previos

Para usar este método, necesitarás:

  • Un token de acceso de Azure AD que tiene el valor https://onestore.microsoft.comde URI de audiencia .
  • Clave de identificador de Microsoft Store que representa la identidad del usuario cuyos productos quiere obtener.

Para obtener más información, consulte Administración de derechos de producto desde un servicio.

Solicitud

Sintaxis de la solicitud

Método URI de solicitud
POST https://collections.mp.microsoft.com/v6.0/collections/query

Encabezado de solicitud

Encabezado Tipo Descripción
Authorization string Necesario. Token de acceso de Azure AD con el formato Token de portador<>.
Host cadena Debe establecerse en el valor collections.mp.microsoft.com.
Content-Length number Longitud del cuerpo de la solicitud.
Content-Type string Especifica los tipos de solicitud y respuesta. Actualmente, el único valor admitido es application/json.

Cuerpo de la solicitud

Parámetro Tipo Descripción Obligatorio
beneficiaries list<UserIdentity> Lista de objetos UserIdentity que representan a los usuarios que se consultan para los productos. Para obtener más información, consulte la tabla siguiente. Sí
continuationToken string Si hay varios conjuntos de productos, el cuerpo de la respuesta devuelve un token de continuación cuando se alcanza el límite de la página. Proporciona ese token de continuación aquí en llamadas posteriores para recuperar los productos restantes. No
maxPageSize number Número máximo de productos que puede devolver una respuesta. El valor predeterminado y máximo es de 100. No
modifiedAfter datetime Si se especifica, el servicio devuelve solo los productos modificados después de esta fecha. No
parentProductId string Si se especifica, el servicio devuelve solo los complementos que corresponden a la aplicación especificada. No
productSkuIds list<ProductSkuId> Si se especifica, el servicio solo devuelve los productos aplicables a los pares de producto o SKU proporcionados. Para obtener más información, consulte la tabla siguiente. No
productTypes cadena de lista<> Especifica los tipos de productos que se van a devolver en los resultados de la consulta. Los tipos de productos admitidos son Application, Durable, Game y UnmanagedConsumable. Sí
validityType string Si se establece en All, se devolverán todos los productos de un usuario, incluidos los artículos expirados. Si se establece en Valid, solo se devolverán los productos que sean válidos en este momento (es decir, que tengan un estado activo, una fecha de inicio anterior a la actual < y una fecha final posterior > a la actual). No

El objeto UserIdentity contiene los parámetros siguientes.

Parámetro Tipo Descripción Obligatorio
identityType cadena Especifica el valor de cadena b2b. Yes
identityValue cadena Clave de identificador de Microsoft Store que representa la identidad del usuario para el que desea consultar productos. Sí
localTicketReference string El identificador solicitado para los productos devueltos. Los artículos devueltos en el cuerpo de la respuesta tendrán un parámetro localTicketReference coincidente. Se recomienda usar el mismo valor que la notificación userId en la clave de identificador de Microsoft Store. Yes

El objeto ProductSkuId contiene los parámetros siguientes.

Parámetro Tipo Descripción Obligatorio
productId string Identificador de la Tienda de un producto en el catálogo de Microsoft Store. Un ejemplo de id. de la Tienda para un producto es 9NBLGGH42CFD. Sí
skuId cadena Identificador de la Tienda para la SKU de un producto en el catálogo de Microsoft Store. Un identificador de la Tienda de ejemplo para una SKU es 0010. Sí

Ejemplo de solicitud

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

Response

Response body

Parámetro Tipo Descripción Obligatorio
continuationToken cadena Si hay varios conjuntos de productos, este token se devuelve cuando se alcanza el límite de la página. Puedes especificar este token de continuación en llamadas posteriores para recuperar los productos restantes. No
items CollectionItemContractV6 Matriz de productos para el usuario especificado. Para obtener más información, consulte la tabla siguiente. No

El objeto CollectionItemContractV6 contiene los parámetros siguientes.

Parámetro Tipo Descripción Obligatorio
acquiredDate datetime Fecha en que el usuario compró el artículo. Sí
campaignId cadena Identificador de campaña que se proporcionó al realizar la compra del artículo. No
devOfferId cadena El identificador de la oferta de una compra desde la aplicación. No
endDate datetime La fecha de finalización del artículo. Sí
fulfillmentData cadena de lista<> N/D No
inAppOfferToken string Cadena de identificador de producto especificada por el desarrollador que se asigna al elemento en el Centro de partners. Un identificador de producto de ejemplo es product123. No
itemId string Id. que identifica este artículo de colección de otros artículos que posee el usuario. Este identificador es único para cada producto. Sí
localTicketReference cadena Identificador del localTicketReference proporcionado anteriormente en el cuerpo de la solicitud. Sí
modifiedDate datetime Fecha de la última modificación de este artículo. Yes
orderId cadena Si está presente, el identificador del objeto del que se obtuvo este artículo. No
orderLineItemId string Si está presente, el artículo de línea de un pedido concreto para el que se obtuvo el artículo. No
ownershipType string Cadena OwnedByBeneficiary. Yes
productId string Identificador de la Tienda del producto en el catálogo de Microsoft Store. Un ejemplo de id. de la Tienda para un producto es 9NBLGGH42CFD. Sí
productType cadena Uno de los siguientes tipos de producto: Application, Durable y UnmanagedConsumable. Yes
purchasedCountry string N/D No
purchaser IdentityContractV6 Si está presente, representa la identidad del comprador del artículo. Consulta los detalles de este objeto a continuación. No
quantity number Cantidad del artículo. Actualmente, el valor siempre será 1. No
skuId string Identificador de la Tienda para la SKU del producto en el catálogo de Microsoft Store. Un id. de tienda de ejemplo para una SKU es 0010. Yes
skuType cadena Tipo de la SKU. Entre los valores posibles se incluyen Trial, Full y Rental. Sí
startDate datetime Fecha en que el artículo comienza a ser válido. Yes
status string Estado del elemento. Entre los valores posibles se incluyen Active, Expired, Revoked y Banned. Yes
etiquetas cadena de lista<> N/D Sí
transactionId guid El identificador de transacción como resultado de la compra de este artículo. Se puede usar para notificar la cumplimentación de un artículo. Sí

El objeto IdentityContractV6 contiene los parámetros siguientes.

Parámetro Tipo Descripción Obligatorio
identityType cadena Contiene el valor pub. Sí
identityValue string Valor de cadena del publisherUserId de la clave de identificador de Microsoft Store especificada. Sí

Ejemplo de respuesta

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