Productrechten van een service beheren

Als u een catalogus met apps en invoegtoepassingen hebt, kunt u de Microsoft Store-verzameling-API en de Microsoft Store-aankoop-API gebruiken om toegang te krijgen tot toegangsrechteninformatie voor deze producten vanuit uw services. Een recht vertegenwoordigt het recht van een klant om een app of invoegtoepassing te gebruiken die is gepubliceerd via de Microsoft Store.

Deze API's bestaan uit REST-methoden die zijn ontworpen voor gebruik door ontwikkelaars met invoegtoepassingscatalogussen die worden ondersteund door platformoverschrijdende services. Met deze API's kunt u het volgende doen:

• Microsoft Store-verzamelings-API: Opvragen van producten die eigendom zijn van een gebruiker en een verbruiksproduct rapporteren als voltooid.
• Microsoft Store-aankoop-API: een gratis product verlenen aan een gebruiker, abonnementen voor een gebruiker krijgenen de factureringsstatus van een abonnement voor een gebruikerwijzigen.

Notitie

De Microsoft Store-verzamelings-API en aankoop-API maken gebruik van de Verificatie van het Microsoft Identity Platform (Entra ID) voor toegang tot eigendomsgegevens van klanten. Als u deze API's wilt gebruiken, moet u (of uw organisatie) een Entra ID-tenant hebben en moet u globale beheerder machtiging voor de tenant hebben. Als u Al Microsoft 365 of andere zakelijke services van Microsoft gebruikt, hebt u al een Entra ID-tenant.

De bibliotheek Microsoft.StoreServices

Bekijk het project Microsoft.StoreServices en het voorbeeld op Github om de verificatiestroom te stroomlijnen en de Microsoft Store Services-services aan te roepen. De bibliotheek Microsoft.StoreServices helpt bij het beheren van de verificatiesleutels en biedt wrapper-API's om de Microsoft Store-services aan te roepen voor het beheren van producten. In het voorbeeldproject wordt uitgelegd hoe een service de Bibliotheek Microsoft.StoreServices kan gebruiken, bijvoorbeeld logica voor het beheren van verbruiksproducten, het afstemmen van terugbetaalde aankopen, het verlengen van verlopen referenties en meer. Een stapsgewijze configuratiehandleiding is opgenomen in het voorbeeld voor het instellen van de voorbeeldservice op uw pc of via Azure.

• Microsoft.StoreServices-bibliotheek (GitHub)
• Microsoft.StoreServices Sample (GitHub)

Overzicht

In de volgende stappen wordt het end-to-end-proces beschreven voor het gebruik van de Microsoft Store-verzamelings-API en aankoop-API:

1. een toepassing configureren in Entra ID.
2. Koppel de toepassings-id van uw Entra ID aan uw app in Partner Centrum.
3. In uw service entra-id-toegangstokens maken die uw uitgeversidentiteit vertegenwoordigen.
4. Maak in de Windows-client-app een Microsoft Store-id-sleutel die de identiteit van de huidige gebruiker vertegenwoordigt en geef deze sleutel weer door aan uw service.

Dit end-to-end proces omvat twee softwareonderdelen die verschillende taken uitvoeren:

• Uw service. Dit is een toepassing die veilig wordt uitgevoerd in de context van uw bedrijfsomgeving en kan worden geïmplementeerd met elk ontwikkelplatform dat u kiest. Uw service is verantwoordelijk voor het maken van de Entra ID-toegangstokens die nodig zijn voor het scenario en voor het aanroepen van de REST-URI's voor de Microsoft Store-verzameling-API en aankoop-API.
• Uw Windows-client-app. Dit is de app waarvoor u toegang wilt hebben tot en beheer wilt voeren over klantrechtinformatie (inclusief uitbreidingen). Deze app is verantwoordelijk voor het maken van de Microsoft Store ID-sleutels die u nodig hebt om de Microsoft Store-collectie-API aan te roepen en de aankoop-API vanuit uw dienst gebruiken.

Stap 1: Een toepassing configureren in Entra-id

Voordat u de Microsoft Store-verzamelings-API of aankoop-API kunt gebruiken, moet u een Entra ID-webtoepassing maken, de tenant-id en toepassings-id voor de toepassing ophalen en een sleutel genereren. De Entra ID-webtoepassing vertegenwoordigt de service waaruit u de Microsoft Store-verzamelings-API of aankoop-API wilt aanroepen. U hebt de tenant-id, toepassings-id en sleutel nodig om Entra ID-toegangstokens te genereren die u nodig hebt om de API aan te roepen.

1. Als u dit nog niet hebt gedaan, volgt u de instructies in Quickstart: Een toepassing registreren bij het Microsoft Identity Platform om een web-app/API--toepassing te registreren met Entra-id.

   Notitie

   Wanneer u uw toepassing registreert, moet u web-app/API- als toepassingstype kiezen, zodat u een sleutel (ook wel een clientgeheimgenoemd) voor uw toepassing kunt ophalen. Als u de Microsoft Store-verzamelings-API of aankoop-API wilt aanroepen, moet u een clientgeheim opgeven wanneer u in een latere stap een toegangstoken aanvraagt bij entra-id.

2. Ga in de Azure beheerportalnaar Microsoft Entra ID. Selecteer uw tenant, klik op App-registraties in het linkernavigatiedeelvenster onder Beheren en selecteer vervolgens uw toepassing.

3. U gaat naar de hoofdregistratiepagina van de toepassing. Kopieer op deze pagina de toepassings-id waarde voor later gebruik.

4. Maak een sleutel die u later nodig hebt (dit wordt allemaal een clientgeheimgenoemd). Klik in het linkerdeelvenster op Instellingen en Sleutels. Voer op deze pagina de stappen uit om een sleutel te maken. Kopieer deze sleutel voor later gebruik.

Stap 2: Koppel uw Entra ID-toepassings-ID aan uw klantenapp in Partner Center

Voordat u de Microsoft Store-verzamelings-API of aankoop-API kunt gebruiken om het eigendom en de aankopen voor uw app of invoegtoepassing te configureren, moet u uw Entra-toepassings-id koppelen aan de app (of de app die de invoegtoepassing bevat) in partnercentrum.

Notitie

U hoeft deze taak slechts één keer uit te voeren. Nadat u uw tenant-id, toepassings-id en clientgeheim hebt, kunt u deze waarden telkens opnieuw gebruiken wanneer u een nieuw Entra ID-toegangstoken moet maken.

1. Meld u aan bij Partnercentrum en selecteer uw app.
2. Ga naar de Services>Productverzamelingen en aankopen pagina en voer uw Entra-toepassings-id in een van de beschikbare velden client-id in.

Stap 3: Entra ID-toegangstokens maken

Voordat u een Microsoft Store-id-sleutel kunt ophalen of de Microsoft Store-verzamelings-API of aankoop-API kunt aanroepen, moet uw service verschillende Entra ID-toegangstokens maken die uw uitgeversidentiteit vertegenwoordigen. Elk token wordt gebruikt met een andere API. De levensduur van elk token is 60 minuten en u kunt ze vernieuwen nadat ze zijn verlopen.

Belangrijk

Maak alleen entra-id-toegangstokens in de context van uw service, niet in uw app. Uw clientgeheim kan worden aangetast als het naar uw app wordt verzonden.

Inzicht in de verschillende tokens en doelgroep-URI's

Afhankelijk van de methoden die u wilt aanroepen in de Microsoft Store-verzamelings-API of aankoop-API, moet u twee of drie verschillende tokens maken. Elk toegangstoken is gekoppeld aan een andere doelgroep-URI.

• In alle gevallen moet u een token maken met de https://onestore.microsoft.com audience-URI. In een latere stap geeft u dit token door aan de Authorization header van methoden in de Microsoft Store-verzamelings-API of aankoop-API.

  Belangrijk

  Gebruik de https://onestore.microsoft.com doelgroep alleen met toegangstokens die veilig in uw service worden opgeslagen. Als u toegangstokens beschikbaar maakt voor deze doelgroep buiten uw service, kan uw service kwetsbaar zijn voor het opnieuw afspelen van aanvallen.

• Als u een methode in de Microsoft Store-verzamelings-API wilt aanroepen om producten op te vragen die eigendom zijn van een gebruiker of een verbruiksproduct als voldaan te rapporteren, moet u ook een token maken met de https://onestore.microsoft.com/b2b/keys/create/collections audience-URI. In een latere stap geeft u dit token door aan een clientmethode in de Windows SDK om een Microsoft Store-id-sleutel aan te vragen die u kunt gebruiken met de Microsoft Store-verzamelings-API.

• Als u een methode in de Microsoft Store-aankoop-API wilt aanroepen om een gratis product toe te kennen aan een gebruiker, abonnementen voor een gebruikerof de factureringsstatus van een abonnement voor een gebruikerwijzigen, moet u ook een token maken met de https://onestore.microsoft.com/b2b/keys/create/purchase doelgroep-URI. In een latere stap geeft u dit token door aan een clientmethode in de Windows SDK om een Microsoft Store-id-sleutel aan te vragen die u kunt gebruiken met de Microsoft Store-aankoop-API.

De tokens maken

Als u de toegangstokens wilt maken, gebruikt u de OAuth 2.0-API in uw service door de instructies in Service to Service-aanroepen te volgen met behulp van clientreferenties een HTTP POST naar het https://login.microsoftonline.com/<tenant_id>/oauth2/token-eindpunt te verzenden. Hier volgt een voorbeeldaanvraag.

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

Geef voor elk token de volgende parametergegevens op:

• Geef voor de parameters client_id en client_secret de toepassings-id en het clientgeheim op voor uw toepassing die u hebt opgehaald uit de Azure Management Portal-. Beide parameters zijn vereist om een toegangstoken te maken met het verificatieniveau dat is vereist voor de Microsoft Store-verzamelings-API of aankoop-API.

• Geef voor de resourceparameter een van de doelgroep-URI's op die worden vermeld in de vorige sectie, afhankelijk van het type toegangstoken dat u maakt.

Nadat uw toegangstoken is verlopen, kunt u het vernieuwen door de instructies hierte volgen. Zie Ondersteunde token- en claimtypenvoor meer informatie over de structuur van een toegangstoken.

Stap 4: Een Microsoft Store-id-sleutel maken

Voordat u een methode in de Microsoft Store-verzamelings-API of aankoop-API kunt aanroepen, moet uw app een Microsoft Store-id-sleutel maken en naar uw service verzenden. Deze sleutel is een JSON Web Token (JWT) dat de identiteit vertegenwoordigt van de gebruiker van wie u de producteigendomsgegevens wilt openen. Voor meer informatie over de claims in deze sleutel, zie Claims in een Microsoft Store-id-sleutel.

Momenteel is de enige manier om een Microsoft Store-id-sleutel te maken door een UWP-API (Universal Windows Platform) aan te roepen op basis van clientcode in uw app. De gegenereerde sleutel vertegenwoordigt de identiteit van de gebruiker die momenteel is aangemeld bij de Microsoft Store op het apparaat.

Notitie

Elke Microsoft Store-id-sleutel is 30 dagen geldig. Voordat de sleutel verloopt, kunt u de sleutelvernieuwen. U wordt aangeraden uw Microsoft Store-id-sleutels te vernieuwen in plaats van nieuwe sleutels te maken.

Een Microsoft Store-id-sleutel voor de Microsoft Store-verzamelings-API maken

Volg deze stappen om een Microsoft Store-id-sleutel te maken die u met de Microsoft Store-verzamelings-API kunt gebruiken om producten op te vragen die eigendom zijn van een gebruiker of een verbruiksproduct te rapporteren als vervuld.

1. Geef het Entra ID-toegangstoken, dat de URI-waarde https://onestore.microsoft.com/b2b/keys/create/collections als doelgroep heeft, door van uw service naar uw client-app. Dit is een van de tokens die u eerder in stap 3hebt gemaakt .

2. Roep in uw app-code een van deze methoden aan om een Microsoft Store-id-sleutel op te halen:

• Als uw app gebruikmaakt van de klasse StoreContext in de Windows.Services.Store-naamruimte voor het beheren van aankopen in apps, gebruikt u de methode StoreContext.GetCustomerCollectionsIdA sync.

• Als uw app gebruikmaakt van de klasse CurrentApp in de Windows.ApplicationModel.Store-naamruimte voor het beheren van aankopen in apps, gebruikt u de methode CurrentApp.GetCustomerCollectionsIdA sync.

  Geef uw Entra ID-toegangstoken door aan de serviceTicket-parameter van de methode. Als u anonieme gebruikers-id's onderhoudt in de context van services die u beheert als uitgever van de huidige app, kunt u ook een gebruikers-id doorgeven aan de parameter publisherUserId om de huidige gebruiker te koppelen aan de nieuwe Microsoft Store-id-sleutel (de gebruikers-id wordt ingesloten in de sleutel). Als u anders geen gebruikers-id aan de Microsoft Store-id-sleutel hoeft te koppelen, kunt u elke tekenreekswaarde doorgeven aan de parameter publisherUserId.

3. Nadat uw app een Microsoft Store-id-sleutel heeft gemaakt, geeft u de sleutel weer door aan uw service.

Een Microsoft Store-id-sleutel maken voor de Microsoft Store-aankoop-API

Volg deze stappen om een Microsoft Store-id-sleutel te maken die u kunt gebruiken met de Microsoft Store-aankoop-API om een gratis product te verlenen aan een gebruiker, abonnementen voor een gebruikerop te halen of de factureringsstatus van een abonnement voor een gebruikerwijzigen.

1. Geef het Entra ID-toegangstoken met de doelgroep-URI-waarde https://onestore.microsoft.com/b2b/keys/create/purchase vanuit uw service door naar uw clientapplicatie. Dit is een van de tokens die u eerder in stap 3hebt gemaakt .

2. Roep in uw app-code een van deze methoden aan om een Microsoft Store-id-sleutel op te halen:

• Als uw app gebruikmaakt van de klasse StoreContext in de Windows.Services.Store-naamruimte voor het beheren van aankopen in apps, gebruikt u de methode StoreContext.GetCustomerPurchaseIdAsync.

• Als uw app gebruikmaakt van de klasse CurrentApp in de Windows.ApplicationModel.Store-naamruimte voor het beheren van aankopen in apps, gebruikt u de CurrentApp.GetCustomerPurchaseIdAsync-methode.

  Geef uw Entra ID-toegangstoken door aan de serviceTicket-parameter van de methode. Als u anonieme gebruikers-id's onderhoudt in de context van services die u beheert als uitgever van de huidige app, kunt u ook een gebruikers-id doorgeven aan de parameter publisherUserId om de huidige gebruiker te koppelen aan de nieuwe Microsoft Store-id-sleutel (de gebruikers-id wordt ingesloten in de sleutel). Als u anders geen gebruikers-id aan de Microsoft Store-id-sleutel hoeft te koppelen, kunt u elke tekenreekswaarde doorgeven aan de parameter publisherUserId.

3. Nadat uw app een Microsoft Store-id-sleutel heeft gemaakt, geeft u de sleutel weer door aan uw service.

Diagram

In het volgende diagram ziet u het proces voor het maken van een Microsoft Store-id-sleutel.

Claims in een Microsoft Store-identificatiesleutel

Een Microsoft Store-id-sleutel is een JSON-webtoken (JWT) dat de identiteit vertegenwoordigt van de gebruiker waarvan u de producteigendomsgegevens wilt openen. Wanneer de code wordt gedecodeerd met Base64, bevat een Microsoft Store-id-sleutel de volgende claims.

• iat: Geeft het tijdstip aan waarop de sleutel is uitgegeven. Deze claim kan worden gebruikt om de leeftijd van het token te bepalen. Deze waarde wordt uitgedrukt als epoch-tijd.
• iss: identificeert de verlener. Dit heeft dezelfde waarde als de aud claim.
• aud: Identificeert de doelgroep. Moet een van de volgende waarden zijn: https://collections.mp.microsoft.com/v6.0/keys of https://purchase.mp.microsoft.com/v6.0/keys.
• exp: geeft de verlooptijd aan of waarna de sleutel niet meer wordt geaccepteerd voor het verwerken van iets behalve voor het vernieuwen van sleutels. De waarde van deze claim wordt uitgedrukt als epoche-tijd.
• nbf: Geeft het tijdstip aan waarop het token wordt geaccepteerd voor verwerking. De waarde van deze claim wordt uitgedrukt als tijdsduur.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: de client-id waarmee de ontwikkelaar wordt geïdentificeerd.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: een ondoorzichtige nettolading (versleuteld en Base64 gecodeerd) die informatie bevat die alleen bedoeld is voor gebruik door Microsoft Store-services.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: een gebruikers-id die de huidige gebruiker identificeert in de context van uw services. Dit is dezelfde waarde die u doorgeeft aan de optionele parameter publisherUserId van de methode die u gebruikt om de sleutelte maken.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: de URI die u kunt gebruiken om de sleutel te vernieuwen.

Hier volgt een voorbeeld van een gedecodeerde Microsoft Store ID-sleutelheader.

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

Hier volgt een voorbeeld van een gedecodeerde Microsoft Store ID-sleutelclaimset.

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

Verwante onderwerpen

• Query uitvoeren voor producten
• verbruiksproducten rapporteren zoals voldaan
• gratis producten weggeven
• Abonnementen voor een gebruiker ophalen
• de factureringsstatus van een abonnement voor een gebruiker wijzigen
• een Microsoft Store-id-sleutel vernieuwen
• Toepassingen integreren met het Microsoft Identity Platform
• ID-tokens in het Microsoft Identiteitsplatform
• Microsoft.StoreServices-bibliotheek (GitHub)