Freigeben über

Abrufen der monatlichen App-Nutzung

  • Artikel

Verwenden Sie diese Methode in der Microsoft Store-Analyse-API, um aggregierte Nutzungsdaten (nicht einschließlich Xbox Multiplayer) im JSON-Format für eine Anwendung während eines bestimmten Zeitraums (nur letzte 90 Tage) und andere optionale Filter abzurufen. Diese Informationen sind auch im Nutzungsbericht im Partner Center verfügbar.

Telemetrie für anaheimbasierte PWA-Apps wird auf Geräteebene erfasst. Metriken im Zusammenhang mit Benutzern stehen daher für solche Produkte nicht zur Verfügung. Weitere Informationen zur Gültigkeit von Feldern finden Sie im folgenden Abschnitt "Nutzungswerte".

Voraussetzungen

Um diese Methode zu verwenden, müssen Sie zuerst Folgendes tun:

  • Falls noch nicht geschehen, erfüllen Sie alle Voraussetzungen für die Microsoft Store-Analyse-API.
  • Rufen Sie ein Azure AD-Zugriffstoken ab, das im Anforderungsheader für diese Methode verwendet wird. 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 eine neue abrufen.

Anfordern

Anforderungssyntax

Methode Anforderungs-URI
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly

Anforderungsheader

Header Typ Beschreibung
Autorisierung Zeichenfolge Erforderlich. Das Azure AD-Zugriffstoken im Formular Bearer<-Token>.

Anforderungsparameter

Parameter Typ Beschreibung Erforderlich
applicationId Zeichenfolge Die Store-ID der App, für die Sie Rezensionsdaten abrufen möchten. Ja
startDate date Das Startdatum im Datumsbereich der abzurufenden Überprüfungsdaten. Die Standardeinstellung ist das aktuelle Datum. No
endDate date Das Enddatum im Datumsbereich der abzurufenden Überprüfungsdaten. Die Standardeinstellung ist das aktuelle Datum. Nein
Oben int Die Anzahl der Datenzeilen, die in der Anforderung zurückgegeben werden sollen. Der Höchstwert und der Standardwert, falls nicht angegeben, ist 10000. Wenn in der Abfrage weitere Zeilen vorhanden sind, enthält der Antworttext einen nächsten Link, den Sie verwenden können, um die nächste Seite mit Daten anzufordern. Nein
skip int Die Anzahl der Zeilen, die in der Abfrage übersprungen werden sollen. Verwenden Sie diesen Parameter, um große Datasets zu durchlaufen. Beispielsweise ruft top=10000 und skip=0 die ersten 10000 Datenzeilen ab, top=100000 und skip=10000 ruft die nächsten 10000 Datenzeilen usw. ab. Nein
filter Zeichenfolge Eine oder mehrere Anweisungen, die die Zeilen in der Antwort filtern. Jede Anweisung enthält einen Feldnamen aus dem Antwortkörper und einen Wert, die mit den Operatoren eq oder ne verbunden sind, und Anweisungen können mit and oder or kombiniert werden. Zeichenfolgenwerte müssen von einfachen Anführungszeichen im Filterparameter umgeben sein. Sie können die folgenden Felder aus dem Antworttext angeben:
  • market
  • deviceType
  • packageVersion
 No
orderby Zeichenfolge Eine Anweisung, die die Ergebnisdatenwerte anordnet. Die Syntax ist orderby=Feld [order], Feld [order],.... Der Feld-Parameter kann eine der folgenden Zeichenfolgen sein:
  • date
  • applicationId
  • applicationName
  • market
  • packageVersion
  • deviceType
  • subscriptionName
  • monthlySessionCount
  • engagementDurationMinutes
  • monthlyActiveUsers
  • monthlyActiveDevices
  • monthlyNewUsers
  • averageDailyActiveUsers
  • averageDailyActiveDevices
  • monthlyNewDevices

Der Order-Parameter ist optional und kann asc oder desc sein, um die aufsteigende oder absteigende Reihenfolge für jedes Feld anzugeben. Die Standardeinstellung ist asc.

Hier ist ein Beispiel für eine orderby-Zeichenfolge: orderby=date,market

 Nein
groupby Zeichenfolge Eine Anweisung, die Datenaggregation nur auf die angegebenen Felder anwendet. Sie können die folgenden Felder aus dem Antworttext angeben:
  • applicationName
  • subscriptionName
  • deviceType
  • packageVersion
  • market
  • date

Die zurückgegebenen Datenzeilen enthalten die im groupby-Parameter angegebenen Felder sowie Folgendes:

  • applicationId
  • subscriptionName
  • monthlySessionCount
  • engagementDurationMinutes
  • monthlyActiveUsers
  • monthlyActiveDevices
  • monthlyNewUsers
  • averageDailyActiveUsers
  • averageDailyActiveDevices
  • monthlyNewDevices

Der groupby-Parameter kann mit dem aggregationLevel-Parameter verwendet werden. Zum Beispiel: &groupby=ageGroup,market&aggregationLevel=week

 No

Anforderungsbeispiel

Im folgenden Beispiel wird eine Anforderung zum Abrufen monatlicher App-Nutzungsdaten veranschaulicht. Ersetzen Sie den applicationId-Wert durch die Store-ID für Ihre App.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=XXXXXXXXXXXX&startDate=2018-06-01&endDate=2018-07-01 HTTP/1.1  
Authorization: Bearer <your access token>

Antwort

Antworttext

Wert Typ BESCHREIBUNG
Wert array Ein Array von Objekten, die aggregierte Nutzungsdaten enthalten. Weitere Informationen zu den Daten in den einzelnen Objekten finden Sie in der folgenden Tabelle.
@nextLink Zeichenfolge Wenn zusätzliche Datenseiten vorhanden sind, enthält diese Zeichenfolge einen URI, den Sie verwenden können, um die nächste Seite mit Daten anzufordern. Dieser Wert wird beispielsweise zurückgegeben, wenn der oberste Parameter der Anforderung auf 10000 festgelegt ist, es aber mehr als 10000 Zeilen mit Rezensionsdaten für die Abfrage gibt.
TotalCount int Die Gesamtanzahl der Zeilen im Datenergebnis für die Abfrage.

 

Verwendungswerte

Elemente im Value-Array enthalten die folgenden Werte.

Wert Typ Beschreibung UWP-Verfügbarkeit Anaheimbasierte PWA-Verfügbarkeit Xbox-Verfügbarkeit
date Zeichenfolge Das erste Datum im Datumsbereich für die Nutzungsdaten. Wenn die Anforderung einen einzelnen Tag angegeben hat, ist dieser Wert dieses Datum. Wenn die Anforderung eine Woche, einen Monat oder einen anderen Datumsbereich angegeben hat, ist dieser Wert das erste Datum in diesem Datumsbereich. Ja Ja Ja
applicationId Zeichenfolge Die Store-ID der App, für die Sie Nutzungsdaten abrufen. Ja Ja Ja
applicationName Zeichenfolge Der Anzeigename der App. Ja Ja Ja
Markt Zeichenfolge Der ISO 3166-Ländercode des Marktes, in dem der Kunde Ihre App verwendet hat. Ja Ja Ja
packageVersion Zeichenfolge Die Version des Pakets, in dem die Verwendung erfolgt ist. Ja Ja No
deviceType Zeichenfolge Eine der folgenden Zeichenfolgen, die den Typ des Geräts angibt, auf dem die Verwendung erfolgt ist:
  • PC
  • Telefonnummer
  • Konsolen-Xbox One
  • Konsolen-Xbox Series X
  • Tablet
  • IoT
  • Server
  • Holographisch
  • Unbekannt
 Ja Ja Ja
subscriptionName Zeichenfolge Gibt an, ob die Verwendung über Xbox Game Pass erfolgt ist. Ja Nr. No
monthlySessionCount long Die Anzahl der Benutzersitzungen in diesem Monat. Ja Ja Ja
engagementDurationMinutes double Die Minuten, in denen Benutzer Ihre App aktiv verwenden, gemessen nach einem bestimmten Zeitraum, beginnend beim Start der App (Prozessstart) und beim Beenden (Prozessende) oder nach einem Zeitraum der Inaktivität. Ja Ja Ja
monthlyActiveUsers long Die Anzahl der Kunden, die die App in diesem Monat verwenden. Ja Keine Ja
monthlyActiveDevices long Die Anzahl der Geräte, die Ihre App für einen bestimmten Zeitraum ausführen, beginnend beim Starten der App (Prozessstart) und beenden, wenn sie beendet wird (Prozessende) oder nach einem Zeitraum der Inaktivität. Ja Ja Ja
monthlyNewUsers long Die Anzahl der Kunden, die Ihre App zum ersten Mal in diesem Monat verwendet haben. Ja Keine Ja
averageDailyActiveUsers double Die durchschnittliche Anzahl von Kunden, die die App täglich verwenden. Ja Keine Ja
averageDailyActiveDevices double Die durchschnittliche Anzahl der Geräte, die für die Interaktion mit Ihrer App von allen Benutzern täglich verwendet werden. Ja Ja Ja
monthlyNewDevices long Die Anzahl der Geräte, die die App zum ersten Mal in diesem Monat verwendet haben. No Ja Nein

Hinweis

Wenn ein Feld für ein bestimmtes Produkt nicht gültig ist, wird der Wert an diese Felder in der Antwort als 0 oder NULL gesendet. Die Berechnung neuer Benutzer und neuer Geräte erfolgt mit dem rollierenden Fenster von 3 Jahren, d. h., wenn ein Benutzer/Gerät die Anwendung 3 Jahre und höher nicht verwendet, wird sie nach 3 Jahren als neuer Benutzer/Gerät behandelt.

Beispiel für Anforderung und Antwort

Die folgenden Codeausschnitte zeigen beispielweise Anforderungs- und JSON-Antworttext für diese Anforderung.

Beispiel-Anfrage

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Beispiel für eine Antwort

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "deviceType": "All",
            "packageVersion": "All",
            "market": "All",
            "engagementDurationMinutes": 2828568.3,
            "monthlyActiveUsers": 165249,
            "monthlyActiveDevices": 165753,
            "monthlyNewUsers": 95787,
            "monthlySessionCount": 314263,
            "averageDailyActiveUsers": 192.506111111111,
            "averageDailyActiveDevices": 191.199722222222,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 1
}

Beispiel-Anfrage

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR&startDate=2022-06-01&endDate=2022-07-01&groupby=applicationName,subscriptionName,deviceType,packageVersion,market,date&top=10&skip=0
HTTP/1.1
Authorization: Bearer <your access token>

Beispiel für eine Antwort

{
    "Value": [
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "JP",
            "engagementDurationMinutes": 0.3,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "MX",
            "engagementDurationMinutes": 2.7,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "Unknown",
            "engagementDurationMinutes": 0.1,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "US",
            "engagementDurationMinutes": 0.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AE",
            "engagementDurationMinutes": 3.2,
            "monthlyActiveUsers": 2,
            "monthlyActiveDevices": 2,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 3,
            "averageDailyActiveUsers": 0.07,
            "averageDailyActiveDevices": 0.07,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AO",
            "engagementDurationMinutes": 1.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AR",
            "engagementDurationMinutes": 574.7,
            "monthlyActiveUsers": 39,
            "monthlyActiveDevices": 39,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 53,
            "averageDailyActiveUsers": 1.43,
            "averageDailyActiveDevices": 1.43,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AT",
            "engagementDurationMinutes": 5.3,
            "monthlyActiveUsers": 4,
            "monthlyActiveDevices": 4,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 9,
            "averageDailyActiveUsers": 0.17,
            "averageDailyActiveDevices": 0.17,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AU",
            "engagementDurationMinutes": 434.7,
            "monthlyActiveUsers": 22,
            "monthlyActiveDevices": 22,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 36,
            "averageDailyActiveUsers": 0.9,
            "averageDailyActiveDevices": 0.9,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AZ",
            "engagementDurationMinutes": 13.5,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 10
}