Verwalten von Produktansprüchen aus einem Dienst

  • Artikel

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 über Ihre Dienste auf Berechtigungsinformationen für diese Produkte 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.

Die APIs bestehen aus REST-Methoden, die für Entwickler mit Add-On-Katalogen konzipiert sind, die von plattformübergreifenden Diensten unterstützt werden. Diese APIs bieten folgende Möglichkeiten:

Hinweis

Die Microsoft Store-Sammlungs-API und die Kauf-API verwenden die Azure Active Directory-Authentifizierung (Azure AD), um auf Kundenbesitzinformationen zuzugreifen. Um diese APIs verwenden zu können, benötigen Sie (oder Ihre organization) ein Azure AD-Verzeichnis und globaler Administrator Berechtigung für das Verzeichnis. Wenn Sie Microsoft 365 oder andere Unternehmensdienste von Microsoft verwenden, verfügen Sie bereits über ein Azure AD-Verzeichnis.

Die Microsoft.StoreServices-Bibliothek

Informationen zum Optimieren des Authentifizierungsablaufs und zum Aufrufen der Microsoft Store-Dienste finden Sie im Projekt Microsoft.StoreServices und im Beispiel auf GitHub. Die Microsoft.StoreServices-Bibliothek hilft bei der Verwaltung der Authentifizierungsschlüssel und stellt Wrapper-APIs zum Aufrufen der Microsoft Store-Dienste zum Verwalten von Produkten bereit. Das Beispielprojekt zeigt, wie ein Dienst die Microsoft.StoreServices-Bibliothek verwenden kann, z. B. Logik für die Verwaltung von Verbrauchsprodukten, das Abgleichen von erstattungsfähigen Käufen, das Verlängern abgelaufener Anmeldeinformationen und vieles mehr. Das Beispiel enthält eine schrittweise Konfigurationsanleitung zum Einrichten des Beispieldiensts auf Ihrem PC oder über Azure.

Übersicht

In den folgenden Schritten wird der End-to-End-Prozess für die Verwendung der Microsoft Store-Sammlungs-API und der Kauf-API beschrieben:

  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 zurück an Ihren Dienst.

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 die Erstellung der für das Szenario erforderlichen Azure AD-Zugriffstoken und für den Aufruf der REST-URIs für die Microsoft Store-Sammlungs-API und die Kauf-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 die Erstellung der Microsoft Store-ID-Schlüssel verantwortlich, die Sie benötigen, um die Microsoft Store-Sammlungs-API aufzurufen und die API von Ihrem Dienst zu erwerben.

Schritt 1: Konfigurieren einer Anwendung in Azure AD

Bevor Sie die Microsoft Store-Sammlungs-API oder die Kauf-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, über den Sie die Microsoft Store-Sammlungs-API oder die Kauf-API aufrufen möchten. Sie benötigen die Mandanten-ID, die 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 unter Integrieren 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 die Kauf-API aufrufen zu können, 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 Standard Registrierungsseite der Anwendung. Kopieren Sie auf dieser Seite den Wert der Anwendungs-ID zur späteren Verwendung.

  4. Erstellen Sie einen Schlüssel, den Sie später benötigen (dies wird alles 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 in Partner Center

Bevor Sie die Microsoft Store-Sammlungs-API oder die Kauf-API verwenden können, um den Besitz und die Kä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) in Partner Center zuordnen.

Hinweis

Sie müssen diese Aufgabe nur einmal ausführen. Nachdem Sie über Ihre Mandanten-ID, Anwendungs-ID und den geheimen Clientschlüssel verfügen, 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 ServicesProduct collections and purchases (Services> Product Collections and Purchases), und geben Sie Ihre Azure AD-Anwendungs-ID in eines der verfügbaren Felder für Client-ID ein.

Schritt 3: Erstellen von Azure AD-Zugriffstoken

Bevor Sie einen Microsoft Store-ID-Schlüssel abrufen oder die Microsoft Store-Sammlungs-API oder die Kauf-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. Jedes Token ist 60 Minuten gültig und kann nach Ablauf aktualisiert werden.

Wichtig

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

Grundlegendes zu den verschiedenen Token und Zielgruppen-URIs

Je nachdem, welche Methoden Sie in der Microsoft Store-Sammlungs-API oder kauf-API aufrufen möchten, müssen Sie entweder zwei oder drei verschiedene 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 kauf-API.

    Wichtig

    Verwenden Sie die https://onestore.microsoft.com Zielgruppe nur mit Zugriffstoken, die sicher in Ihrem Dienst gespeichert sind. Durch das Verfügbarmachen von Zugriffstoken mit dieser Zielgruppe außerhalb Ihres Diensts kann er anfällig für Replay-Angriffe werden.

  • Wenn Sie eine Methode in der Microsoft Store-Sammlungs-API aufrufen möchten, um Produkte abzufragen, die sich im Besitz eines Benutzers befinden , oder ein Verbrauchsprodukt als erfüllt melden möchten, 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 zu erhalten 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

Um die Zugriffstoken zu erstellen, verwenden Sie die OAuth 2.0-API in Ihrem Dienst, indem Sie die Anweisungen unter Dienst-zu-Dienst-Aufrufe mit Clientanmeldeinformationen befolgen, um einen HTTP POST an den https://login.microsoftonline.com/<tenant_id>/oauth2/token Endpunkt zu senden. Hier ist ein Beispiel für eine Anforderung angegeben.

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 für die Microsoft Store-Sammlungs-API oder die Kauf-API erforderlich ist.

  • Geben Sie für den Ressourcenparameter je nach Art des Zugriffstokens, das Sie erstellen, eine der im vorherigen Abschnitt aufgeführten Zielgruppen-URIs an.

Nachdem das Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie diese Anleitung 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 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. Bei diesem Schlüssel handelt es sich um 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 Dem Clientcode in Ihrer App aufzurufen. Der generierte Schlüssel stellt die Identität des Benutzers dar, der derzeit beim Microsoft Store auf dem Gerät angemeldet ist.

Hinweis

Jeder Microsoft Store-ID-Schlüssel ist 90 Tage lang gültig. Nach dem Ablauf eines Schlüssels können Sie den Schlüssel verlängern. Es wird empfohlen, Dass Sie Ihre Microsoft Store-ID-Schlüssel erneuern, 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 sich im Besitz eines Benutzers befinden , oder ein Verbrauchsprodukt als erfüllt melden können.

  1. Übergeben Sie das Azure AD-Zugriffstoken, das über den Zielgruppen-URI-Wert https://onestore.microsoft.com/b2b/keys/create/collections von Ihrem Dienst verfügt, 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 verwendet, um In-App-Käufe zu verwalten, 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 publisherUserId-Parameter übergeben, um dem aktuellen Benutzer den 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.

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

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

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

  1. Übergeben Sie das Azure AD-Zugriffstoken, das über den Zielgruppen-URI-Wert https://onestore.microsoft.com/b2b/keys/create/purchase verfügt, 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 publisherUserId-Parameter übergeben, um dem aktuellen Benutzer den 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.

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

Diagramm

Das folgende Diagramm veranschaulicht den Prozess zum Erstellen eines Microsoft Store-ID-Schlüssels.

Erstellen eines Windows 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 mithilfe von Base64 decodiert wird, enthält ein Microsoft Store-ID-Schlüssel die folgenden Ansprüche.

  • iat: Gibt den Zeitpunkt an, zu dem der Schlüssel ausgestellt wurde. Mit diesem Anspruch kann das Alter des Tokens bestimmt werden. Dieser Wert wird als Epoche ausgedrückt.
  • iss: Identifiziert den Aussteller. Dies hat den gleichen Wert wie der aud Anspruch.
  • aud: Identifiziert die Zielgruppe. Muss einem der folgenden Werte entsprechen: https://collections.mp.microsoft.com/v6.0/keys oder https://purchase.mp.microsoft.com/v6.0/keys.
  • exp: Gibt die Ablaufzeit für oder an, nach der der Schlüssel nicht mehr für die Verarbeitung von Schlüsseln akzeptiert wird. Der Wert dieses Anspruchs wird als Epoche ausgedrückt.
  • nbf: Gibt den Zeitpunkt an, zu dem das Token für die 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 der gleiche 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 Erneuern des Schlüssels verwenden können.

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

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

Hier sehen Sie ein Beispiel für einen decodierten Anspruchssatz für microsoft Store-ID-Schlüssel.

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