Zugreifen auf Analysedaten mit Store Diensten

Verwenden Sie die Microsoft Store Analytics-API, um Analysedaten für Apps programmgesteuert abzurufen, die beim Windows Partner Center-Konto Ihrer Organisation registriert sind. Mit dieser API können Sie Daten zum Kauf von Apps und Add-Ons (auch als In-App-Produkte (IAPs) bezeichnet), Fehler, App-Bewertungen und App-Rezensionen abrufen. Diese API verwendet Azure Active Directory (Azure AD), um die Aufrufe von Ihrer App oder Ihrem Dienst zu authentifizieren.

Dazu müssen folgende Schritte ausgeführt werden:

  1. Stellen Sie sicher, dass Sie alle Voraussetzungen erfüllt haben.
  2. Bevor Sie eine Methode in der Microsoft Store Analytics-API aufrufen, rufen Sie ein Azure AD Zugriffstokenab. Nachdem Sie ein Token erhalten haben, haben Sie 60 Minuten Zeit, dieses Token in Aufrufen der Microsoft Store Analytics-API zu verwenden, bevor das Token abläuft. Nach dem Ablauf des Tokens können Sie ein neues Token generieren.
  3. Rufen Sie die Microsoft Store Analytics-APIauf.

Schritt 1: Abschließen der Voraussetzungen für die Verwendung der Microsoft Store Analytics-API

Bevor Sie mit dem Schreiben von Code zum Aufrufen der Microsoft Store Analytics-API beginnen, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllt haben.

  • Sie (oder Ihre Organisation) müssen über ein Azure AD-Verzeichnis verfügen, und Ihnen müssen die Berechtigungen globaler Administrator für das Verzeichnis gewährt worden sein. Wenn Sie Microsoft 365 oder andere Unternehmensdienste von Microsoft verwenden, verfügen Sie bereits über ein Azure AD-Verzeichnis. Andernfalls können Sie in Partner Center ohne zusätzliche Kosten eine neue Azure AD erstellen.

  • Sie müssen Ihrem Partner Center-Konto eine Azure AD Anwendung zuordnen, die Mandanten-ID und die Client-ID für die Anwendung abrufen und einen Schlüssel generieren. Die Azure AD-Anwendung stellt die App oder den Dienst dar, von der aus Sie die Microsoft Store Analytics-API aufrufen möchten. Sie benötigen die Mandanten-ID, die Client-ID und den Schlüssel, um ein Azure AD-Zugriffstoken zu erhalten, das Sie an die API übergeben.

    Hinweis

    Sie müssen diese Aufgabe nur einmal ausführen. Nachdem Sie über die Mandanten-ID, die Client-ID und den Schlüssel verfügen, können Sie diese jederzeit wiederverwenden, wenn Sie ein neues Azure AD-Zugriffstoken erstellen müssen.

So ordnen Sie Ihrem Partner Center-Konto eine Azure AD Anwendung zu und rufen die erforderlichen Werte ab:

  1. Verknüpfen Sie in Partner Center das Partner Center-Konto Ihres Unternehmens mit dem Azure AD-Verzeichnis Ihrer Organisation.

  2. Fügen Sie als Nächstes auf der Seite Benutzer im Abschnitt Kontoeinstellungen von Partner Center die Azure AD Anwendung hinzu, die die App oder den Dienst darstellt, die Bzw. den Sie für den Zugriff auf Analysedaten für Ihr Partner Center-Konto verwenden. Stellen Sie sicher, dass Sie dieser Anwendung die Rolle Manager zuweisen. Wenn die Anwendung noch nicht in Ihrem Azure AD-Verzeichnis vorhanden ist, können Sie in Partner Center eine neue Azure AD-Anwendung erstellen.

  3. Kehren Sie zur Seite Benutzer zurück, klicken Sie auf den Namen Ihrer Azure AD-Anwendung, um die Anwendungseinstellungen zu öffnen, und schreiben Sie die Werte Mandanten-ID und Client-ID auf.

  4. Klicken Sie auf Neuen Schlüssel hinzufügen. Notieren Sie auf dem folgenden Bildschirm den Wert von Schlüssel. Nachdem Sie diese Seite verlassen haben, können Sie nicht mehr auf diese Informationen zugreifen. Weitere Informationen finden Sie unter Verwalten von Schlüsseln für eine Azure AD-Anwendung.

Schritt 2: Abrufen eines Azure AD-Zugriffstokens

Bevor Sie eine der Methoden in der Microsoft Store Analytics-API aufrufen, müssen Sie zunächst ein Azure AD Zugriffstoken abrufen, das Sie an den Autorisierungsheader jeder Methode in der API übergeben. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft. Nachdem das Token abgelaufen ist, können Sie es aktualisieren, um es in weiteren Aufrufen an die API zu verwenden.

Befolgen Sie zum Abrufen des Zugriffstokens die Anweisungen unter Aufrufe zwischen Diensten mithilfe von Clientanmeldeinformationen, um eine HTTP POST-Anforderung 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://manage.devcenter.microsoft.com

Geben Sie für den _ Mandanten-ID-Wert im POST-URI und die Parameter _ client-ID und geheimer _ Clientschlüssel die Mandanten-ID, die Client-ID und den Schlüssel für Ihre Anwendung an, die Sie im vorherigen Abschnitt aus Partner Center abgerufen haben. Für den Parameter resource müssen Sie https://manage.devcenter.microsoft.com angeben.

Nachdem das Zugriffstoken abgelaufen ist, können Sie es aktualisieren, indem Sie diese Anleitung befolgen.

Schritt 3: Aufrufen der Microsoft Store Analytics-API

Nachdem Sie über ein Azure AD Zugriffstoken verfügen, können Sie die Microsoft Store Analytics-API aufrufen. Sie müssen das Zugriffstoken an den Authorization-Header der einzelnen Methoden übergeben.

Methoden für UWP-Apps und -Spiele

Die folgenden Methoden sind für Apps- und Spielekäufe und Add-On-Übernahmen verfügbar:

Methoden für UWP-Apps

Die folgenden Analysemethoden sind für UWP-Apps in Partner Center verfügbar.

Szenario Methoden
Erwerbe, Konvertierungen, Installationen und Nutzung
App-Fehler
Einblicke
Bewertungen und Rezensionen
In-App-Anzeigen und Werbekampagnen

Methoden für Desktopanwendungen

Die folgenden Analysemethoden können von Entwicklerkonten verwendet werden, die zum Windows Desktopanwendungsprogrammgehören.

Szenario Methoden
Installiert
Blöcke
Anwendungsfehler
Einblicke

Methoden für Xbox Live Dienste

Die folgenden zusätzlichen Methoden können von Entwicklerkonten mit Spielen verwendet werden, die Xbox Live Diensteverwenden.

Szenario Methoden
Allgemeine Analysen
Integritätsanalysen
Community Analytics

Methoden für Hardware und Treiber

Entwicklerkonten, die zum Windows Hardwaredashboard-Programm gehören, haben Zugriff auf einen zusätzlichen Satz von Methoden zum Abrufen von Analysedaten für Hardware und Treiber. Weitere Informationen finden Sie unter Hardwaredashboard-API.

Codebeispiel

Im folgenden Codebeispiel wird veranschaulicht, wie Sie Azure AD Zugriffstoken abrufen und die Microsoft Store Analytics-API aus einer C#-Konsolen-App aufrufen. Wenn Sie dieses Codebeispiel verwenden möchten, weisen Sie die Variablen TenantId, ClientId, ClientSecret und AppID den entsprechenden Werten für Ihr Szenario zu. Für dieses Beispiel muss Json.NET Newtonsoft-Paket verwenden, um die json-Daten zu deserialisieren, die von der Microsoft Store Analytics-API zurückgegeben werden.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestAnalyticsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            // This is your app's Store ID. This ID is available on
            // the App identity page of the Dev Center dashboard.
            string appID = "<your app's Store ID>";

            DateTime startDate = DateTime.Parse("08-01-2015");
            DateTime endDate = DateTime.Parse("11-01-2015");
            int pageSize = 1000;
            int startPageIndex = 0;

            // Call the Windows Store analytics API
            CallAnalyticsAPI(accessToken, appID, startDate, endDate, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallAnalyticsAPI(string accessToken, string appID, DateTime startDate, DateTime endDate, int top, int skip)
        {
            string requestURI;

            // Get app acquisitions
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
                appID, startDate, endDate, top, skip);

            //// Get add-on acquisitions
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app failures
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/failurehits?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app ratings
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?applicationId={0}&startDate={1}&endDate={2}top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app reviews
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/reviews?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&client_id={0}&client_secret={1}&resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}

Fehlercodes

Die Microsoft Store Analytics-API gibt Fehlerantworten in einem JSON-Objekt zurück, das Fehlercodes und Meldungen enthält. Im folgenden Beispiel wird eine Fehlerantwort veranschaulicht, die durch einen ungültigen Parameter bewirkt wurde.

{
    "code":"BadRequest",
    "data":[],
    "details":[],
    "innererror":{
        "code":"InvalidQueryParameters",
        "data":[
            "top parameter cannot be more than 10000"
        ],
        "details":[],
        "message":"One or More Query Parameters has invalid values.",
        "source&quot;:&quot;AnalyticsAPI"
    },
    "message":"The calling client sent a bad request to the service.",
    "source&quot;:&quot;AnalyticsAPI"
}