Partilhar via

Declarar produtos consumíveis como providenciados

  • Artigo

Use esse método na API de coleção da Microsoft Store para relatar um produto consumível como atendido para um determinado cliente. Antes que um usuário possa comprar novamente um produto consumível, seu aplicativo ou serviço deve informar o produto consumível como processado para esse usuário.

Há duas maneiras de usar esse método para relatar um produto consumível como processado:

  • Forneça a ID do item do consumível (conforme retornado no parâmetro itemId de uma consulta para produtos) e uma ID de rastreamento exclusiva que você fornece. Se o mesmo ID de rastreamento for usado para várias tentativas, o mesmo resultado será retornado mesmo que o item já tenha sido consumido. Se você não tiver certeza se uma solicitação de consumo foi bem-sucedida, seu serviço deverá reenviar solicitações de consumo com o mesmo ID de rastreamento. O ID de rastreamento sempre estará vinculado a essa solicitação de consumo e poderá ser reenviado indefinidamente.
  • Forneça a ID do produto (conforme retornado no parâmetro productId de uma consulta para produtos) e uma ID de transação obtida de uma das fontes listadas na descrição do parâmetro transactionId na seção do corpo da solicitação abaixo.

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

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 para o qual você deseja relatar um produto consumível como processado.

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/consume

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ário UserIdentity O usuário para o qual este item está sendo consumido. Para obter mais informações, confira a tabela a seguir. Sim
itemId string O valor itemId retornado por uma consulta para produtos. Use este parâmetro com trackingId Não
trackingId guid Um ID de rastreamento exclusivo fornecido pelo desenvolvedor. Use esse parâmetro com itemId. Não
productId string O valor productId retornado por uma consulta para produtos. Use este parâmetro com transactionId Não
transactionId guid Um valor de ID de transação obtido de uma das seguintes fontes. Use esse parâmetro com productId. 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 relatar um produto consumível como atendido. Sim
localTicketReference string O identificador solicitado para a resposta retornada. Recomendamos que você use o mesmo valor que a declaração userIdna chave de ID da Microsoft Store. Sim

Exemplos de solicitação

O exemplo a seguir usa itemId e trackingId.

POST https://collections.mp.microsoft.com/v6.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1…..
Host: collections.mp.microsoft.com
Content-Length: 2050
Content-Type: application/json

{
    "beneficiary": {
        "localTicketReference": "testreference",
        "identityValue": "eyJ0eXAiOi…..",
        "identityType": "b2b"
    },
    "itemId": "44c26106-4979-457b-af34-609ae97a084f",
    "trackingId": "44db79ca-e31d-49e9-8896-fa5c7f892b40"
}

O exemplo a seguir usa productId e transactionId.

POST https://collections.mp.microsoft.com/v6.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1……
Content-Length: 1880
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue" : "eyJ0eXAiOiJ…..",
        "identitytype" : "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "transactionId" : "08a14c7c-1892-49fc-9135-190ca4f10490"
}

Resposta

Nenhum conteúdo será retornado se o consumo tiver sido executado com êxito.

Exemplo de resposta

HTTP/1.1 204 No Content
Content-Length: 0
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: e488cd0a-9fb6-4c2c-bb77-e5100d3c15b1
MS-CV: 5.1
MS-ServerId: 030011326
Date: Tue, 22 Sep 2015 20:40:55 GMT

Códigos do Erro

Código Erro Código de erro interno Descrição
401 Não Autorizado AuthenticationTokenInvalid O token de acesso do Azure AD é inválido. Em alguns casos, os detalhes do ServiceError conterão mais informações, como quando o token expirou ou a declaração appid está ausente.
401 Não Autorizado PartnerAadTicketRequired Um token de acesso do Azure AD não foi passado para o serviço no cabeçalho de autorização.
401 Não Autorizado InconsistenteClientId A declaração clientId na chave de ID da Microsoft Store no corpo da solicitação e a declaração appid no token de acesso do Azure AD no cabeçalho de autorização não correspondem.