Hantera produkträttigheter från en tjänst

Om du har en katalog med appar och tillägg kan du använda api:et för Microsoft Store-samling och Köp-API för Microsoft Store för att få åtkomst till berättigandeinformation för dessa produkter från dina tjänster. Ett berättigande representerar en kunds rätt att använda en app eller ett tillägg som publiceras via Microsoft Store.

Dessa API:er består av REST-metoder som är utformade för att användas av utvecklare med tilläggskataloger som stöds av plattformsoberoende tjänster. Med dessa API:er kan du göra följande:

• Microsoft Store-samlings-API: Fråga efter produkter som ägs av en användare och rapportera en förbrukningsprodukt som uppfyller.
• Köp-API för Microsoft Store: Bevilja en kostnadsfri produkt till en användareskaffa prenumerationer för en användareoch ändra faktureringstillståndet för en prenumeration för en användare.

Notera

Microsoft Store-samlings-API:et och inköps-API:et använder Microsofts identitetsplattformsautentisering (Entra ID) för att få åtkomst till information om kundägarskap. Om du vill använda dessa API:er måste du (eller din organisation) ha en Entra-ID-klientorganisation och du måste ha global administratör behörighet för klientorganisationen. Om du redan använder Microsoft 365 eller andra företagstjänster från Microsoft har du redan Entra ID-klientorganisation.

Microsoft.StoreServices-biblioteket

För att förbättra autentiseringsflödet och anropa Microsoft Store Services, gå igenom projektet Microsoft.StoreServices och exempelkoden på Github. Microsoft.StoreServices-biblioteket hjälper dig att hantera autentiseringsnycklarna och tillhandahåller omslutnings-API:er för att anropa Microsoft Store Services för att hantera produkter. Exempelprojektet visar hur en tjänst kan använda biblioteket Microsoft.StoreServices, till exempel logik för att hantera förbrukningsprodukter, förena återbetalningar av inköp, förnya utgångna autentiseringsuppgifter med mera. En stegvis konfigurationsguide ingår i exemplet för att konfigurera exempeltjänsten på datorn eller via Azure.

• Microsoft.StoreServices-biblioteket (GitHub)
• Exempel på Microsoft.StoreServices (GitHub)

Överblick

Följande steg beskriver processen från slutpunkt till slutpunkt för användning av Microsoft Store-samlings-API:et och inköps-API:et:

1. Konfigurera ett program i Entra ID.
2. Associera ditt Entra ID-program-ID med din app i Partnercenter.
3. I din tjänst skapa Entra ID-åtkomsttoken som representerar din utgivaridentitet.
4. I din Windows-klientapp skapa en Microsoft Store-ID-nyckel som representerar den aktuella användarens identitet och skicka tillbaka nyckeln till din tjänst.

Den här processen från slutpunkt till slutpunkt omfattar två programvarukomponenter som utför olika uppgifter:

• Din tjänst. Det här är ett program som körs på ett säkert sätt i samband med din affärsmiljö och som kan implementeras med valfri utvecklingsplattform. Din tjänst ansvarar för att skapa entra-ID-åtkomsttoken som behövs för scenariot och för att anropa REST-URI:erna för Microsoft Store-samlings-API:et och inköps-API:et.
• Windows-klientappen. Det här är den app som du vill komma åt och hantera information om kundrättigheter för (inklusive tillägg för appen). Den här appen ansvarar för att skapa de Microsoft Store-ID-nycklar som du behöver för att anropa Microsoft Store-samlings-API:et och köpa API från din tjänst.

Steg 1: Konfigurera ett program i Entra-ID

Innan du kan använda Microsoft Store-samlings-API:et eller inköps-API:et måste du skapa ett Webbprogram för Entra-ID, hämta klientorganisations-ID:t och program-ID:t för programmet och generera en nyckel. Webbprogrammet För Entra-ID representerar den tjänst som du vill anropa Microsoft Store-samlings-API:et från eller köpa API:et. Du behöver klientorganisations-ID, program-ID och nyckel för att generera Entra ID-åtkomsttoken som du behöver för att anropa API:et.

1. Om du inte redan har gjort det följer du anvisningarna i Snabbstart: Registrera ett program med Microsofts identitetsplattform för att registrera en webbapp/API-program med Entra-ID.

   Not

   När du registrerar ditt program måste du välja webbapp/API som programtyp så att du kan hämta en nyckel (kallas även klienthemlighet) för ditt program. För att kunna anropa Microsoft Store-samlings-API:et eller inköps-API:et måste du ange en klienthemlighet när du begär en åtkomsttoken från Etttra-ID i ett senare steg.

2. I Azure Management Portalnavigerar du till Microsoft Entra ID. Välj din klientorganisation, klicka på Appregistreringar i det vänstra navigeringsfönstret under Hantera och välj sedan ditt program.

3. Du tas till programmets huvudregistreringssida. På den här sidan kopierar du värdet program-ID för senare användning.

4. Skapa en nyckel som du behöver senare (allt detta kallas för en klienthemlighet). I den vänstra rutan klickar du på Inställningar och sedan Tangenter. På den här sidan slutför du stegen för att skapa en nyckel. Kopiera den här nyckeln för senare användning.

Steg 2: Associera ditt Entra ID-program-ID med din klientapp i Partnercenter

Innan du kan använda Microsoft Store-samlings-API:et eller köp-API:et för att konfigurera ägarskap och inköp för din app eller ditt tillägg måste du associera ditt Entra-program-ID med appen (eller appen som innehåller tillägget) i Partnercenter.

Anteckning

Du behöver bara utföra den här uppgiften en gång. När du har ditt klient-ID, program-ID och klienthemlighet kan du återanvända dessa värden när du behöver skapa en ny Åtkomsttoken för Entra-ID.

1. Logga in på Partnercenter och välj din app.
2. Gå till sidan Tjänster>Produktsamlingar och inköp och ange ditt Entra-program-ID i något av de tillgängliga fälten för Klient-ID.

Steg 3: Skapa Entra ID-åtkomsttoken

Innan du kan hämta en Microsoft Store-ID-nyckel eller anropa API:et för Microsoft Store-samlingen eller köpa API måste tjänsten skapa flera olika Åtkomsttoken för Entra-ID som representerar din utgivaridentitet. Varje token används med ett annat API. Livslängden för varje token är 60 minuter och du kan uppdatera dem när de har upphört att gälla.

Viktig

Skapa åtkomsttoken för Entra-ID endast i kontexten för din tjänst, inte i din app. Din klienthemlighet kan komprometteras om den skickas till din app.

Förstå skillnaderna mellan token och målgrupps-URIer

Beroende på vilka metoder du vill anropa i Microsoft Store-samlings-API:et eller inköps-API:et måste du skapa två eller tre olika token. Varje åtkomsttoken är associerad med en annan målgrupps-URI.

• I samtliga fall måste du skapa en token med https://onestore.microsoft.com målgrupps-URI. I ett senare steg skickar du denna token till Authorization-huvudet för metoder i Microsoft Store-samlings-API:et eller inköps-API:et.

  Viktig

  Använd endast https://onestore.microsoft.com-målgruppen med åtkomsttoken som lagras säkert i din tjänst. Att exponera åtkomsttoken med den här målgruppen utanför din tjänst kan göra tjänsten sårbar för reprisattacker.

• Om du vill anropa en metod i Microsoft Store-samlings-API:et för att fråga efter produkter som ägs av en användare eller rapportera en förbrukningsbar produkt enligtmåste du också skapa en token med https://onestore.microsoft.com/b2b/keys/create/collections målgrupps-URI. I ett senare steg skickar du den här token till en klientmetod i Windows SDK för att begära en Microsoft Store-ID-nyckel som du kan använda med Microsoft Store-samlings-API:et.

• Om du vill anropa en metod i Microsoft Store-inköps-API:et för att bevilja en kostnadsfri produkt till en användare, skaffa prenumerationer för en användareeller ändra faktureringstillståndet för en prenumeration för en användaremåste du också skapa en token med https://onestore.microsoft.com/b2b/keys/create/purchase målgrupps-URI. I ett senare steg skickar du denna token till en klientmetod i Windows SDK för att begära en Microsoft Store-ID-nyckel som du kan använda med Köp-API:et för Microsoft Store.

Skapa token

Om du vill skapa åtkomsttoken använder du OAuth 2.0 API i din tjänst genom att följa anvisningarna i Service to Service Calls Using Client Credentials för att skicka en HTTP POST till slutpunkten https://login.microsoftonline.com/<tenant_id>/oauth2/token. Här är en exempelbegäran.

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

För varje token anger du följande parameterdata:

• För parametrarna client_id och client_secret anger du program-ID och klienthemlighet för ditt program som du hämtade från Azure Management Portal. Båda dessa parametrar krävs för att skapa en åtkomsttoken med den autentiseringsnivå som krävs av Microsoft Store-samlings-API:et eller inköps-API:et.

• För parametern resurs anger du en av målgrupps-URI:erna som anges i föregående avsnitt, beroende på vilken typ av åtkomsttoken du skapar.

När din åtkomsttoken har upphört att gälla kan du uppdatera den genom att följa anvisningarna här. Mer information om strukturen för en åtkomsttoken finns i Stödda token- och anspråkstyper.

Steg 4: Skapa en Microsoft Store-ID-nyckel

Innan du kan anropa någon metod i Microsoft Store-samlings-API:et eller köpa API måste din app skapa en Microsoft Store-ID-nyckel och skicka den till din tjänst. Den här nyckeln är en JSON-webbtoken (JWT) som representerar identiteten för den användare vars information om produktägarskap som du vill komma åt. Mer information om anspråk i en Microsoft Store-ID-nyckel finner du i Anspråk i en Microsoft Store-ID-nyckel.

För närvarande är det enda sättet att skapa en Microsoft Store-ID-nyckel genom att anropa ett UWP-API (Universal Windows Platform) från klientkoden i din app. Den genererade nyckeln representerar identiteten för den användare som för närvarande är inloggad i Microsoft Store på enheten.

Not

Varje Microsoft Store-ID-nyckel är giltig i 30 dagar. Innan nyckeln upphör att gälla kan du förnya nyckeln. Vi rekommenderar att du förnyar dina Microsoft Store-ID-nycklar i stället för att skapa nya.

Så här skapar du en Microsoft Store-ID-nyckel för Microsoft Store-samlings-API:et

Följ de här stegen för att skapa en Microsoft Store-ID-nyckel som du kan använda med Microsoft Store-samlings-API:et för att fråga efter produkter som ägs av en användare eller rapportera en förbrukningsprodukt som uppfylld.

1. Skicka Entra ID-åtkomsttoken som har målgruppens URI-värde https://onestore.microsoft.com/b2b/keys/create/collections från din tjänst till klientappen. Det här är en av de tokens som du skapade tidigare i steg 3.

2. I din appkod anropar du någon av dessa metoder för att hämta en Microsoft Store-ID-nyckel:

• Om din app använder klassen StoreContext i Windows.Services.Store-namnområdet för att hantera köp i appen använder du metoden StoreContext.GetCustomerCollectionsIdAsync.

• Om din app använder klassen CurrentApp i Windows.ApplicationModel.Store-namnområdet för att hantera köp i appen använder du metoden CurrentApp.GetCustomerCollectionsIdAsync.

  Skicka din Entra ID-åtkomsttoken till parametern serviceTicket för den metoden. Om du behåller anonyma användar-ID:n i kontexten för tjänster som du hanterar som utgivare av den aktuella appen kan du även skicka ett användar-ID till parametern publisherUserId för att associera den aktuella användaren med den nya Microsoft Store-ID-nyckeln (användar-ID:t bäddas in i nyckeln). Om du inte behöver associera ett användar-ID med Microsoft Store-ID-nyckeln kan du skicka valfritt strängvärde till parametern publisherUserId.

3. När appen har skapat en Microsoft Store-ID-nyckel skickar du tillbaka nyckeln till tjänsten.

Så här skapar du en Microsoft Store-ID-nyckel för Köp-API:et för Microsoft Store

Följ dessa steg för att skapa en Microsoft Store-ID-nyckel som du kan använda med Köp-API:et för Microsoft Store för att bevilja en kostnadsfri produkt till en användare, hämta prenumerationer för en användareeller ändra faktureringstillståndet för en prenumeration för en användare.

1. Skicka Entra ID-åtkomsttoken som har målgruppens URI-värde https://onestore.microsoft.com/b2b/keys/create/purchase från din tjänst till klientappen. Det här är ett av de tokens som du skapade tidigare i steg 3.

2. I din appkod anropar du någon av dessa metoder för att hämta en Microsoft Store-ID-nyckel:

• Om din app använder klassen StoreContext i Windows.Services.Store-namnområdet för att hantera köp i appen använder du metoden StoreContext.GetCustomerPurchaseIdAsync.

• Om din app använder klassen CurrentApp i Windows.ApplicationModel.Store-namnområdet för att hantera köp i appen använder du metoden CurrentApp.GetCustomerPurchaseIdAsync.

  Skicka din Entra ID-åtkomsttoken till parametern "serviceTicket" för metoden. Om du behåller anonyma användar-ID:n i kontexten för tjänster som du hanterar som utgivare av den aktuella appen kan du även skicka ett användar-ID till parametern publisherUserId för att associera den aktuella användaren med den nya Microsoft Store-ID-nyckeln (användar-ID:t bäddas in i nyckeln). Om du inte behöver associera ett användar-ID med Microsoft Store-ID-nyckeln kan du skicka valfritt strängvärde till parametern publisherUserId.

3. När appen har skapat en Microsoft Store-ID-nyckel skickar du tillbaka nyckeln till tjänsten.

Diagram

Följande diagram illustrerar processen med att skapa en Microsoft Store-ID-nyckel.

Anspråk i en Microsoft Store-ID-nyckel

En Microsoft Store-ID-nyckel är en JSON-webbtoken (JWT) som representerar identiteten för den användare vars produktägarinformation du vill komma åt. När du avkodar med Base64 innehåller en Microsoft Store-ID-nyckel följande anspråk.

• iat: Identifierar den tidpunkt då nyckeln utfärdades. Det här anspråket kan användas för att fastställa tokenens ålder. Det här värdet uttrycks som epoktid.
• iss: Identifierar utfärdaren. Detta har samma värde som anspråket aud.
• aud: Identifierar målgruppen. Måste vara något av följande värden: https://collections.mp.microsoft.com/v6.0/keys eller https://purchase.mp.microsoft.com/v6.0/keys.
• exp: Identifierar förfallotiden på eller efter vilken nyckeln inte längre kommer att accepteras för bearbetning av något annat än för att förnya nycklar. Värdet för det här anspråket uttrycks som epoktid.
• nbf: Identifierar den tidpunkt då token godkänns för bearbetning. Värdet för det här anspråket uttrycks som epoktid.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: Det klient-ID som identifierar utvecklaren.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: En ogenomskinlig nyttolast (krypterad och Base64-kodad) som innehåller information som endast är avsedd att användas av Microsoft Store-tjänster.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: Ett användar-ID som identifierar den aktuella användaren i kontexten för dina tjänster. Det här är samma värde som du skickar till den valfria publisherUserId parametern för den metod som du använder för att skapa nyckeln.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: Den URI som du kan använda för att förnya nyckeln.

Här är ett exempel på en avkodad Nyckelrubrik för Microsoft Store-ID.

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

Här är ett exempel på en avkodad Anspråksuppsättning för Microsoft Store-ID-nyckel.

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

Relaterade ämnen

• Fråga efter produkter
• Rapportera förbrukningsprodukter som är uppfyllda
• Bevilja kostnadsfria produkter
• Hämta prenumerationer för en användare
• Ändra faktureringstillståndet för en prenumeration för en användare
• Förnya en Microsoft Store-ID-nyckel
• Integrera program med Microsofts identitetsplattform
• ID-token på Microsofts identitetsplattform
• Microsoft.StoreServices-biblioteket (GitHub)