Správa nároků na produkty ze služby

Pokud máte katalog aplikací a doplňků, můžete použít rozhraní API Microsoft Store pro kolekci a rozhraní API pro nákup v Microsoft Storu, abyste získali přístup k informacím o oprávnění pro tyto produkty z vašich služeb. Nárok představuje právo zákazníka používat aplikaci nebo doplněk publikovaný prostřednictvím Microsoft Storu.

Tato rozhraní API se skládají z metod REST navržených pro použití vývojáři s doplňkovými katalogy, které jsou podporovány službami pro různé platformy. Tato rozhraní API umožňují provádět následující akce:

• Rozhraní API kolekce Microsoft Storu: Dotaz na produkty vlastněné uživatelem a označení spotřebního produktu jako splněného.
• Rozhraní API pro nákup v Microsoft Storu: udělit uživateli bezplatný produkt, získat uživateli předplatnáa změnit stav fakturace předplatného pro uživatele.

Poznámka

Rozhraní API kolekce Microsoft Store a rozhraní API pro nákupy používají ověřování Microsoft Identity Platform (Entra ID) pro přístup k informacím o vlastnictví zákazníka. Abyste mohli tato rozhraní API používat, musíte vy (nebo vaše organizace) mít tenanta Entra ID a musíte mít oprávnění globálního správce tenanta. Pokud už používáte Microsoft 365 nebo jiné obchodní služby od Microsoftu, už máte tenanta Entra ID.

Knihovna Microsoft.StoreServices

Pokud chcete zjednodušit tok ověřování a volat služby Microsoft Store, projděte si projekt Microsoft.StoreServices a ukázku na GitHubu. Knihovna Microsoft.StoreServices pomůže se správou ověřovacích klíčů a poskytne obalující API pro volání do služeb Microsoft Store za účelem správy produktů. Ukázkový projekt zdůrazňuje, jak může služba používat knihovnu Microsoft.StoreServices, například logiku pro správu spotřebních produktů, spojování refundovaných nákupů, prodloužení platnosti přihlašovacích údajů a další. Podrobný průvodce konfigurací je součástí ukázky pro nastavení ukázkové služby na počítači nebo prostřednictvím Azure.

• knihovny Microsoft.StoreServices (GitHub)
• ukázkové služby Microsoft.StoreServices (GitHub)

Přehled

Následující kroky popisují kompletní proces použití rozhraní API kolekce Microsoft Store a rozhraní API pro nákup:

1. Konfigurace aplikace v Entra ID.
2. Přiřaďte ID aplikace Entra ID k aplikaci v Partnerském Centru.
3. Ve vaší službě vytvoří přístupové tokeny Entra ID, které představují vaši identitu vydavatele.
4. Ve vaší klientské aplikaci pro Windows vytvořte klíč ID obchodu Microsoft Store, který představuje identitu aktuálního uživatele, a předaný klíč vraťte zpět do vaší služby.

Tento kompletní proces zahrnuje dvě softwarové komponenty, které provádějí různé úlohy:

• Vaše služba. Jedná se o aplikaci, která běží bezpečně v kontextu vašeho obchodního prostředí a dá se implementovat pomocí libovolné vámi zvolené vývojové platformy. Vaše služba zodpovídá za vytvoření přístupových tokenů Entra ID potřebných pro scénář a za volání identifikátorů REST URI pro rozhraní API kolekce Microsoft Store a rozhraní API pro nákup.
• vaše klientská aplikace pro Windows. Toto je aplikace, pro kterou chcete získat přístup k informacím o nároku zákazníka a spravovat je (včetně doplňků pro aplikaci). Tato aplikace je zodpovědná za vytváření ID klíčů pro Microsoft Store, které potřebujete k volání rozhraní API kolekce Microsoft Storu a k použití rozhraní API pro nákup z vaší služby.

Krok 1: Konfigurace aplikace v ID Entra

Než budete moct použít rozhraní API kolekce Microsoft Store nebo rozhraní API pro nákup, musíte vytvořit webovou aplikaci Entra ID, načíst ID tenanta a ID aplikace a vygenerovat klíč. Webová aplikace Entra ID představuje službu, ze které chcete volat rozhraní API sbírky Microsoft Store nebo rozhraní API pro nákup. K vygenerování přístupových tokenů Entra ID, které potřebujete k volání rozhraní API, potřebujete ID tenanta, ID aplikace a klíč.

1. Pokud jste to ještě neudělali, postupujte podle pokynů v Rychlém startu: Zaregistrujte aplikaci na platformě Microsoft Identity Platform k registraci webové aplikace nebo rozhraní API pomocí Id Entra.

   Poznámka

   Při registraci aplikace musíte zvolit webovou aplikaci nebo rozhraní API jako typ aplikace, abyste mohli pro aplikaci načíst klíč (označovaný také jako tajný klíč klienta). Pokud chcete volat rozhraní API pro shromažďování Microsoft Storu nebo rozhraní API pro nákup, musíte zadat tajný klíč klienta, když žádáte o přístupový token z ID Entra v pozdějším kroku.

2. Na portálu pro správu Azurepřejděte na MICROSOFT Entra ID . Vyberte svého tenanta, klikněte na Registrace aplikací v levém navigačním podokně v sekci Správa, a pak vyberte vaši aplikaci.

3. Přejdete na hlavní registrační stránku aplikace. Na této stránce zkopírujte hodnotu identifikátoru aplikace pro pozdější použití.

4. Vytvořte klíč, který budete potřebovat později (to se označuje jako tajný klíč klienta ). V levém podokně klikněte na Nastavení a potom na Klíče. Na této stránce dokončete kroky pro vytvoření klíče. Zkopírujte tento klíč pro pozdější použití.

Krok 2: Přidružení ID aplikace Entra ID k klientské aplikaci v Partnerském centru

Než budete moct použít rozhraní API pro kolekci z Microsoft Storu nebo rozhraní API pro nákup ke konfiguraci vlastnictví a nákupů pro vaši aplikaci nebo doplněk, musíte přidružit ID aplikace Entra k aplikaci (nebo k aplikaci, která obsahuje doplněk) v Partnerském centru.

Poznámka

Tuto úlohu musíte provést jenom jednou. Jakmile budete mít ID tenanta, ID aplikace a tajný klíč klienta, můžete tyto hodnoty kdykoli znovu použít k vytvoření nového přístupového tokenu Entra ID.

1. Přihlaste se k partnerskému centru a vyberte aplikaci.
2. Přejděte na stránku Services>Kolekce produktů a nákupy a zadejte ID vaší aplikace Entra do jednoho z dostupných polí ID klienta.

Krok 3: Vytvoření přístupových tokenů Entra ID

Než budete moct načíst klíč ID Microsoft Storu nebo volat rozhraní API kolekce Microsoft Storu nebo rozhraní API pro nákup, musí vaše služba vytvořit několik různých přístupových tokenů Entra ID, které představují vaši identitu vydavatele. Každý token se použije s jiným rozhraním API. Životnost každého tokenu je 60 minut a po vypršení jejich platnosti je můžete aktualizovat.

Důležitý

Vytvořte přístupové tokeny Entra ID pouze v kontextu vaší služby, ne v aplikaci. Tajemství klienta může být ohroženo, pokud je odesláno do vaší aplikace.

Vysvětlení různých tokenů a identifikátorů URI cílové skupiny

V závislosti na tom, které metody chcete volat v rozhraní API kolekce Microsoft Store nebo rozhraní API pro nákup, je třeba vytvořit dva nebo tři různé tokeny. Každý přístupový token je přidružený k jinému identifikátoru URI cílové skupiny.

• Ve všech případech musíte vytvořit token s URI pro publikum https://onestore.microsoft.com. V pozdějším kroku předáte tento token do hlavičky Authorization metod v rozhraní API kolekce Microsoft Store nebo rozhraní API pro nákup.

  Důležitý

  Používejte cílovou skupinu https://onestore.microsoft.com pouze s přístupovými tokeny, které jsou bezpečně uloženy ve vaší službě. Vystavení přístupových tokenů s tímto publikem mimo vaši službu může vystavit váš systém riziku útoků typu replay.

• Pokud chcete volat metodu v rozhraní API kolekce Microsoft Storu, která dotaz na produkty vlastněné uživatelem nebo hlásit spotřební produkt podle, musíte také vytvořit token s identifikátorem URI cílové skupiny https://onestore.microsoft.com/b2b/keys/create/collections. V pozdějším kroku předáte tento token klientské metodě v sadě Windows SDK a požádáte o klíč ID Microsoft Storu, který můžete použít s rozhraním API kolekce Microsoft Store.

• Pokud chcete volat metodu v rozhraní API pro nákup v Microsoft Storu, abyste uživateli udělili bezplatný produkt, získat předplatná pro uživatelenebo změnit stav fakturace předplatného pro uživatele, musíte také vytvořit token s identifikátorem URI cílové skupiny https://onestore.microsoft.com/b2b/keys/create/purchase. V pozdějším kroku předáte tento token metodě klienta v sadě Windows SDK a požádáte o klíč ID Microsoft Storu, který můžete použít s rozhraním API pro nákup v Microsoft Storu.

Vytvoření tokenů

Pokud chcete vytvořit přístupové tokeny, použijte ve své službě rozhraní API OAuth 2.0 podle pokynů v tématu Volání služby do služby pomocí přihlašovacích údajů klienta k odeslání HTTP POST do koncového bodu https://login.microsoftonline.com/<tenant_id>/oauth2/token. Tady je ukázkový požadavek.

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

Pro každý token zadejte následující data parametrů:

• Pro parametry client_id a client_secret zadejte ID aplikace a tajný klíč klienta pro vaši aplikaci, kterou jste získali z portálu pro správu Azure. Oba tyto parametry jsou potřeba k vytvoření přístupového tokenu s úrovní ověřování vyžadovanou rozhraním API kolekce Microsoft Store nebo rozhraním API pro nákup.

• U parametru prostředku zadejte identifikátory URI cílové skupiny uvedené v předchozí částiv závislosti na typu přístupového tokenu, který vytváříte.

Po vypršení platnosti přístupového tokenu ho můžete aktualizovat podle pokynů zde. Další podrobnosti o struktuře přístupového tokenu najdete v tématu Podporované typy tokenů a deklarací identity.

Krok 4: Vytvoření klíče ID Microsoft Storu

Než budete moct volat jakoukoli metodu v rozhraní API kolekce Microsoft Storu nebo v rozhraní API pro nákupy, musí vaše aplikace vytvořit klíč ID Microsoft Storu a odeslat ho vaší službě. Tento klíč je webový token JSON (JWT), který představuje identitu uživatele, jehož informace o vlastnictví produktu chcete získat. Další informace o nárocích v tomto klíči naleznete v tématu nároky v klíči ID obchodu Microsoft Store.

Jediný způsob, jak vytvořit klíč ID Microsoft Storu, je v současné době voláním rozhraní API pro Univerzální platformu Windows (UPW) z klientského kódu ve vaší aplikaci. Vygenerovaný klíč představuje identitu uživatele, který je aktuálně přihlášený k Microsoft Storu na zařízení.

Poznámka

Každý klíč ID Microsoft Storu je platný po dobu 30 dnů. Před vypršením platnosti klíče můžete obnovit klíč. Doporučujeme, abyste si klíče ID Microsoft Storu prodloužili místo vytváření nových klíčů.

Vytvoření klíče ID Microsoft Store pro rozhraní API služby kolekce Microsoft Store

Pomocí těchto kroků vytvořte klíč ID Microsoft Storu, který můžete použít s rozhraním API kolekce Microsoft Store k dotazování na produkty vlastněné uživatelem nebo nahlásit spotřební produkt podle.

1. Předejte přístupový token Entra ID, který má hodnotu identifikátoru URI cílové skupiny https://onestore.microsoft.com/b2b/keys/create/collections z vaší služby do klientské aplikace. Toto je jeden z tokenů, které jste vytvořili dříve v kroku 3.

2. V kódu aplikace zavolejte jednu z těchto metod pro načtení klíče Microsoft Store ID:

• Pokud vaše aplikace ke správě nákupů v aplikaci používá třídu StoreContext v oboru názvů Windows.Services.Store, použijte metodu StoreContext.GetCustomerCollectionsIdAsync.

• Pokud vaše aplikace ke správě nákupů v aplikaci používá třídu CurrentApp v oboru názvů Windows.ApplicationModel.Store, použijte metodu CurrentApp.GetCustomerCollectionsIdAsync.

  Předejte přístupový token Entra ID do parametru metody „serviceTicket“. Pokud udržujete ID anonymních uživatelů v kontextu služeb, které spravujete jako vydavatel aktuální aplikace, můžete také předat ID uživatele do parametru publisherUserId pro přidružení aktuálního uživatele k novému klíči ID Microsoft Storu (ID uživatele se vloží do klíče). V opačném případě, pokud nepotřebujete přidružit ID uživatele ke klíči ID Microsoft Storu, můžete předat libovolnou řetězcovou hodnotu do parametru publisherUserId.

3. Jakmile aplikace úspěšně vytvoří klíč ID Microsoft Storu, předejte ho zpět do služby.

Vytvoření klíče ID Microsoft Storu pro rozhraní API pro nákup v Microsoft Storu

Pomocí těchto kroků vytvořte klíč ID Microsoft Storu, který můžete použít s rozhraním API pro nákup v Microsoft Storu k udělit uživateli bezplatný produkt, získat předplatná pro uživatelenebo změnit stav fakturace předplatného pro uživatele.

1. Předejte přístupový token Entra ID, který má hodnotu identifikátoru URI cílové skupiny https://onestore.microsoft.com/b2b/keys/create/purchase z vaší služby do klientské aplikace. Toto je jeden z tokenů, které jste vytvořili dříve v kroku 3.

2. V kódu aplikace zavolejte jednu z těchto metod pro načtení klíče ID Microsoft Storu:

• Pokud vaše aplikace ke správě nákupů v aplikaci používá třídu StoreContext v oboru názvů Windows.Services.Store, použijte metodu StoreContext.GetCustomerPurchaseIdAsync.

• Pokud vaše aplikace ke správě nákupů v aplikaci používá třídu CurrentApp v oboru názvů Windows.ApplicationModel.Store, použijte metodu CurrentApp.GetCustomerPurchaseIdAsync.

  Předejte svůj přístupový token Entra ID do parametru serviceTicket metody . Pokud udržujete ID anonymních uživatelů v kontextu služeb, které spravujete jako vydavatel aktuální aplikace, můžete také předat ID uživatele do parametru publisherUserId pro přidružení aktuálního uživatele k novému klíči ID Microsoft Storu (ID uživatele se vloží do klíče). V opačném případě, pokud nepotřebujete přidružit ID uživatele ke klíči ID Microsoft Storu, můžete předat libovolnou řetězcovou hodnotu do parametru publisherUserId.

3. Jakmile aplikace úspěšně vytvoří klíč ID Microsoft Storu, předejte ho zpět do služby.

Diagram

Následující diagram znázorňuje proces vytvoření klíče ID Microsoft Storu.

Deklarace identity v klíči ID Microsoft Storu

Klíč ID Microsoft Storu je webový token JSON (JWT), který představuje identitu uživatele, jehož informace o vlastnictví produktu chcete získat. Při dekódování pomocí Base64 obsahuje klíč ID Microsoft Storu následující nároky.

• iat: Určuje čas vydání klíče. Tuto deklaraci identity lze použít k určení stáří tokenu. Tato hodnota se vyjadřuje jako epochový čas.
• iss: Identifikuje vystavitele. Tato hodnota má stejnou hodnotu jako nárok aud.
• aud: Identifikuje cílovou skupinu. Musí to být jedna z následujících hodnot: https://collections.mp.microsoft.com/v6.0/keys nebo https://purchase.mp.microsoft.com/v6.0/keys.
• exp: Určuje dobu vypršení platnosti, po které už klíč nebude přijat ke zpracování čehokoli kromě obnovování klíčů. Hodnota tohoto nároku je vyjádřena jako čas epochy.
• nbf: Určuje čas, kdy bude token přijat ke zpracování. Hodnota této deklarace identity se vyjadřuje jako epocha.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: ID klienta, které identifikuje vývojáře.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: Neprůhlená datová část (zašifrovaná a zakódovaná s kódováním Base64), která obsahuje informace určené pouze pro použití službami Microsoft Storu.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: ID uživatele, které identifikuje aktuálního uživatele v kontextu vašich služeb. Jedná se o stejnou hodnotu, kterou předáte volitelnému parametru publisherUserId metody , kterou používáte k vytvoření klíče.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: Identifikátor URI, který můžete použít k obnovení klíče.

Tady je příklad dekódované hlavičky klíče ID Microsoft Storu.

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

Tady je příklad dekódované množiny nároků ID klíče Microsoft Storu.

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

Související témata

• Dotaz na produkty
• Nahlásit spotřební výrobky jako splněné
• Udělení bezplatných produktů
• Získání předplatných pro uživatele
• Změna stavu fakturace předplatného pro uživatele
• Obnovení klíče ID pro Microsoft Store
• integrace aplikací s platformou Microsoft Identity Platform
• Identifikační tokeny na platformě Microsoft
• Knihovna Microsoft.StoreServices (GitHub)