Share via

Declarar produtos consumíveis como providenciados

  • Artigo

Use esse método na API da coleção da Microsoft Store para declarar um produto consumível como providenciado para um determinado cliente. Para que um usuário possa recomprar um produto consumível, seu aplicativo ou serviço deve declarar que o produto consumível já foi providenciado para esse usuário.

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

  • Forneça a ID do item do produto consumível (conforme retornado no parâmetro itemId de uma consulta por produtos) e uma ID de rastreamento exclusivo que você forneça. Se a mesma ID de rastreamento for usada em várias tentativas, o mesmo resultado será retornado mesmo se o item já tiver sido consumido. Se você não tiver certeza se uma solicitação de produto consumível foi bem-sucedida, o serviço deve reenviar as solicitações de produto consumível com a mesma ID de rastreamento. A ID de rastreamento sempre será vinculada a essa solicitação de produto consumível e poderá ser reenviada indefinidamente.
  • Forneça a ID do produto (como retornado no parâmetro productId de uma consulta por produtos) e uma ID de transação que é 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 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 para o qual você quer declarar um produto consumível como providenciado.

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

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
beneficiary 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 por produtos. Use esse parâmetro com trackingId Não
trackingId guid Uma ID de rastreamento exclusiva fornecida pelo desenvolvedor. Use esse parâmetro com itemId. Não
productId string O valor de productId retornado por uma consulta por produtos. Use esse parâmetro com transactionId Não
transactionId guid Um valor de ID de transação que é obtido de uma das seguintes fonte. Use esse parâmetro com productId. 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 Uma chave ID da Microsoft Store que representa a identidade do usuário para o qual você quer declarar um produto consumível como providenciado. Sim
localTicketReference string O identificador solicitado para resposta retornada. Recomendamos que você use o mesmo valor do que a declaraçãouserId na chave 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 for executado com êxito.

Exemplo de resposta

HTTP/1.1 204 No Content
Content-Length: 0
MS-CorrelationId: 386f733d-bc66-4bf9-9b6f-a1ad417f97f0
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 do 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 de ServiceError irão conter mais informações, como quando o token está expirado ou falta a declaração appid.
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 InconsistentClientId 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 coincidem.