Zarządzanie uprawnieniami produktów w ramach usługi

Jeśli masz katalog aplikacji i dodatków, możesz użyć interfejsu API kolekcji Microsoft Store i interfejsu API zakupów Microsoft Store, aby uzyskać dostęp do informacji o uprawnieniach dla tych produktów z usług. Uprawnienie reprezentuje prawo klienta do korzystania z aplikacji lub dodatku opublikowanego w Sklepie Microsoft.

Te interfejsy API składają się z metod REST, które są przeznaczone dla deweloperów z wykazami dodatków obsługiwanymi przez usługi międzyplatformowe. Te interfejsy API umożliwiają wykonywanie następujących czynności:

• Interfejs API kolekcji sklepu Microsoft Store: Zapytanie o produkty posiadane przez użytkownika oraz zgłoszenie produktu konsumpcyjnego jako zrealizowanego.
• Interfejs API zakupów w Microsoft Store: Przyznaj użytkownikowi bezpłatny produkt, uzyskaj subskrypcje dla użytkownikaoraz zmień stan rozliczeniowy subskrypcji dla użytkownika.

Notatka

Interfejs API kolekcji sklepu Microsoft Store i interfejs API zakupów używają uwierzytelniania platformy tożsamości firmy Microsoft (Entra ID) w celu uzyskania dostępu do informacji o własności klienta. Aby korzystać z tych interfejsów API, użytkownik (lub organizacja) musi mieć dzierżawę Entra ID oraz musi mieć uprawnienia administratora globalnego dla dzierżawy. Jeśli korzystasz już z platformy Microsoft 365 lub innych usług biznesowych od Microsoft, masz już dzierżawcę Entra ID.

Biblioteka Microsoft.StoreServices

Aby usprawnić przepływ uwierzytelniania i wywoływać usługi Microsoft Store, zapoznaj się z projektem Microsoft.StoreServices i przykładem w witrynie GitHub. Biblioteka Microsoft.StoreServices pomoże zarządzać kluczami uwierzytelniania i udostępnia interfejsy API typu wrapper do wywoływania Usług Sklep Microsoft w celu zarządzania produktami. Przykładowy projekt wyróżnia, w jaki sposób usługa może używać biblioteki Microsoft.StoreServices, na przykład logiki do zarządzania produktami eksploatacyjnymi, uzgadniania zwrotu kosztów zakupów, odnawiania wygasłych poświadczeń i nie tylko. Przewodnik konfiguracji krok po kroku jest dołączony do przykładu w celu skonfigurowania przykładowej usługi na komputerze lub za pośrednictwem platformy Azure.

• biblioteka Microsoft.StoreServices (GitHub)
• Przykładowy kod Microsoft.StoreServices (GitHub)

Przegląd

W poniższych krokach opisano pełny proces korzystania z interfejsu API kolekcji sklepu Microsoft Store i interfejsu API zakupów:

1. Skonfiguruj aplikację wEntra ID.
2. Skojarz identyfikator aplikacji Entra ID z aplikacją w Centrum partnerskim.
3. W twojej usłudze utwórz tokeny dostępu Entra ID, które reprezentują tożsamość wydawcy.
4. W aplikacji klienckiej systemu Windows utwórz klucz identyfikatora sklepu Microsoft Store reprezentujący tożsamość bieżącego użytkownika i przekaż ten klucz z powrotem do usługi.

Ten pełny proces obejmuje dwa składniki oprogramowania, które wykonują różne zadania:

• Twoja usługa. Jest to aplikacja, która działa bezpiecznie w kontekście środowiska biznesowego i można ją zaimplementować przy użyciu dowolnej wybranej platformy programistycznej. Twoja usługa jest odpowiedzialna za tworzenie tokenów dostępu Entra ID wymaganych w tym scenariuszu oraz wywoływanie adresów URI REST dla API kolekcji i zakupu w sklepie Microsoft Store.
• Twoja aplikacja kliencka Windows. Jest to aplikacja, dla której chcesz uzyskać dostęp do informacji o upoważnieniach klienta i zarządzać nimi (w tym dodatki dla aplikacji). Ta aplikacja jest odpowiedzialna za tworzenie kluczy identyfikatorów sklepu Microsoft Store, które są potrzebne do wywoływania interfejsu API kolekcji Microsoft Store oraz interfejsu API zakupów w twojej usłudze.

Krok 1. Konfigurowanie aplikacji w identyfikatorze Entra

Aby móc korzystać z interfejsów API kolekcji Microsoft Store lub zakupu, najpierw należy utworzyć aplikację internetową Entra ID, pobrać identyfikator dzierżawcy i identyfikator aplikacji oraz wygenerować klucz. Aplikacja internetowa Entra ID reprezentuje usługę, za pomocą której chcesz wywołać interfejs API kolekcji Microsoft Store lub interfejs API zakupów. Potrzebujesz identyfikatora dzierżawy, identyfikatora aplikacji i klucza, aby wygenerować tokeny dostępu Entra ID, które są potrzebne do wywołania interfejsu API.

1. Jeśli jeszcze tego nie zrobiono, postępuj zgodnie z instrukcjami w przewodniku Szybki start : Rejestrowanie aplikacji za pomocą platformy tożsamości firmy Microsoft w celu zarejestrowania aplikacji internetowej/interfejsu API przy użyciu identyfikatora Entra.

   Notatka

   Podczas rejestrowania aplikacji musisz wybrać aplikację internetową/interfejs API jako typ aplikacji, aby można było pobrać klucz (nazywany również kluczem tajnym klienta ) dla aplikacji. Aby wywołać interfejs API kolekcji sklepu Microsoft Store lub interfejs API zakupu, należy podać klucz tajny klienta podczas żądania tokenu dostępu z identyfikatora Entra w późniejszym kroku.

2. W witrynie Azure Management Portalprzejdź do Microsoft Entra ID. Wybierz dzierżawę, kliknij pozycję Rejestracje aplikacji w panelu nawigacyjnym po lewej stronie w obszarze Zarządzaj, a następnie wybierz aplikację.

3. Zostanie wyświetlona strona główna rejestracji aplikacji. Na tej stronie skopiuj wartość Identyfikator aplikacji do późniejszego użycia.

4. Utwórz klucz, który będzie potrzebny później (jest to wszystko nazywane kluczem tajnym klienta ). W panelu po lewej stronie kliknij pozycję "Ustawienia" , a następnie "Klucze". Na tej stronie wykonaj kroki, aby utworzyć klucz. Skopiuj ten klucz do późniejszego użycia.

Krok 2: Połącz identyfikator aplikacji Entra ID z aplikacją kliencką w Centrum partnerskim

Aby móc używać interfejsu API kolekcji Microsoft Store lub interfejsu API zakupu do konfiguracji własności i zakupów dla aplikacji lub dodatku, musisz skojarzyć identyfikator aplikacji Entra z aplikacją (lub aplikacją zawierającą dodatek) w Centrum Partnerskim.

Notatka

To zadanie trzeba wykonać tylko raz. Po utworzeniu identyfikatora dzierżawy, identyfikatora aplikacji i klucza tajnego klienta możesz ponownie użyć tych wartości za każdym razem, gdy musisz utworzyć nowy token dostępu identyfikatora Entra.

1. Zaloguj się do centrum partnerskiego i wybierz aplikację.
2. Przejdź do strony Services>Product collections and purchases i wprowadź identyfikator aplikacji Entra w jednym z dostępnych pól identyfikatora klienta.

Krok 3. Tworzenie tokenów dostępu Entra ID

Aby można było pobrać klucz identyfikatora sklepu Microsoft Store, wywołać interfejs API kolekcji sklepu Microsoft Store lub skorzystać z interfejsu API zakupu, wasza usługa musi utworzyć kilka różnych tokenów dostępu Entra ID reprezentujących tożsamość wydawcy. Każdy token będzie używany z innym interfejsem API. Okres istnienia każdego tokenu wynosi 60 minut i można je odświeżyć po wygaśnięciu.

Ważny

Twórz tokeny dostępu Entra ID tylko w kontekście swojej usługi, a nie w aplikacji. Klucz tajny klienta może zostać naruszony, jeśli zostanie wysłany do aplikacji.

Omówienie różnych tokenów i identyfikatorów URI odbiorców

W zależności od metod, które mają być wywoływane w interfejsie API kolekcji sklepu Microsoft Store lub interfejsie API zakupu, należy utworzyć dwa lub trzy różne tokeny. Każdy token dostępu jest skojarzony z innym identyfikatorem URI odbiorców.

• We wszystkich przypadkach należy utworzyć token z identyfikatorem URI odbiorców https://onestore.microsoft.com. W późniejszym kroku przekażesz ten token do nagłówka Authorization metod w interfejsie API kolekcji sklepu Microsoft Store lub interfejsie API zakupu.

  Ważny

  Użyj odbiorców https://onestore.microsoft.com tylko z tokenami dostępu przechowywanymi bezpiecznie w usłudze. Uwidacznianie tokenów dostępu tym odbiorcom spoza usługi może sprawić, że usługa będzie podatna na ataki powtarzane.

• Jeśli chcesz wywołać metodę w interfejsie API kolekcji sklepu Microsoft Store, aby zapytać o produkty należące do użytkownika lub zgłosić produkt eksploatacyjny jako spełniony, należy również utworzyć token z identyfikatorem URI odbiorców https://onestore.microsoft.com/b2b/keys/create/collections. W późniejszym kroku przekażesz ten token do metody klienta w Windows SDK, aby zażądać klucza identyfikatora Microsoft Store, którego można użyć z interfejsem API kolekcji Microsoft Store.

• Jeśli chcesz wywołać metodę w interfejsie API zakupu sklepu Microsoft Store, aby udzielić bezpłatnego produktu użytkownikowi, uzyskać subskrypcje dla użytkownikalub zmienić stan rozliczeniowy subskrypcji dla użytkownika, musisz również utworzyć token z identyfikatorem URI odbiorców https://onestore.microsoft.com/b2b/keys/create/purchase. W późniejszym kroku przekażesz ten token do metody klienta w zestawie Sdk systemu Windows, aby zażądać klucza identyfikatora sklepu Microsoft Store, którego można użyć z interfejsem API zakupu sklepu Microsoft Store.

Tworzenie tokenów

Aby utworzyć tokeny dostępu, użyj interfejsu API OAuth 2.0 w swojej usłudze, postępując zgodnie z instrukcjami w zapisie Service to Service Calls Using Client Credentials (Wywołania usługi do usługi przy użyciu poświadczeń klienta), aby wysłać żądanie HTTP POST do punktu końcowego https://login.microsoftonline.com/<tenant_id>/oauth2/token. Oto przykładowe żądanie.

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

Dla każdego tokenu określ następujące dane parametrów:

• W przypadku parametrów client_id i client_secret określ identyfikator aplikacji i klucz tajny klienta dla aplikacji pobranej z witryny Azure Management Portal. Oba te parametry są wymagane w celu utworzenia tokenu dostępu z poziomem uwierzytelniania wymaganym przez interfejs API kolekcji sklepu Microsoft Store lub interfejs API zakupu.

• W przypadku parametru zasobu , w zależności od typu tworzonego tokenu dostępu, należy określić jeden z identyfikatorów URI odbiorców wymienionych w poprzedniej sekcji .

Po wygaśnięciu tokenu dostępu możesz go odświeżyć, postępując zgodnie z instrukcjami tutaj. Aby uzyskać więcej informacji na temat struktury tokenu dostępu, zobacz Obsługiwane typy tokenów i oświadczeń.

Krok 4. Tworzenie klucza identyfikatora sklepu Microsoft Store

Aby można było wywołać dowolną metodę w interfejsie API kolekcji sklepu Microsoft Store lub interfejsie API zakupu, aplikacja musi utworzyć klucz identyfikatora sklepu Microsoft Store i wysłać go do usługi. Ten klucz jest tokenem sieci Web JSON (JWT), który reprezentuje tożsamość użytkownika, którego informacje o własności produktu chcesz uzyskać dostęp. Aby uzyskać więcej informacji na temat roszczeń w tym kluczu, zobacz Roszczenia w kluczu identyfikatora sklepu Microsoft Store.

Obecnie jedynym sposobem utworzenia klucza identyfikatora sklepu Microsoft Store jest wywołanie interfejsu API platformy uniwersalnej systemu Windows (UWP) z kodu klienta w aplikacji. Wygenerowany klucz reprezentuje tożsamość użytkownika, który jest obecnie zalogowany do sklepu Microsoft Store na urządzeniu.

Notatka

Każdy klucz identyfikatora sklepu Microsoft Store jest ważny przez 30 dni. Przed wygaśnięciem klucza można odnowić klucz. Zalecamy odnowienie kluczy identyfikatorów sklepu Microsoft Store zamiast tworzenia nowych.

Aby utworzyć klucz identyfikatora sklepu Microsoft Store dla interfejsu API kolekcji sklepu Microsoft Store

Wykonaj następujące kroki, aby utworzyć klucz identyfikatora sklepu Microsoft Store, którego można użyć z interfejsem API kolekcji Microsoft Store, aby wyszukać produkty posiadane przez użytkownika lub oznaczyć produkt eksploatacyjny jako zrealizowany.

1. Przekaż token dostępu Entra ID, który ma wartość identyfikatora URI odbiorcy https://onestore.microsoft.com/b2b/keys/create/collections, z usługi do aplikacji klienckiej. Jest to jeden z tokenów utworzonych wcześniej w kroku 3.

2. W kodzie aplikacji wywołaj jedną z następujących metod, aby pobrać klucz identyfikatora sklepu Microsoft Store:

• Jeśli aplikacja używa klasy StoreContext w przestrzeni nazw Windows.Services.Store do zarządzania zakupami w aplikacji, użyj metody StoreContext.GetCustomerCollectionsIdAsync.

• Jeśli aplikacja używa klasy CurrentApp w przestrzeni nazw Windows.ApplicationModel.Store do zarządzania zakupami w aplikacji, użyj metody CurrentApp.GetCustomerCollectionsIdAsync.

  Przekaż token dostępu Entra ID do parametru serviceTicket metody. Jeśli jako wydawca tej aplikacji zachowujesz anonimowe identyfikatory użytkowników w kontekście zarządzanych usług, możesz również przekazać identyfikator użytkownika do parametru publisherUserId, aby skojarzyć bieżącego użytkownika z nowym kluczem ID Microsoft Store (identyfikator użytkownika zostanie osadzony w kluczu). W przeciwnym razie, jeśli nie musisz skojarzyć identyfikatora użytkownika z kluczem identyfikatora sklepu Microsoft Store, możesz przekazać dowolną wartość ciągu do parametru publisherUserId.

3. Po pomyślnym utworzeniu przez aplikację klucza identyfikatora Microsoft Store przekaż klucz z powrotem do usługi.

Aby utworzyć klucz identyfikatora sklepu Microsoft Store dla interfejsu API zakupu sklepu Microsoft Store

Wykonaj następujące kroki, aby utworzyć klucz identyfikatora sklepu Microsoft Store, którego można użyć z interfejsem API zakupu sklepu Microsoft Store, aby udzielić bezpłatnego produktu użytkownikowi, uzyskać subskrypcje dla użytkownikalub zmienić stan rozliczeniowy subskrypcji dla użytkownika.

1. Przekaż token dostępu Entra ID, który ma wartość identyfikatora URI odbiorców https://onestore.microsoft.com/b2b/keys/create/purchase z usługi do aplikacji klienckiej. Wcześniej, w kroku 3, utworzyłeś jeden z tokenów .

2. W kodzie aplikacji wywołaj jedną z następujących metod, aby pobrać klucz identyfikatora sklepu Microsoft Store:

• Jeśli aplikacja używa klasy StoreContext w przestrzeni nazw Windows.Services.Store do zarządzania zakupami w aplikacji, użyj metody StoreContext.GetCustomerPurchaseIdAsync.

• Jeśli aplikacja używa klasy CurrentApp w przestrzeni nazw Windows.ApplicationModel.Store do zarządzania zakupami w aplikacji, użyj metody CurrentApp.GetCustomerPurchaseIdAsync.

  Przekaż token dostępu Entra ID do parametru metody serviceTicket . Jeśli zachowujesz identyfikatory anonimowych użytkowników w kontekście usług, którymi zarządzasz jako wydawca bieżącej aplikacji, możesz również przekazać identyfikator użytkownika do parametru publisherUserId, aby skojarzyć bieżącego użytkownika z nowym kluczem identyfikatora Microsoft Store. Identyfikator użytkownika będzie częścią klucza. W przeciwnym razie, jeśli nie musisz skojarzyć identyfikatora użytkownika z kluczem identyfikatora sklepu Microsoft Store, możesz przekazać dowolną wartość ciągu do parametru publisherUserId.

3. Po pomyślnym utworzeniu przez aplikację klucza identyfikatora sklepu Microsoft Store, przekaż ten klucz z powrotem do swojej usługi.

Diagram

Na poniższym diagramie przedstawiono proces tworzenia klucza identyfikatora sklepu Microsoft Store.

Oświadczenia w kluczu identyfikatora sklepu Microsoft Store

Klucz identyfikatora sklepu Microsoft Store to token internetowy JSON (JWT), który reprezentuje tożsamość użytkownika, którego informacje o własności produktu mają być dostępne. Podczas dekodowania przy użyciu base64 klucz identyfikatora sklepu Microsoft Store zawiera następujące oświadczenia.

• iat: określa czas wystawienia klucza. To oświadczenie może służyć do określenia wieku tokenu. Ta wartość jest wyrażona jako czas epoki.
• iss: identyfikuje wystawcę. Ma to taką samą wartość jak oświadczenie aud.
• aud: identyfikuje odbiorców. Musi być jedną z następujących wartości: https://collections.mp.microsoft.com/v6.0/keys lub https://purchase.mp.microsoft.com/v6.0/keys.
• exp: określa czas wygaśnięcia, po którym klucz nie będzie już akceptowany do przetwarzania wszystkich elementów z wyjątkiem odnawiania kluczy. Wartość tego oświadczenia jest wyrażona jako czas w formacie epoch.
• nbf: określa czas, w którym token zostanie zaakceptowany do przetworzenia. Wartość tego oświadczenia jest wyrażona jako czas epoki.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: identyfikator klienta identyfikujący dewelopera.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: nieprzezroczystym ładunkiem (zaszyfrowanym i zakodowanym w formacie Base64), który zawiera informacje przeznaczone tylko do użytku przez usługi Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: identyfikator użytkownika identyfikujący bieżącego użytkownika w kontekście usług. Jest to ta sama wartość przekazywana do opcjonalnego parametru publisherUserId metody używanej do utworzenia klucza.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: identyfikator URI, którego można użyć do odnowienia klucza.

Oto przykład zdekodowanego nagłówka klucza ID sklepu Microsoft Store.

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

Oto przykład zdekodowanego zestawu roszczeń dotyczących klucza ID sklepu Microsoft Store.

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

Tematy pokrewne

• Zapytanie o produkty
• Raportuj produkty eksploatacyjne zgodnie z
• Udzielanie bezpłatnych produktów
• Pobieranie subskrypcji dla użytkownika
• Zmienianie stanu rozliczeniowego subskrypcji dla użytkownika
• Odnów klucz identyfikatora Microsoft Store
• integrowanie aplikacji z platformą tożsamości firmy Microsoft
• identyfikatory tokenów w platformie tożsamości Microsoft
• biblioteka Microsoft.StoreServices (GitHub)