Gerenciar direitos de produto a partir de um serviço

Se você tiver um catálogo de aplicativos e complementos, poderá usar a API de coleção Microsoft Store e a API de compra Microsoft Store para acessar informações de direitos para esses produtos a partir dos seus serviços. Um direito representa o direito do cliente de usar um aplicativo ou complemento publicado por meio da Microsoft Store.

Essas APIs consistem em métodos REST projetados para serem usados por desenvolvedores com catálogos de complementos compatíveis com serviços multiplataforma. Essas APIs permitem que você faça o seguinte:

• API de coleção da Microsoft Store: Consultar produtos de um usuário e relatar o cumprimento de um produto consumível como atendido.
• API de compra da Microsoft Store: conceder um produto gratuito a um usuário, obter assinaturas de um usuário, e alterar o estado de cobrança de uma assinatura para um usuário.

Nota

A API de coleção da Microsoft Store e a API de compra usam a autenticação da Plataforma de Identidade da Microsoft (Entra ID) para acessar as informações de propriedade do cliente. Para usar essas APIs, você (ou sua organização) deve ter um locatário do Entra ID e deve ter permissão de Administrador global para o locatário. Se você já usa o Microsoft 365 ou outros serviços empresariais da Microsoft, já tem um tenant do Entra ID.

A biblioteca Microsoft.StoreServices

Para ajudar a simplificar o fluxo de autenticação e chamar os Serviços da Microsoft Store, examine o projeto Microsoft.StoreServices e o exemplo no Github. A biblioteca Microsoft.StoreServices ajudará a gerenciar as chaves de autenticação e fornecerá API de wrapper para chamar os Serviços da Microsoft Store para gerenciar produtos. O projeto de exemplo destaca como um serviço pode usar a biblioteca Microsoft.StoreServices, lógica de exemplo para gerenciar produtos consumíveis, reconciliar compras reembolsadas, renovar credenciais expiradas e muito mais. Um guia de configuração passo a passo é incluído com o exemplo para configurar o serviço de exemplo em seu computador ou por meio do Azure.

• Biblioteca Microsoft.StoreServices (GitHub)
• Exemplo de Microsoft.StoreServices (GitHub)

Visão geral

As etapas a seguir descrevem o processo de ponta a ponta para usar a API de coleção da Microsoft Store e a API de compra:

1. Configure um aplicativo no Entra ID.
2. Associe o ID do aplicativo Entra ID ao seu aplicativo no Partner Center.
3. Em seu serviço, crie tokens de acesso ao Entra ID que representam sua identidade de editor.
4. Em seu aplicativo cliente Windows, crie uma chave de ID da Microsoft Store que representa a identidade do usuário atual e, depois, passe essa chave de volta para seu serviço.

Esse processo de ponta a ponta envolve dois componentes de software que executam tarefas diferentes:

• Seu serviço. Este é um aplicativo que é executado com segurança no contexto do seu ambiente de negócios e pode ser implementado usando qualquer plataforma de desenvolvimento escolhida. Seu serviço é responsável por criar os tokens de acesso do Entra ID necessários para o cenário e invocar as URIs REST para a API de coleção da Microsoft Store e a API de compra.
• Seu aplicativo cliente do Windows. Este é o aplicativo para o qual você deseja acessar e gerenciar informações de direitos do cliente (incluindo complementos para o aplicativo). Este aplicativo é responsável por criar as chaves de ID da Microsoft Store que você precisa para chamar a API de coleção da Microsoft Store e a API de compras do seu serviço.

Etapa 1: Configurar um aplicativo na ID do Entra

Antes de usar a API de coleção da Microsoft Store ou a API de compra, você deve criar um aplicativo Web da ID do Entra, recuperar a ID do locatário e a ID do aplicativo e gerar uma chave. O aplicativo Web Entra ID representa o serviço a partir do qual você deseja chamar a API de coleção da Microsoft Store ou a API de compra. Você precisa do ID do locatário, do ID do aplicativo e da chave para gerar tokens de acesso ao Entra ID necessários para chamar a API.

1. Se você ainda não fez isso, siga as instruções no Início Rápido do : registre um aplicativo na plataforma de identidade da Microsoft para registrar um aplicativo Web /aplicativo de API com a ID do Entra.

   Nota

   Ao registrar seu aplicativo, você deve escolher aplicativo Web / de API como o tipo de aplicativo, para que você possa obter uma chave (também chamada de segredo do cliente ) para seu aplicativo. Para chamar a API de coleção da Microsoft Store ou a API de compra, você deve fornecer um segredo de cliente ao solicitar um token de acesso do Entra ID em uma etapa posterior.

2. No Portal de Gerenciamento do Azure, navegue até o Microsoft Entra ID. Selecione seu locatário, clique em Registros de aplicativo no painel de navegação esquerdo em Gerenciar e selecione seu aplicativo.

3. Você será levado para a página de registro principal do aplicativo. Nesta página, copie o valor do ID do Aplicativo para uso posterior.

4. Crie uma chave que você precisará mais tarde (isso tudo é chamado de segredo de cliente ). No painel esquerdo, clique em Configurações e em Chaves. Nesta página, conclua as etapas para criar uma chave. Copie essa chave para uso posterior.

Etapa 2: Associar a ID do aplicativo Entra ID ao aplicativo cliente no Partner Center

Antes de usar a API de coleção da Microsoft Store ou a API de compra para configurar a propriedade e as compras para seu aplicativo ou complemento, você deve associar sua ID do aplicativo Entra ao aplicativo (ou ao aplicativo que contém o complemento) no Partner Center.

Nota

Você só precisa executar essa tarefa uma vez. Depois de ter a ID do locatário, a ID do aplicativo e o segredo do cliente, você poderá reutilizar esses valores sempre que precisar criar um novo token de acesso à ID do Entra.

1. Entre no do Partner Center e selecione seu aplicativo.
2. Vá para a página Serviços>Coleções e compras de produtos e insira o ID do aplicativo Entra em um dos campos ID do Cliente disponíveis.

Etapa 3: Criar tokens de acesso à ID do Entra

Antes de recuperar uma chave de ID da Microsoft Store ou chamar a API de coleção ou a API de compra da Microsoft Store, seu serviço deve criar diferentes tokens de acesso do Entra ID que representem a identidade do editor. Cada token será usado com uma API diferente. O tempo de vida de cada token é de 60 minutos e você pode atualizá-los depois que eles expirarem.

Importante

Crie tokens de acesso à ID do Entra apenas no contexto do serviço, não no seu aplicativo. O segredo do cliente poderá ser comprometido se for enviado para seu aplicativo.

Noções básicas sobre os diferentes tokens e URIs de audiência

Dependendo de quais métodos você deseja chamar na API de coleção da Microsoft Store ou na API de compra, você deve criar dois ou três tokens diferentes. Cada token de acesso é associado a um URI de público diferente.

• Em todos os casos, você deve criar um token com o URI de público https://onestore.microsoft.com. Em uma etapa posterior, você passará esse token para o cabeçalho Autorização de métodos na API de coleção da Microsoft Store ou na API de compra.

  Importante

  Use o público https://onestore.microsoft.com somente com tokens de acesso armazenados com segurança em seu serviço. Expor tokens de acesso para esse público fora do seu serviço pode tornar seu serviço vulnerável a ataques de repetição.

• Se quiser chamar um método na API de coleção da Microsoft Store para consultar produtos pertencentes a um usuário ou informar um produto consumível como atendido, você também deverá criar um token com o URI de público https://onestore.microsoft.com/b2b/keys/create/collections. Em uma etapa posterior, você passará esse token para um método cliente no SDK do Windows para solicitar uma chave de ID da Microsoft Store que possa ser usada com a API de coleção da Microsoft Store.

• Se você quiser chamar um método na API de compra da Microsoft Store para conceder um produto gratuito a umde usuário, obter assinaturas para umde usuário ou alterar o estado de cobrança de uma assinatura para um usuário, você também deve criar um token com o URI de público https://onestore.microsoft.com/b2b/keys/create/purchase. Em uma etapa posterior, você passará esse token para um método cliente no SDK do Windows para solicitar uma chave de ID da Microsoft Store que possa ser usada com a API de compra da Microsoft Store.

Criar os tokens

Para criar os tokens de acesso, use a API OAuth 2.0 em seu serviço seguindo as instruções em Chamadas de serviço para serviço utilizando credenciais de cliente, para enviar um HTTP POST ao ponto de extremidade https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está uma solicitação de exemplo.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://onestore.microsoft.com

Para cada token, especifique os seguintes dados de parâmetro:

• Para os parâmetros client_id e client_secret, especifique a ID do aplicativo e o segredo do cliente para seu aplicativo que você recuperou do Portal de Gerenciamento do Azure. Ambos os parâmetros são necessários para criar um token de acesso com o nível de autenticação exigido pela API de coleção da Microsoft Store ou a API de compra.

• Para o parâmetro de recurso, especifique um dos URIs de público listados na seção anterior, dependendo do tipo de token de acesso que você está criando.

Depois que o token de acesso expirar, você poderá atualizá-lo seguindo as instruções aqui. Para obter mais detalhes sobre a estrutura de um token de acesso, consulte Tipos de token e declaração com suporte.

Etapa 4: Criar uma chave de ID da Microsoft Store

Antes de chamar qualquer método na API de coleção da Microsoft Store ou na API de compras, seu aplicativo deve criar uma chave de ID da Microsoft Store e enviá-la ao seu serviço. Essa chave é um JWT (Token Web JSON) que representa a identidade do usuário cujas informações de propriedade do produto você deseja acessar. Para obter mais informações sobre as afirmações nessa chave, consulte Afirmações em uma chave de ID da Microsoft Store.

Atualmente, a única maneira de criar uma chave de ID da Microsoft Store é chamando uma API da Plataforma Universal do Windows (UWP) do código do cliente em seu aplicativo. A chave gerada representa a identidade do usuário que está atualmente conectado à Microsoft Store no dispositivo.

Nota

Cada chave de ID da Microsoft Store é válida por 30 dias. Antes que a chave expire, você pode renovar a chave. Recomendamos que você renove suas chaves de ID da Microsoft Store em vez de criar novas.

Para criar uma chave de ID da Microsoft Store para a API de coleção da Microsoft Store

Siga estas etapas para criar uma chave de ID da Microsoft Store que você pode usar com a API de coleção da Microsoft Store para consultar produtos pertencentes a um usuário ou indicar que um produto consumível foi consumido.

1. Passe o token de acesso do Entra ID, que possui a URI de público https://onestore.microsoft.com/b2b/keys/create/collections, do seu serviço para o seu aplicativo cliente. Esse é um dos tokens que você criou anteriormente na etapa 3.

2. No código do aplicativo, chame um destes métodos para recuperar uma chave de ID da Microsoft Store:

• Se o aplicativo usar a classe StoreContext no namespace Windows.Services.Store para gerenciar compras no aplicativo, use o método StoreContext.GetCustomerCollectionsIdAsync.

• Se o aplicativo usar a classe CurrentApp no namespace Windows.ApplicationModel.Store para gerenciar compras no aplicativo, use o método CurrentApp.GetCustomerCollectionsIdAsync.

  Passe o token de acesso do Entra ID para o parâmetro serviceTicket do método. Se você mantiver registros de IDs de usuários anônimos no contexto de serviços que você gerencia na função de editor do aplicativo atual, também poderá passar uma ID de usuário para o parâmetro publisherUserId para associar o usuário atual à nova chave de ID da Microsoft Store (a ID do usuário será incorporada à chave). Caso contrário, se você não precisar associar uma ID de usuário à chave de ID da Microsoft Store, poderá passar qualquer valor de cadeia de caracteres para o parâmetro publisherUserId.

3. Depois que o aplicativo criar com êxito uma chave de ID da Microsoft Store, passe a chave de volta para seu serviço.

Para criar uma chave de ID da Microsoft Store para a API de compra da Microsoft Store

Siga estas etapas para criar uma chave de ID da Microsoft Store que você pode usar com a API de compra da Microsoft Store para conceder um produto gratuito a um usuário, obter assinaturas para umde usuário ou alterar o estado de cobrança de uma assinatura para um usuário.

1. Passe o token de acesso do Entra ID, que possui a URI de público https://onestore.microsoft.com/b2b/keys/create/purchase, do seu serviço para o seu aplicativo cliente. Esse é um dos tokens que você criou anteriormente na etapa 3.

2. No código do aplicativo, chame um destes métodos para recuperar uma chave de ID da Microsoft Store:

• Se o aplicativo usar a classe StoreContext no namespace Windows.Services.Store para gerenciar compras no aplicativo, use o método StoreContext.GetCustomerPurchaseIdAsync.

• Se o aplicativo usar a classe CurrentApp no namespace Windows.ApplicationModel.Store para gerenciar compras no aplicativo, use o método CurrentApp.GetCustomerPurchaseIdAsync.

  Passe o token de acesso do Entra ID para o parâmetro serviceTicket do método. Se você mantiver IDs de usuários anônimos no contexto de serviços que você gerencia como o publicador do aplicativo atual, também poderá passar uma ID de usuário para o parâmetro publisherUserId para associar o usuário atual à nova chave de ID da Microsoft Store (a ID do usuário será incorporada na chave). Caso contrário, se você não precisar associar uma ID de usuário à chave de ID da Microsoft Store, poderá passar qualquer valor de cadeia de caracteres para o parâmetro publisherUserId.

3. Depois que o aplicativo criar com êxito uma chave de ID da Microsoft Store, passe a chave de volta para seu serviço.

Diagrama

O diagrama a seguir ilustra o processo de criação de uma chave de ID da Microsoft Store.

Declarações em uma chave de ID da Microsoft Store

Uma chave de ID da Microsoft Store é um JWT (Token Web JSON) que representa a identidade do usuário cujas informações de propriedade do produto você deseja acessar. Quando decodificada usando Base64, uma chave de ID da Microsoft Store contém as declarações a seguir.

• iat: identifica o momento em que a chave foi emitida. Essa declaração pode ser usada para determinar a idade do token. Esse valor é expresso como hora da época.
• iss: identifica o emissor. Isso tem o mesmo valor que a declaração aud.
• aud: identifica o público-alvo. Deve ser um dos seguintes valores: https://collections.mp.microsoft.com/v6.0/keys ou https://purchase.mp.microsoft.com/v6.0/keys.
• exp: identifica o tempo de expiração em ou após o qual a chave não será mais aceita para processar nada, exceto para renovar chaves. O valor dessa declaração é expresso como hora da época.
• nbf: identifica o momento em que o token será aceito para processamento. O valor dessa declaração é expresso como hora da época.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: a ID do cliente que identifica o desenvolvedor.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: uma carga opaca (criptografada e codificada em Base64) que contém informações destinadas apenas para uso pelos serviços da Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: uma ID de usuário que identifica o usuário atual no contexto de seus serviços. Esse é o mesmo valor que você passa para o parâmetro publisherUserId opcional do método usado para criar a chave.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: o URI que você pode usar para renovar a chave.

Aqui está um exemplo de um cabeçalho de chave de ID da Microsoft Store decodificado.

{
    "typ":"JWT",
    "alg":"RS256",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

Aqui está um exemplo de um conjunto de declarações de chave de ID da Microsoft Store decodificada.

{
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d5773695a3b44928227393bfef1e13d",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "ZdcOq0/N2rjytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQMLaYCrgtC0d/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
    "iat": 1733526889,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1733523289,
    "nbf": 1736118889
}

Tópicos relacionados

• Consulta de produtos
• Declarar produtos consumíveis como providenciados
• Conceder produtos gratuitos
• Obter assinaturas para um usuário
• Alterar o estado de cobrança de uma assinatura para um usuário
• Renovar uma chave de ID da Microsoft Store
• integração de aplicativos com a plataforma de identidade da Microsoft
• Tokens de ID na plataforma de identidade da Microsoft
• Biblioteca Microsoft.StoreServices (GitHub)