Verwalten von Einnahmen mithilfe der Ertragsdienst-API

In diesem Artikel wird erläutert, wie Sie über die Einnahmen-APIs anstelle der Partner Center-Benutzeroberfläche auf Ergebnisdaten zugreifen können. Diese APIs bieten eine programmgesteuerte Möglichkeit, die Funktion des Features " Daten exportieren " im Partner Center bereitzustellen.

Verfügbare APIs

Alle verfügbaren APIs bei Partnerauszahlungen anzeigen.

Voraussetzungen

• Sie haben ein Arbeitsabonnement im Azure-Portal.
• Zugriff auf einen Webbrowser haben.
• Sie können REST-API-Aufrufe entweder programmgesteuert oder über dedizierte Software durchführen.

Registrieren einer Anwendung bei Microsoft Identity Platform

1. Befolgen Sie die Anweisungen zum Erstellen einer App-Registrierung mit Microsoft Identity Platform.

2. Weisen Sie der App entsprechende delegierte Berechtigungen zu.

   1. Wechseln Sie in der neu erstellten App-Registrierung zu "Verwalten → API-Berechtigungen". Wählen Sie "Berechtigung hinzufügen" aus.
   2. Wählen Sie die Registerkarte "APIs, die meine Organisation verwendet", und suchen Sie dann die AppId "4990cffe-04e8-4e8b-808a-1175604b879f" oder nach dem Namen "Microsoft Dev Center". Wählen Sie für Berechtigungen "user_impersonation" aus. Wählen Sie "Berechtigungen hinzufügen" aus.
      • Problembehandlung: Wenn die Suche nach der Dev Center-API keine Ergebnisse zurückgibt, müssen Sie möglicherweise die Dienstprinzipale erstellen, die für den manuellen Zugriff auf diese APIs erforderlich sind. Sie können mit AzCLI erstellt werden:

        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        

        Anschließend sollten die API-Berechtigungen zur Auswahl im Suchdialogfeld verfügbar sein.
   3. Stellen Sie darüber hinaus sicher, dass Ihre App über eine Berechtigung "User.Read" in Microsoft Graph verfügt. Andernfalls fügen Sie es hinzu, indem Sie Microsoft Graph auf der Registerkarte "Microsoft-APIs" auswählen.
   4. Wählen Sie "Administratorzustimmung erteilen" für alle drei Berechtigungen aus, die Sie erhalten haben.
   5. Ihre App-Berechtigungen sollten wie folgt aussehen (beachten Sie das grüne Teilstrich neben den einzelnen

3. Richten Sie einen Umleitungs-URI für die Webplattform ein.

   1. Wechseln Sie zu Verwalten → Authentifizierung. Wählen Sie "Plattform hinzufügen" aus.
   2. Wählen Sie "Web" aus.
   3. Geben Sie in Umleitungs-URIs den URI ein, den Sie für Ihre Anwendung verwenden möchten, z. B. https://localhost:3000. Notieren Sie sich diesen URI für später. Drücken Sie "Konfigurieren".

4. Generieren Sie einen geheimen Clientschlüssel, der beim Abrufen von Zugriffstoken verwendet werden soll.

   1. Wechseln Sie zu Verwalten von → Zertifikaten und geheimen Schlüsseln. Wechseln Sie zur Registerkarte "Geheime Clientschlüssel", und wählen Sie "Neuer geheimer Clientschlüssel" aus.
   2. Geben Sie den gewünschten Namen und die gewünschte Dauer ein.
   3. Wählen Sie "Geheimen Schlüssel hinzufügen" aus.
   4. Notieren Sie sich den Wert an einer anderen Stelle. Achten Sie darauf, sie an einem sicheren Ort zu speichern, z. B. einen Schlüsseltresor. Sie verwenden diesen geheimen Schlüssel, wenn Sie AccessToken und RefreshToken anfordern.

Zugriffstoken abrufen – MFA-fähige Konten

Für die Earnings-APIs muss ein AccessToken als Autorisierungs-Bearer-Token in der Anforderung mit dem Präfix Bearer <access-token> im Autorisierungsheader bereitgestellt werden. Sie können dieses Token abrufen, indem Sie sich mit Ihrem Konto anmelden; Zugriffstoken sind jedoch kurzlebig. Die Anmeldung bei einem MFA-fähigen Konto, um jedes Mal ein Token zu generieren, wenn Sie die API aufrufen müssen, ist für Workflows mit Automatisierung nicht praktikabel. Diese Schritte führen Sie durch den Prozess, um ein RefreshToken zu generieren. Es hat eine längere Lebensdauer (ca. 3 Monate) und kann verwendet werden, um das AccessToken abzurufen. Indem Sie ein RefreshToken an einem sicheren Speicherort speichern, können Sie es verwenden, um ein AccessToken programmgesteuert abzurufen, um die Einnahmen-API aufzurufen. Hinweis: RefreshToken kann nur einmal verwendet werden, danach wird es veraltet. In der Antwort wird ein neues RefreshToken zusammen mit dem AccessToken zurückgegeben. Stellen Sie sicher, dass Sie den alten Wert von RefreshToken in Ihrem sicheren Speicher jedes Mal ersetzen, wenn Sie ein RefreshToken verwenden.

1. Rufen Sie AuthCode über den Browser ab. Derzeit muss dieser Vorgang mithilfe der Benutzeroberfläche eines Webbrowsers erfolgen und kann nicht programmgesteuert ausgeführt werden.

   1. Folgen Sie der Vorlage hier , um eine URL zu erstellen, die zum Abrufen des AuthCode verwendet wird.
      1. Verwenden Sie Mandanten-ID und Client-ID für die erstellte Anwendung.
      2. Legen Sie den Bereich auf https://api.partner.microsoft.com/.default.
      3. Setzen Sie die Umleitungs-URL auf die zuvor konfigurierte Umleitungs-URL. Die URL-Vorlage lautet: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
   2. Wechseln Sie zur integrierten URL, und melden Sie sich mit den Anmeldeinformationen eines autorisierten Benutzers an.
   3. Bei erfolgreicher Anmeldung versucht Ihr Browser, eine URL des Formats <redirect-uri>/?code=<auth-code>&session_state=<state-id>#zu öffnen. Für das Umleitungs-URI-Beispiel in einem vorherigen Schritt sollte die URL, an die Sie gesendet werden, sein https://localhost:3000/?code=<auth-code>?session_state=<state-id>#. Speichern Sie den zurückgegebenen AuthCode an einem sicheren Ort.
      • Da in der Regel keine App auf localhost:3000 lauscht, gibt der Browser eine Fehlermeldung "Keine Verbindung herstellen" aus. Dieser Fehler wird erwartet, da wir nur den AuthCode-Wert manuell aus dem code zuvor gezeigten URL-Abfrageparameter kopieren müssen.
      • In einer Prod-Lösung kann eine App erstellt werden, die diesen Teil des Authentifizierungsprozesses automatisch verarbeitet. Beispielsweise könnte es sich um einen Workflow handeln, in dem der Benutzer zu einer Einzelseitenanwendung (SINGLE Page Application, SPA) wechselt. Der Benutzer wählt eine Schaltfläche "Anmelden" aus, mit der sie zur zuvor erstellten URL gelangen. Bei der Anmeldung extrahiert der SPA den Wert des AuthCode und speichert ihn in einem Tresor. Die SPA verwendet dann AuthCode, um RefreshToken und AccessToken abzurufen, wie in den nächsten Schritten beschrieben.

2. Verwenden Sie AuthCode , um RefreshToken und anfängliches AccessToken abzurufen. Hinweis: RefreshToken läuft alle 3 Monate ab und muss erneut bezogen und in einem Schlüsseltresor gespeichert werden.

   1. Erstellen Sie eine POST-API-Anforderung nach der hier bereitgestellten Vorlage.
      1. Verwenden Sie dieselben Werte für Mandanten-/Client-ID und Umleitungs-URL.
      2. Legen Sie den Bereich auf https://api.partner.microsoft.com/.default offline_access.
      3. Setzen Sie den Code auf den im Schritt zuvor abgerufenen AuthCode.
      4. Legen Sie client_secret auf den geheimen Schlüssel fest, der für die erstellte Anwendung generiert wurde. Die URL sollte dann wie folgt strukturiert sein: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

3. Später können Sie RefreshToken verwenden, um neues AccessToken abzurufen.

   1. Erstellen Sie eine POST-API-Anforderung nach der hier bereitgestellten Vorlage.
      1. Verwenden Sie dieselben Werte für Mandanten-/Client-ID und Umleitungs-URL.
      2. Bereich festlegen auf https://api.partner.microsoft.com/.default
      3. Legen Sie refresh_token auf das RefreshToken fest, das im vorherigen Schritt abgerufen wurde.
      4. Legen Sie client_secret auf den geheimen Schlüssel fest, der für die erstellte Anwendung generiert wurde.

Zugriffstoken abrufen – Nicht-MFA-Konten

1. Rufen Sie AccessToken unter Verwendung der Informationen zur neuen App-Registrierung ab.
   1. Erstellen Sie eine POST-API-Anforderung nach der hier bereitgestellten Vorlage.
      1. Verwenden Sie dieselben Werte für Mandanten-/Client-ID.
      2. Legt den Bereich auf https://api.partner.microsoft.com/.default fest
      3. Verwenden Sie den Benutzernamen/das Kennwort für einen autorisierten Benutzer. Die URL sollte dann wie folgt strukturiert sein: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
   2. Die Anforderung gibt AccessToken und ein neues RefreshToken zurück. Achten Sie darauf, den gespeicherten Wert für das RefreshToken zu aktualisieren, da Sie den alten Wert nicht mehr verwenden können.

Anrufverdienste (vormals Transaktionshistorie)/Zahlungen

• Verwenden Sie das zuvor im Autorisierungsheader erhaltene AccessToken mit dem Präfix Bearer <access-token> , um neue Einnahmen (ehemals Transaktionstheorie) oder Zahlungsberichte zu erstellen.

Verwandte Inhalte

• Verwenden des Portals zum Erstellen einer Microsoft Entra-Anwendung und eines Dienstprinzipals, der auf Ressourcen zugreifen kann
• Registrieren einer Anwendung bei Microsoft Identity Platform
• Konfigurieren einer Clientanwendung für den Zugriff auf eine Web-API