Gerenciar direitos de produtos de um serviço

Se você tiver um catálogo de aplicativos e complementos, poderá usar o da API de coleta da Microsoft Store e da API de compra da Microsoft Store para acessar as informações de direitos desses produtos a partir de seus serviços. Um direito representa o direito de um cliente de usar um aplicativo ou complemento publicado na Microsoft Store.

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

• API de coleção da Microsoft Store: Consultar os produtos possuídos por um utilizador e relatar um produto consumível como cumprido.
• API de compra da Microsoft Store: Conceder um produto gratuito a um usuário, obter assinaturas para um usuárioe alterar o estado de cobrança de uma assinatura para um usuário.

Observação

A API de coleta da Microsoft Store e a API de compra usam a autenticação da plataforma de identidade da Microsoft (Entra ID) para acessar 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 de administrador global para o locatário. Se já utiliza o Microsoft 365 ou outros serviços empresariais da Microsoft, já tem um inquilino 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 fornece APIs 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, conciliar compras reembolsadas, renovar credenciais expiradas e muito mais. Um guia de configuração passo a passo está incluído com o exemplo para configurar o serviço de exemplo no seu PC ou através do Azure.

• biblioteca Microsoft.StoreServices (GitHub)
• Exemplo Microsoft.StoreServices (GitHub)

Visão geral

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

1. Configure um aplicativo no Entra ID.
2. Associe seu ID de aplicativo Entra ID ao seu aplicativo no Partner Center.
3. No seu serviço, cria tokens de acesso ao Entra ID que representam a sua identidade como editor.
4. Na sua aplicação cliente do Windows, crie uma chave de ID da Microsoft Store que represente a identidade do utilizador atual e passe essa chave de volta para o seu serviço.

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

• O 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 que você escolher. O seu serviço é responsável por criar os tokens de acesso Entra ID necessários para o cenário e por chamar os 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). Esta aplicação é responsável por criar as chaves de ID da Microsoft Store que necessita para chamar a API de coleção da Microsoft Store e a API de compras do seu serviço.

Etapa 1: Configurar um aplicativo no Entra ID

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

1. Se ainda não o fez, siga as instruções em Guia de início rápido: registar uma aplicação com a plataforma de identidade da Microsoft para registar uma aplicação Web e API com o Entra ID.

   Observação

   Ao registar a sua aplicação, deve escolher aplicação Web / API como o tipo de aplicação para que possa recuperar uma chave (também chamada de cliente secreto) para a sua aplicação. Para chamar a API de coleta da Microsoft Store ou a API de compra, você deve fornecer um segredo do cliente quando solicitar um token de acesso do Entra ID em uma etapa posterior.

2. Nodo Portal de Gerenciamento do Azure , navegue até ID do Microsoft Entra. Selecione o seu inquilino, clique em Registos de aplicações no painel de navegação esquerdo em Gerir e, em seguida, selecione a sua aplicação.

3. Você é levado para a página principal de registro do aplicativo. Nesta página, copie o valor ID da aplicação para uso posterior.

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

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

Antes de poder usar a API de coleta da Microsoft Store ou a API de compra para configurar a propriedade e as compras do 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.

Observação

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

1. Inicie sessão no Partner Center e selecione a sua aplicação.
2. Vá para a página de Serviços coleções e compras de produtos e insira o seu ID da aplicação Entra em um dos campos de ID do Cliente disponíveis.

Etapa 3: Criar tokens de acesso ao Entra ID

Antes de poder recuperar uma chave de ID da Microsoft Store ou chamar as APIs de coleção ou de compra da Microsoft Store, o seu serviço deve criar vários tokens de acesso de ID do Entra, que representem a identidade do seu 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 do Entra ID apenas no contexto do seu serviço, não no seu aplicativo. O segredo do cliente pode ser comprometido se for enviado para o seu aplicativo.

Entendendo os diferentes tokens e URIs de audiência

Dependendo dos métodos que 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 audiência https://onestore.microsoft.com. Em uma etapa posterior, você passará esse token para o cabeçalho Authorization de métodos na API de coleta 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 com esse público fora do seu serviço pode tornar seu serviço vulnerável a ataques de repetição.

• Se pretender chamar um método na API de coleção da Microsoft Store para consultar produtos de propriedade de um utilizador ou assinalar um produto consumível como concluído, deve também criar um token com o URI de audiência https://onestore.microsoft.com/b2b/keys/create/collections. Em uma etapa posterior, você passará esse token para um método de cliente no SDK do Windows para solicitar uma chave de ID da Microsoft Store que você pode usar com a API de coleta da Microsoft Store.

• Se você quiser chamar um método na API de compra da Microsoft Store para conceder um produto gratuito a um usuário, obter assinaturas para um usuárioou 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 de cliente no SDK do Windows para solicitar uma chave de ID da Microsoft Store que você pode usar com a API de compra da Microsoft Store.

Crie os tokens

Para criar os tokens de acesso, use a API OAuth 2.0 no seu serviço seguindo as instruções em Service to Service Calls Using Client Credentials para enviar um HTTP POST ao endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está um pedido de amostra.

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 coleta da Microsoft Store ou pela API de compra.

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

Depois que seu 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 Supported Token and Claim Types.

Etapa 4: Criar uma chave de ID da Microsoft Store

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

Observação

Cada chave de ID da Microsoft Store é válida por 30 dias. Antes que a chave expire, você pode renová-la. 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 coleta da Microsoft Store para consulta de produtos de propriedade de um usuário ou relatar um produto consumível como cumprido.

1. Passe o token de acesso Entra ID que tem o valor de URI de audiência https://onestore.microsoft.com/b2b/keys/create/collections do seu serviço para o seu aplicativo cliente. Este é um dos tokens que você criou anteriormente na etapa 3.

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

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

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

  Passe o seu token de acesso do Entra ID para o parâmetro serviceTicket do método. Se você mantiver IDs de usuário anônimos no contexto dos serviços que gerencia como 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 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 seu aplicativo criar com êxito uma chave de ID da Microsoft Store, passe a chave de volta para o 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 um usuárioou alterar o estado de cobrança de uma assinatura para um usuário.

1. Passe o token de acesso Entra ID que tem o valor de URI de audiência https://onestore.microsoft.com/b2b/keys/create/purchase do seu serviço para o seu aplicativo cliente. Este é um dos tokens que você criou anteriormente na etapa 3.

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

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

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

  Passe o seu token de acesso do Entra ID para o parâmetro serviceTicket do método. Se você mantiver IDs de usuário anônimos no contexto dos serviços que gerencia como 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 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 seu aplicativo criar com êxito uma chave de ID da Microsoft Store, passe a chave de volta para o 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 JSON Web Token (JWT) 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 seguintes declarações.

• iat: Identifica o momento em que a chave foi emitida. Esta declaração pode ser usada para determinar a idade do token. Este valor é expresso como tempo de época.
• iss: Identifica o emitente. Isto tem o mesmo valor que a reivindicação aud.
• aud: Identifica o público. 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 no qual ou após o qual a chave não será mais aceita para processamento de nada, exceto para renovar chaves. O valor desta reivindicação é expresso como tempo de época.
• nbf: Identifica o momento em que o token será aceito para processamento. O valor desta reivindicação é expresso como tempo de época.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: O 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 ao uso pelos serviços da Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: Um 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 opcional publisherUserId 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 decodificado.

{
    "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
• Comunicar produtos consumíveis como cumpridos
• Conceda produtos gratuitos
• Obter subscrições para um utilizador
• Alterar o estado de faturação de uma subscrição para um utilizador
• 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)