Gestire i diritti dei prodotti attraverso un servizio

Se disponi di un catalogo di app e componenti aggiuntivi, puoi usare l'API di raccolta di Microsoft Store e l'API di acquisto di Microsoft Store per accedere alle informazioni sui diritti di utilizzo per questi prodotti dai tuoi servizi. Un' autorizzazione rappresenta il diritto di un cliente di usare un'app o un componente aggiuntivo pubblicato tramite Microsoft Store.

Queste API sono costituite da metodi REST progettati per essere usati dagli sviluppatori con cataloghi di componenti aggiuntivi supportati da servizi multipiattaforma. Queste API consentono di eseguire le operazioni seguenti:

• API di raccolta di Microsoft Store: Query per i prodotti di proprietà di un utente e segnalare un prodotto di consumo come completato.
• API di acquisto di Microsoft Store: Concedere un prodotto gratuito a un utente, ottenere sottoscrizioni per un utentee modificare lo stato di fatturazione di una sottoscrizione per un utente.

Nota

L'API di raccolta e l'API di acquisto di Microsoft Store usano l'autenticazione di Microsoft Identity Platform (Entra ID) per accedere alle informazioni sulla proprietà dei clienti. Per usare queste API, l'utente (o l'organizzazione) deve disporre di un tenant Entra ID ed è necessario disporre dell'autorizzazione amministratore globale per il tenant. Se si usa già Microsoft 365 o altri servizi aziendali di Microsoft, si dispone già del tenant Entra ID.

Libreria Microsoft.StoreServices

Per aiutare a semplificare il flusso di autenticazione e l'accesso ai servizi di Microsoft Store, esaminare il progetto Microsoft.StoreServices e un esempio su Github. La libreria Microsoft.StoreServices consente di gestire le chiavi di autenticazione e fornisce l'API wrapper per chiamare i servizi di Microsoft Store per la gestione dei prodotti. Il progetto di esempio illustra come un servizio può usare la libreria Microsoft.StoreServices, ad esempio la logica per la gestione dei prodotti di consumo, la riconciliazione degli acquisti rimborsati, il rinnovo delle credenziali scadute e altro ancora. Una guida dettagliata alla configurazione è inclusa nell'esempio per configurare il servizio di esempio nel PC o tramite Azure.

• libreria Microsoft.StoreServices (GitHub)
• Esempio di Microsoft.StoreServices (GitHub)

Panoramica

I passaggi seguenti descrivono il processo end-to-end per l'uso dell'API di raccolta e dell'API di acquisto di Microsoft Store:

1. Configurare un'applicazione in Entra ID.
2. Associa l'ID dell'applicazione di Entra ID alla tua app nel Partner Center.
3. Nel tuo servizio, crea token di accesso Entra ID che rappresentano l'identità dell'editore.
4. Nell'app Windows client, creare una chiave ID di Microsoft Store che rappresenta l'identità dell'utente corrente e restituire questa chiave al servizio.

Questo processo end-to-end prevede due componenti software che eseguono attività diverse:

• Il servizio. Si tratta di un'applicazione che viene eseguita in modo sicuro nel contesto dell'ambiente aziendale e può essere implementata usando qualsiasi piattaforma di sviluppo scelta. Il tuo servizio è responsabile della creazione dei token di accesso Entra ID necessari per lo scenario e per invocare gli URI REST per l'API di raccolta e l'API di acquisto di Microsoft Store.
• L'app client di Windows. Questa è l'app per cui vuoi accedere e gestire le informazioni sui diritti dei clienti (inclusi i componenti aggiuntivi per l'app). Questa app è responsabile della creazione delle chiavi ID di Microsoft Store necessarie per chiamare l'API di raccolta di Microsoft Store e l'API di acquisto dal tuo servizio.

Passaggio 1: Configurare un'applicazione in Entra ID

Prima di poter usare l'API di raccolta o di acquisto di Microsoft Store, è necessario creare un'applicazione Web Entra ID, recuperare l'ID tenant e l'ID applicazione per l'applicazione e generare una chiave. L'applicazione Web Entra ID rappresenta il servizio da cui vuoi chiamare l'API di raccolta o l'API di acquisto di Microsoft Store. Sono necessari l'ID tenant, l'ID applicazione e la chiave per generare i token di accesso di Entra ID necessari per chiamare l'API.

1. Se non è già stato fatto, seguire le istruzioni riportate in Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform per registrare un'app Web /API'applicazione con Entra ID.

   Nota

   Quando registri l'applicazione, è necessario scegliere app Web/ API come tipo di applicazione in modo da poter recuperare una chiave (denominata anche segreto del client) per l'applicazione. Per chiamare l'API di raccolta o l'API di acquisto di Microsoft Store, devi fornire un segreto client quando richiedi un token di accesso dall'ID Entra in un passaggio successivo.

2. Nel portale di gestione di Azure , naviga fino a Microsoft Entra ID. Seleziona il tuo tenant, fai clic su Registrazioni app nel riquadro di navigazione a sinistra sotto Gestione e quindi seleziona la tua applicazione.

3. Viene visualizzata la pagina di registrazione principale dell'applicazione. In questa pagina, copiare il valore dell'applicazione ID per usarlo in un secondo momento.

4. Creare una chiave che sarà necessaria in un secondo momento (viene chiamato un segreto client ). Nel riquadro a sinistra, fare clic su Impostazioni e quindi su Chiavi. In questa pagina completare i passaggi per creare una chiave. Copiare questa chiave per usarla in un secondo momento.

Passaggio 2: Associare l'ID dell'applicazione Entra ID all'app client nel Centro partners

Prima di poter usare l'API di raccolta o di acquisto di Microsoft Store per configurare la proprietà e gli acquisti per l'app o il componente aggiuntivo, devi associare l'ID applicazione Entra all'app (o all'app che contiene il componente aggiuntivo) nel Centro per i partner.

Nota

È sufficiente eseguire questa attività una sola volta. Dopo aver ottenuto l'ID tenant, l'ID applicazione e il segreto client, è possibile riutilizzare questi valori ogni volta che è necessario creare un nuovo token di accesso Entra ID.

1. Accedi al Centro per i partner di e seleziona la tua app.
2. Vai alla pagina Services>Raccolte di prodotti e acquisti ed inserisci l'ID applicazione Entra in uno dei campi disponibili ID cliente.

Passaggio 3: Creare token di accesso con ID Entra

Prima di poter recuperare una chiave ID di Microsoft Store o chiamare l'API di raccolta o di acquisto di Microsoft Store, il servizio deve creare diversi token di accesso Entra ID che rappresentano l'identità dell'editore. Ogni token verrà usato con un'API diversa. La durata di ogni token è di 60 minuti ed è possibile aggiornarli dopo la scadenza.

Importante

Crea token di accesso Entra ID solo nel contesto del tuo servizio, non nella tua app. Il segreto del client potrebbe essere compromesso se viene inviato alla tua app.

Informazioni sui diversi token e URI del gruppo di destinatari

A seconda dei metodi che vuoi chiamare nell'API di raccolta o nell'API di acquisto di Microsoft Store, devi creare due o tre token diversi. Ogni token di accesso è associato a un URI del gruppo di destinatari diverso.

• In tutti i casi, è necessario creare un token con l'URI del gruppo di destinatari https://onestore.microsoft.com. In un passaggio successivo, questo token verrà passato all'intestazione di autorizzazione dei metodi nell'API di raccolta del Microsoft Store o nell'API di acquisto.

  Importante

  Usare il gruppo di destinatari https://onestore.microsoft.com solo con token di accesso archiviati in modo sicuro all'interno del servizio. L'esposizione di token di accesso con questo gruppo di destinatari all'esterno del servizio potrebbe rendere il servizio vulnerabile agli attacchi di riproduzione.

• Se vuoi chiamare un metodo nell'API di raccolta di Microsoft Store per eseguire una query sui prodotti di proprietà di un utente o segnalare un prodotto di consumo come, devi anche creare un token con l'URI del gruppo di destinatari https://onestore.microsoft.com/b2b/keys/create/collections. In un passaggio successivo questo token verrà passato a un metodo client in Windows SDK per richiedere una chiave ID di Microsoft Store che è possibile usare con l'API di raccolta di Microsoft Store.

• Se vuoi chiamare un metodo nell'API di acquisto di Microsoft Store per concedere un prodotto gratuito a un utente, ottenere sottoscrizioni per un utenteo modificare lo stato di fatturazione di una sottoscrizione per un utente, devi anche creare un token con l'URI del gruppo di destinatari https://onestore.microsoft.com/b2b/keys/create/purchase. In un passaggio successivo, passerai questo token a un metodo client in Windows SDK per richiedere una chiave ID di Microsoft Store che puoi usare con l'API di acquisto di Microsoft Store.

Creare i token

Per creare i token di accesso, usare l'API OAuth 2.0 nel servizio seguendo le istruzioni riportate in Service to Service Calls Using Client Credentials per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Ecco una richiesta di esempio.

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

Per ogni token, specificare i dati dei parametri seguenti:

• Per i parametri client_id e client_secret, specificare l'ID applicazione e il segreto client per l'applicazione recuperati dal portale di gestione di Azure . Entrambi questi parametri sono necessari per creare un token di accesso con il livello di autenticazione richiesto dall'API di raccolta di Microsoft Store o dall'API di acquisto.

• Per il parametro della risorsa , specificare uno degli URI del gruppo di destinatari elencati nella sezione precedente, a seconda del tipo di token di accesso che si sta creando.

Dopo la scadenza del token di accesso, è possibile aggiornarlo seguendo le istruzioni qui. Per altre informazioni sulla struttura di un token di accesso, vedere Token e tipi di attestazione supportati.

Passaggio 4: Creare una chiave ID di Microsoft Store

Prima di poter chiamare qualsiasi metodo nell'API di raccolta o nell'API di acquisto di Microsoft Store, l'app deve creare una chiave ID di Microsoft Store e inviarla al servizio. Questa chiave è un token JSON Web (JWT) che rappresenta l'identità dell'utente di cui si vogliono ottenere le informazioni sulla proprietà del prodotto. Per altre informazioni sulle attestazioni in questa chiave, vedere Attestazioni in una chiave ID di Microsoft Store.

Attualmente, l'unico modo per creare una chiave ID di Microsoft Store consiste nel chiamare un'API UWP (Universal Windows Platform) dal codice client nella tua app. La chiave generata rappresenta l'identità dell'utente attualmente connesso a Microsoft Store nel dispositivo.

Nota

Ogni chiave ID di Microsoft Store è valida per 30 giorni. Prima della scadenza della chiave, è possibile rinnovare la chiave. Ti consigliamo di rinnovare le chiavi ID di Microsoft Store invece di crearne di nuove.

Per creare una chiave ID di Microsoft Store per l'API delle raccolte di Microsoft Store

Segui questi passaggi per creare una chiave ID Microsoft Store da usare con l'API di raccolta di Microsoft Store per eseguire query sui prodotti che un utente possiede o segnalare un prodotto di consumo come evaso.

1. Passa il token di accesso Entra ID con il valore URI dell'audience https://onestore.microsoft.com/b2b/keys/create/collections dal tuo servizio alla tua app client. Si tratta di uno dei token creati in precedenza nel passaggio 3.

2. Nel codice dell'app chiamare uno di questi metodi per recuperare una chiave ID di Microsoft Store:

• Se l'app usa la classe StoreContext nello spazio dei nomi Windows.Services.Store per gestire gli acquisti in-app, usa il metodo StoreContext.GetCustomerCollectionsIdAsync.

• Se l'app usa la classe CurrentApp nello spazio dei nomi Windows.ApplicationModel.Store per gestire gli acquisti in-app, usa il metodo CurrentApp.GetCustomerCollectionsIdAsync.

  Passa il token di accesso Entra ID al parametro serviceTicket del metodo. Se si mantengono ID utente anonimi nel contesto dei servizi che gestite in qualità di publisher dell'app corrente, è possibile anche passare un ID utente al parametro publisherUserId per associare l'utente attuale alla nuova chiave ID di Microsoft Store (l'ID utente sarà incorporato nella chiave). In caso contrario, se non è necessario associare un ID utente alla chiave ID di Microsoft Store, è possibile passare qualsiasi valore stringa al parametro publisherUserId.

3. Dopo che l'app ha creato correttamente una chiave ID di Microsoft Store, restituire la chiave al servizio.

Per creare una chiave ID di Microsoft Store per l'API di acquisto di Microsoft Store

Seguire questa procedura per creare una chiave ID di Microsoft Store che è possibile usare con l'API di acquisto di Microsoft Store per concedere un prodotto gratuito a un utente, ottenere sottoscrizioni per un utenteo modificare lo stato di fatturazione di una sottoscrizione per un utente.

1. Passare il token di accesso Entra ID con il valore dell'audience URI https://onestore.microsoft.com/b2b/keys/create/purchase dal tuo servizio alla tua app client. Si tratta di uno dei token creati precedentemente nel passaggio 3.

2. Nel codice dell'app chiamare uno di questi metodi per recuperare una chiave ID di Microsoft Store:

• Se la tua app usa la classe storeContext nello spazio dei nomi Windows.Services.Store per gestire gli acquisti in-app, usa il metodo StoreContext.GetCustomerPurchaseIdAsync.

• Se l'app usa la classe CurrentApp nello spazio dei nomi Windows.ApplicationModel.Store per gestire gli acquisti in-app, usa il metodo CurrentApp.GetCustomerPurchaseIdAsync.

  Passare il token di accesso dell'ID Entra al parametro serviceTicket del metodo . Se mantieni ID utente anonimi nel contesto dei servizi che gestisci in qualità di autore dell'app corrente, è possibile anche passare un ID utente al parametro publisherUserId per associare l'utente corrente alla nuova chiave ID di Microsoft Store (l'ID utente verrà incorporato nella chiave). In caso contrario, se non è necessario associare un ID utente alla chiave ID di Microsoft Store, è possibile passare qualsiasi valore stringa al parametro publisherUserId.

3. Una volta che l'app ha creato correttamente una chiave ID di Microsoft Store, inviare la chiave al servizio.

Diagramma

Il diagramma seguente illustra il processo di creazione di una chiave ID di Microsoft Store.

Attestazioni in una chiave ID di Microsoft Store

Una chiave ID di Microsoft Store è un token JSON Web (JWT) che rappresenta l'identità dell'utente delle cui informazioni sulla proprietà del prodotto si vogliono accedere. Se decodificato con Base64, una chiave ID di Microsoft Store contiene le attestazioni seguenti.

• iat: identifica l'ora di emissione della chiave. Questa attestazione può essere usata per determinare l'età del token. Questo valore viene espresso come periodo temporale.
• iss: identifica l'emittente. Questo ha lo stesso valore dell'attestazione aud.
• aud: identifica il gruppo di destinatari. Deve essere uno dei valori seguenti: https://collections.mp.microsoft.com/v6.0/keys o https://purchase.mp.microsoft.com/v6.0/keys.
• exp: identifica l'ora di scadenza in o dopo la quale la chiave non verrà più accettata per l'elaborazione di alcun elemento, ad eccezione del rinnovo delle chiavi. Il valore di questa attestazione viene espresso come periodo temporale.
• nbf: identifica l'ora in cui il token verrà accettato per l'elaborazione. Il valore di questa attestazione viene espresso come periodo temporale.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: ID client che identifica lo sviluppatore.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: payload opaco (crittografato e con codifica Base64) che contiene informazioni destinate solo all'uso da parte dei servizi di Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: Un ID utente che identifica l'utente corrente nel contesto dei tuoi servizi. Si tratta dello stesso valore passato al parametro facoltativo publisherUserId del metodo usato per creare la chiave.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: URI che è possibile usare per rinnovare la chiave.

Di seguito è riportato un esempio di intestazione di chiave ID di Microsoft Store decodificata.

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

Ecco un esempio di set di attestazioni di chiave ID di Microsoft Store decodificate.

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

Argomenti correlati

• query per i prodotti
• Segnalare i prodotti di consumo come soddisfatti
• Concedere prodotti gratuiti
• Acquisire abbonamenti per un utente
• Modificare lo stato di fatturazione di una sottoscrizione per un utente
• Rinnovare una chiave ID di Microsoft Store
• Integrazione di applicazioni con Microsoft Identity Platform
• Token ID in Microsoft Identity Platform
• libreria Microsoft.StoreServices (GitHub)