Verwalten von Produktansprüchen aus einem Dienst

Wenn Sie über einen Katalog von Apps und Add-Ons verfügen, können Sie die Microsoft Store-Sammlungs-API und die Microsoft Store-Einkaufs-API verwenden, um auf Berechtigungsinformationen für diese Produkte von Ihren Diensten zuzugreifen. Eine Berechtigung stellt das Recht eines Kunden dar, eine App oder ein Add-On zu verwenden, die über den Microsoft Store veröffentlicht wird.

Diese APIs bestehen aus REST-Methoden, die von Entwicklern mit Add-On-Katalogen verwendet werden sollen, die von plattformübergreifenden Diensten unterstützt werden. Diese APIs ermöglichen Folgendes:

• Microsoft Store-Sammlungs-API: Fragen Sie nach Produkten ab, die einem Benutzer gehören, und melden Sie ein Verbrauchsprodukt als erfüllt.
• Microsoft Store-Einkaufs-API: Gewähren Eines kostenlosen Produkts für einen Benutzer, Abrufen von Abonnements für einen Benutzer und Ändern des Abrechnungsstatus eines Abonnements für einen Benutzer.

Hinweis

Die Microsoft Store-Sammlungs-API und -Einkaufs-API verwenden die Azure Active Directory (Azure AD)-Authentifizierung, um auf Kundenbesitzinformationen zuzugreifen. Um diese APIs verwenden zu können, müssen Sie (oder Ihre Organisation) über ein Azure AD-Verzeichnis verfügen, und Sie müssen über globale Administratorberechtigungen für das Verzeichnis verfügen. Wenn Sie Microsoft 365 oder andere Unternehmensdienste von Microsoft verwenden, verfügen Sie bereits über ein Azure AD-Verzeichnis.

Die Microsoft.StoreServices-Bibliothek

Um den Authentifizierungsfluss zu optimieren und die Microsoft Store-Dienste aufzurufen, lesen Sie das Microsoft.StoreServices-Projekt und das Beispiel auf Github. Die Microsoft.StoreServices-Bibliothek unterstützt die Verwaltung der Authentifizierungsschlüssel und stellt Wrapper-APIs bereit, um die Microsoft Store-Dienste für die Verwaltung von Produkten aufzurufen. Das Beispielprojekt hebt hervor, wie ein Dienst die Microsoft.StoreServices-Bibliothek verwenden kann, z. B. Logik für die Verwaltung von Verbrauchsprodukten, die Abstimmung von rückerstattungierten Einkäufen, die Verlängerung abgelaufener Anmeldeinformationen und vieles mehr. Eine schrittweise Konfigurationsanleitung ist im Beispiel enthalten, um den Beispieldienst auf Ihrem PC oder über Azure einzurichten.

• Microsoft.StoreServices-Bibliothek (GitHub)
• Microsoft.StoreServices-Beispiel (GitHub)

Übersicht

Die folgenden Schritte beschreiben den End-to-End-Prozess für die Verwendung der Microsoft Store-Sammlungs-API und der Einkaufs-API:

1. Konfigurieren Sie eine Anwendung in Azure AD.
2. Ordnen Sie Ihre Azure AD-Anwendungs-ID Ihrer App im Partner Center zu.
3. Erstellen Sie in Ihrem Dienst Azure AD-Zugriffstoken, die Ihre Herausgeberidentität darstellen.
4. Erstellen Sie in Ihrer Windows-Client-App einen Microsoft Store-ID-Schlüssel, der die Identität des aktuellen Benutzers darstellt, und übergeben Sie diesen Schlüssel an Ihren Dienst zurück.

Dieser End-to-End-Prozess umfasst zwei Softwarekomponenten, die unterschiedliche Aufgaben ausführen:

• Ihr Dienst. Dies ist eine Anwendung, die sicher im Kontext Ihrer Geschäftsumgebung ausgeführt wird und mit jeder von Ihnen gewählten Entwicklungsplattform implementiert werden kann. Ihr Dienst ist für das Erstellen der für das Szenario erforderlichen Azure AD-Zugriffstoken und für das Aufrufen der REST-URIs für die Microsoft Store-Sammlungs-API und -Einkaufs-API verantwortlich.
• Ihre Windows-Client-App. Dies ist die App, für die Sie auf Kundenberechtigungsinformationen zugreifen und diese verwalten möchten (einschließlich Add-Ons für die App). Diese App ist für das Erstellen der Microsoft Store-ID-Schlüssel verantwortlich, die Sie zum Aufrufen der Microsoft Store-Sammlungs-API und der Einkaufs-API von Ihrem Dienst benötigen.

Schritt 1: Konfigurieren einer Anwendung in Azure AD

Bevor Sie die Microsoft Store-Sammlungs-API oder -Einkaufs-API verwenden können, müssen Sie eine Azure AD-Webanwendung erstellen, die Mandanten-ID und Anwendungs-ID für die Anwendung abrufen und einen Schlüssel generieren. Die Azure AD-Webanwendung stellt den Dienst dar, von dem Sie die Microsoft Store-Sammlungs-API oder -Einkaufs-API aufrufen möchten. Sie benötigen die Mandanten-ID, Anwendungs-ID und den Schlüssel, um Azure AD-Zugriffstoken zu generieren, die Sie zum Aufrufen der API benötigen.

1. Wenn Sie dies noch nicht getan haben, befolgen Sie die Anweisungen in der Integration von Anwendungen in Azure Active Directory , um eine Web-App/API-Anwendung bei Azure AD zu registrieren.

   Hinweis

   Wenn Sie Ihre Anwendung registrieren, müssen Sie web app/API als Anwendungstyp auswählen, damit Sie einen Schlüssel (auch als geheimer Clientschlüssel bezeichnet) für Ihre Anwendung abrufen können. Um die Microsoft Store-Sammlungs-API oder einkaufs-API aufzurufen, müssen Sie einen geheimen Clientschlüssel angeben, wenn Sie in einem späteren Schritt ein Zugriffstoken von Azure AD anfordern.

2. Navigieren Sie im Azure-Verwaltungsportal zu Azure Active Directory. Wählen Sie Ihr Verzeichnis aus, klicken Sie im linken Navigationsbereich auf App-Registrierungen, und wählen Sie dann Ihre Anwendung aus.

3. Sie gelangen zur Hauptregistrierungsseite der Anwendung. Kopieren Sie auf dieser Seite den Anwendungs-ID-Wert für die spätere Verwendung.

4. Erstellen Sie einen Schlüssel, den Sie später benötigen (dies wird als geheimer Clientschlüssel bezeichnet). Klicken Sie im linken Bereich auf "Einstellungen" und dann auf "Schlüssel". Führen Sie auf dieser Seite die Schritte zum Erstellen eines Schlüssels aus. Kopieren Sie diesen Schlüssel zur späteren Verwendung.

Schritt 2: Zuordnen Ihrer Azure AD-Anwendungs-ID zu Ihrer Client-App im Partner Center

Bevor Sie die Microsoft Store-Sammlungs-API oder -Einkaufs-API verwenden können, um den Besitz und die Einkäufe für Ihre App oder Ihr Add-On zu konfigurieren, müssen Sie Ihre Azure AD-Anwendungs-ID der App (oder der App, die das Add-On enthält) im Partner Center zuordnen.

Hinweis

Sie müssen diese Aufgabe nur einmal ausführen. Nachdem Sie Ihre Mandanten-ID, Anwendungs-ID und geheimen Clientschlüssel besitzen, können Sie diese Werte jederzeit wiederverwenden, wenn Sie ein neues Azure AD-Zugriffstoken erstellen müssen.

1. Melden Sie sich beim Partner Center an, und wählen Sie Ihre App aus.
2. Wechseln Sie zur Seite "Diensteproduktsammlungen>und -einkäufe ", und geben Sie Ihre Azure AD-Anwendungs-ID in eines der verfügbaren Client-ID-Felder ein.

Schritt 3: Erstellen von Azure AD-Zugriffstoken

Bevor Sie einen Microsoft Store-ID-Schlüssel abrufen oder die Microsoft Store-Sammlungs-API oder -Einkaufs-API aufrufen können, muss Ihr Dienst mehrere verschiedene Azure AD-Zugriffstoken erstellen, die Ihre Herausgeberidentität darstellen. Jedes Token wird mit einer anderen API verwendet. Die Lebensdauer jedes Tokens beträgt 60 Minuten, und Sie können sie nach Ablauf aktualisieren.

Wichtig

Erstellen Sie Azure AD-Zugriffstoken nur im Kontext Ihres Diensts, nicht in Ihrer App. Ihr geheimer Clientschlüssel könnte kompromittiert werden, wenn er an Ihre App gesendet wird.

Grundlegendes zu den verschiedenen Token und Benutzergruppen-URIs

Je nachdem, welche Methoden Sie in der Microsoft Store-Sammlungs-API oder -Einkaufs-API aufrufen möchten, müssen Sie entweder zwei oder drei unterschiedliche Token erstellen. Jedes Zugriffstoken ist einem anderen Zielgruppen-URI zugeordnet.

• In allen Fällen müssen Sie ein Token mit dem https://onestore.microsoft.com Zielgruppen-URI erstellen. In einem späteren Schritt übergeben Sie dieses Token an den Autorisierungsheader der Methoden in der Microsoft Store-Sammlungs-API oder Einkaufs-API.

  Wichtig

  Verwenden Sie die https://onestore.microsoft.com Zielgruppe nur mit Zugriffstoken, die sicher in Ihrem Dienst gespeichert sind. Wenn Sie Zugriffstoken mit dieser Zielgruppe außerhalb Ihres Diensts verfügbar machen, kann Ihr Dienst anfällig für Replay-Angriffe sein.

• Wenn Sie eine Methode in der Microsoft Store-Sammlungs-API aufrufen möchten, um Produkte im Besitz eines Benutzers abzufragen oder ein Verbrauchsprodukt als erfüllt zu melden, müssen Sie auch ein Token mit dem https://onestore.microsoft.com/b2b/keys/create/collections Zielgruppen-URI erstellen. In einem späteren Schritt übergeben Sie dieses Token an eine Clientmethode im Windows SDK, um einen Microsoft Store-ID-Schlüssel anzufordern, den Sie mit der Microsoft Store-Sammlungs-API verwenden können.

• Wenn Sie eine Methode in der Microsoft Store-Einkaufs-API aufrufen möchten, um einem Benutzer ein kostenloses Produkt zu gewähren, Abonnements für einen Benutzer abzurufen oder den Abrechnungsstatus eines Abonnements für einen Benutzer zu ändern, müssen Sie auch ein Token mit dem https://onestore.microsoft.com/b2b/keys/create/purchase Zielgruppen-URI erstellen. In einem späteren Schritt übergeben Sie dieses Token an eine Clientmethode im Windows SDK, um einen Microsoft Store-ID-Schlüssel anzufordern, den Sie mit der Microsoft Store-Einkaufs-API verwenden können.

Erstellen der Token

Verwenden Sie zum Erstellen der Zugriffstoken die OAuth 2.0-API in Ihrem Dienst, indem Sie die Anweisungen in Service to Service Calls Using Client Credentials to Send an HTTP POST an den https://login.microsoftonline.com/<tenant_id>/oauth2/token Endpunkt befolgen. Hier ist eine Beispielanforderung:

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

Geben Sie für jedes Token die folgenden Parameterdaten an:

• Geben Sie für die Parameter client_id und client_secret die Anwendungs-ID und den geheimen Clientschlüssel für Ihre Anwendung an, die Sie aus dem Azure-Verwaltungsportal abgerufen haben. Beide Parameter sind erforderlich, um ein Zugriffstoken mit der Authentifizierungsebene zu erstellen, die von der Microsoft Store-Sammlungs-API oder einkaufs-API benötigt wird.

• Geben Sie für den Ressourcenparameter je nach Typ des erstellten Zugriffstokens eine der im vorherigen Abschnitt aufgeführten Benutzergruppen-URIs an.

Nachdem Ihr Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie die anweisungen hier befolgen. Weitere Informationen zur Struktur eines Zugriffstokens finden Sie unter "Unterstützte Token- und Anspruchstypen".

Schritt 4: Erstellen eines Microsoft Store-ID-Schlüssels

Bevor Sie eine beliebige Methode in der Microsoft Store-Sammlungs-API oder -Einkaufs-API aufrufen können, muss Ihre App einen Microsoft Store-ID-Schlüssel erstellen und an Ihren Dienst senden. Dieser Schlüssel ist ein JSON-Webtoken (JWT), das die Identität des Benutzers darstellt, auf dessen Produktbesitzinformationen Sie zugreifen möchten. Weitere Informationen zu den Ansprüchen in diesem Schlüssel finden Sie unter "Ansprüche" in einem Microsoft Store-ID-Schlüssel.

Derzeit besteht die einzige Möglichkeit zum Erstellen eines Microsoft Store-ID-Schlüssels darin, eine Universelle Windows-Plattform -API (UWP) aus Clientcode in Ihrer App aufzurufen. Der generierte Schlüssel stellt die Identität des Benutzers dar, der aktuell beim Microsoft Store auf dem Gerät angemeldet ist.

Hinweis

Jeder Microsoft Store-ID-Schlüssel ist 90 Tage lang gültig. Nach Ablauf eines Schlüssels können Sie den Schlüssel verlängern. Es wird empfohlen, Ihre Microsoft Store-ID-Schlüssel zu verlängern, anstatt neue zu erstellen.

So erstellen Sie einen Microsoft Store-ID-Schlüssel für die Microsoft Store-Sammlungs-API

Führen Sie die folgenden Schritte aus, um einen Microsoft Store-ID-Schlüssel zu erstellen, den Sie mit der Microsoft Store-Sammlungs-API verwenden können, um Produkte abzufragen, die einem Benutzer gehören, oder ein Verbrauchsprodukt als erfüllt melden.

1. Übergeben Sie das Azure AD-Zugriffstoken mit dem Zielgruppen-URI-Wert https://onestore.microsoft.com/b2b/keys/create/collections von Ihrem Dienst an Ihre Client-App. Dies ist eines der Token, die Sie zuvor in Schritt 3 erstellt haben.

2. Rufen Sie in Ihrem App-Code eine der folgenden Methoden auf, um einen Microsoft Store-ID-Schlüssel abzurufen:

• Wenn Ihre App die StoreContext-Klasse im Windows.Services.Store Namespace zum Verwalten von In-App-Käufen verwendet, verwenden Sie die StoreContext.GetCustomerCollectionsIdAsync-Methode .

• Wenn Ihre App die CurrentApp-Klasse im Windows.ApplicationModel.Store Namespace zum Verwalten von In-App-Käufen verwendet, verwenden Sie die CurrentApp.GetCustomerCollectionsIdAsync-Methode .

  Übergeben Sie Ihr Azure AD-Zugriffstoken an den ServiceTicket-Parameter der Methode. Wenn Sie anonyme Benutzer-IDs im Kontext von Diensten verwalten, die Sie als Herausgeber der aktuellen App verwalten, können Sie auch eine Benutzer-ID an den parameter publisherUserId übergeben, um den aktuellen Benutzer dem neuen Microsoft Store-ID-Schlüssel zuzuordnen (die Benutzer-ID wird in den Schlüssel eingebettet). Andernfalls können Sie einen beliebigen Zeichenfolgenwert an den publisherUserId-Parameter übergeben, wenn Sie dem Microsoft Store-ID-Schlüssel keine Benutzer-ID zuordnen müssen.

3. Nachdem Ihre App erfolgreich einen Microsoft Store-ID-Schlüssel erstellt hat, übergeben Sie den Schlüssel an Ihren Dienst zurück.

So erstellen Sie einen Microsoft Store-ID-Schlüssel für die Microsoft Store-Einkaufs-API

Führen Sie die folgenden Schritte aus, um einen Microsoft Store-ID-Schlüssel zu erstellen, den Sie mit der Microsoft Store-Einkaufs-API verwenden können, um einem Benutzer ein kostenloses Produkt zu gewähren, Abonnements für einen Benutzer abzurufen oder den Abrechnungsstatus eines Abonnements für einen Benutzer zu ändern.

1. Übergeben Sie das Azure AD-Zugriffstoken mit dem Zielgruppen-URI-Wert https://onestore.microsoft.com/b2b/keys/create/purchase von Ihrem Dienst an Ihre Client-App. Dies ist eines der Token, die Sie zuvor in Schritt 3 erstellt haben.

2. Rufen Sie in Ihrem App-Code eine der folgenden Methoden auf, um einen Microsoft Store-ID-Schlüssel abzurufen:

• Wenn Ihre App die StoreContext-Klasse im Windows.Services.Store Namespace zum Verwalten von In-App-Käufen verwendet, verwenden Sie die StoreContext.GetCustomerPurchaseIdAsync-Methode .

• Wenn Ihre App die CurrentApp-Klasse im Windows.ApplicationModel.Store Namespace zum Verwalten von In-App-Käufen verwendet, verwenden Sie die CurrentApp.GetCustomerPurchaseIdAsync-Methode .

  Übergeben Sie Ihr Azure AD-Zugriffstoken an den ServiceTicket-Parameter der Methode. Wenn Sie anonyme Benutzer-IDs im Kontext von Diensten verwalten, die Sie als Herausgeber der aktuellen App verwalten, können Sie auch eine Benutzer-ID an den parameter publisherUserId übergeben, um den aktuellen Benutzer dem neuen Microsoft Store-ID-Schlüssel zuzuordnen (die Benutzer-ID wird in den Schlüssel eingebettet). Andernfalls können Sie einen beliebigen Zeichenfolgenwert an den publisherUserId-Parameter übergeben, wenn Sie dem Microsoft Store-ID-Schlüssel keine Benutzer-ID zuordnen müssen.

3. Nachdem Ihre App erfolgreich einen Microsoft Store-ID-Schlüssel erstellt hat, übergeben Sie den Schlüssel an Ihren Dienst zurück.

Diagramm

Das folgende Diagramm veranschaulicht das Erstellen eines Microsoft Store-ID-Schlüssels.

Ansprüche in einem Microsoft Store-ID-Schlüssel

Ein Microsoft Store-ID-Schlüssel ist ein JSON-Webtoken (JWT), das die Identität des Benutzers darstellt, auf dessen Produktbesitzinformationen Sie zugreifen möchten. Wenn sie mit Base64 decodiert werden, enthält ein Microsoft Store-ID-Schlüssel die folgenden Ansprüche.

• iat: Gibt den Zeitpunkt an, zu dem der Schlüssel ausgestellt wurde. Dieser Anspruch kann verwendet werden, um das Alter des Tokens zu bestimmen. Dieser Wert wird als Epoche ausgedrückt.
• iss: Identifiziert den Aussteller. Dies hat denselben Wert wie der aud Anspruch.
• aud: Identifiziert die Zielgruppe. Muss einer der folgenden Werte sein: https://collections.mp.microsoft.com/v6.0/keys oder https://purchase.mp.microsoft.com/v6.0/keys.
• exp: Gibt die Ablaufzeit an oder nach der der Schlüssel nicht mehr für die Verarbeitung von Schlüsseln akzeptiert wird, mit Ausnahme der Verlängerung von Schlüsseln. Der Wert dieses Anspruchs wird als Epoche ausgedrückt.
• nbf: Gibt den Zeitpunkt an, zu dem das Token zur Verarbeitung akzeptiert wird. Der Wert dieses Anspruchs wird als Epoche ausgedrückt.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: Die Client-ID, die den Entwickler identifiziert.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: Eine undurchsichtige Nutzlast (verschlüsselt und Base64-codiert), die Informationen enthält, die nur für die Verwendung durch Microsoft Store-Dienste vorgesehen sind.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: Eine Benutzer-ID, die den aktuellen Benutzer im Kontext Ihrer Dienste identifiziert. Dies ist derselbe Wert, den Sie an den optionalen publisherUserId-Parameter der Methode übergeben, die Sie zum Erstellen des Schlüssels verwenden.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: Der URI, den Sie zum Verlängern des Schlüssels verwenden können.

Hier ist ein Beispiel für einen decodierten Microsoft Store-ID-Schlüsselheader.

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

Hier ist ein Beispiel für einen decodierten Microsoft Store ID-Schlüsselanspruchssatz.

{
    "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": 1442395542,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1450171541,
    "nbf": 1442391941
}

Zugehörige Themen

• Produktabfrage
• Melden von Verbrauchsartikeln als erfüllt
• Gewähren kostenloser Produkte
• Abrufen von Abonnements für einen Benutzer
• Ändern des Abrechnungsstatus eines Abonnements für einen Benutzer
• Verlängern eines Microsoft Store-ID-Schlüssels
• Integrieren von Anwendungen in Azure Active Directory
• Grundlegendes zum Azure Active Directory-Anwendungsmanifest
• Unterstützte Token- und Anspruchstypen
• Microsoft.StoreServices-Bibliothek (GitHub)