Abrufen von Kaufdaten für Ihre Spiele und Apps

  • Artikel

Verwenden Sie diese Methode in der Microsoft Store-Analyse-API, um aggregierte Kaufdaten im JSON-Format für UWP-Apps und Xbox One-Spiele abzurufen, die über das Xbox Developer Portal (XDP) erfasst wurden und im XDP Analytics-Dashboard verfügbar sind.

Hinweis

Diese API stellt keine täglichen Aggregatdaten vor dem 1. Oktober 2016 bereit.

Voraussetzungen

Um diese Methoden 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.

Anforderung

Anforderungssyntax

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

Anforderungsheader

Header type BESCHREIBUNG
Authorization Zeichenfolge Erforderlich. Das Azure AD-Zugriffstoken im Formular Bearer<token>.

Anforderungsparameter

Parameter Typ Beschreibung Erforderlich
applicationId Zeichenfolge Die Produkt-ID des Xbox One-Spiels, für das Sie Kaufdaten abrufen. Um die Produkt-ID Ihres Spiels abzurufen, navigieren Sie im XDP-Analyse-Programm zu Ihrem Spiel, und rufen Sie die Produkt-ID aus der URL ab. Wenn Sie Ihre Käufe aus dem Partner Center-Analytics-Bericht herunterladen, ist die Produkt-ID in der TSV-Datei enthalten. Ja
startDate Datum Das Startdatum im Datumsbereich der abzurufenden Kaufdaten. Der Standard ist das aktuelle Datum. Nein
endDate Datum Das Enddatum im Datumsbereich der abzurufenden Kaufdaten. Der Standard ist das aktuelle Datum. Nein
filter Zeichenfolge Eine oder mehrere Anweisungen, die die Zeilen in der Antwort filtern. Jede Anweisung enthält einen Feldnamen aus dem Antworttext und Wert, die dem eq- oder ne-Operator zugeordnet sind, und Anweisungen können mit und oder oder kombiniert werden. Zeichenfolgenwerte müssen von einfachen Anführungszeichen im Filter-Parameter umgeben sein. Beispielsweise filter=market eq 'US' and gender eq 'm'.
Sie können die folgenden Felder aus dem Antworttext angeben:
  • acquisitionType
  • age
  • storeClient
  • gender
  • market
  • osVersion
  • deviceType
  • sandboxId
 Nein
aggregationLevel Zeichenfolge Gibt den Zeitraum an, für den aggregierte Daten abgerufen werden sollen. Dies kann eine der folgenden Zeichenfolgen sein: Tag, Woche oder Monat. Wenn keine Angabe erfolgt, lautet der Standardwert Tag. Nein
orderby Zeichenfolge Eine Anweisung, die die Ergebnisdatenwerte für jeden Kauf anordnet. Die Syntax ist orderby=Feld [order],Feld [order],... Der Feld-Parameter kann eine der folgenden Zeichenfolgen sein:
  • date
  • acquisitionType
  • age
  • storeClient
  • gender
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
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 angeben:
  • date
  • applicationName
  • acquisitionType
  • age
  • storeClient
  • gender
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
Die zurückgegebenen Datenzeilen enthalten die im Parameter groupby angegebenen Felder sowie folgendes:
  • date
  • applicationId
  • acquisitionQuantity
Der Parameter groupby kann mit dem aggregationLevel-Parameter verwendet werden. Zum Beispiel: &groupby=age,market&aggregationLevel=week		 Nein

Beispiel für eine Anfrage

Im folgenden Beispiel werden mehrere Anforderungen zum Abrufen von Xbox One-Spiel-Kaufdaten veranschaulicht. Ersetzen Sie den Wert applicationId durch die Produkt-ID für Ihr Spiel.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&top=10&skip=0 HTTP/1.1 
Authorization: Bearer <your access token> 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token>

Antwort

Antworttext

Wert type BESCHREIBUNG
Wert array Ein Array von Objekten, die aggregierte Kaufdaten für das Spiel enthalten. Weitere Informationen zu den Daten in den einzelnen Objekten finden Sie unten im Abschnitt Akquisitionswerte‭.
TotalCount integer Die Gesamtanzahl der Zeilen im Datenergebnis für die Abfrage.

Akquisitionswerte

Elemente im Value-Array enthalten die folgenden Werte.

Wert type Beschreibung
Datum Zeichenfolge Das erste Datum im Datumsbereich für die Kaufdaten. 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.
applicationId Zeichenfolge Die Produkt-ID des Xbox One-Spiels, für das Sie Kaufdaten abrufen.
applicationName Zeichenfolge Der Anzeigename des Spiels.
acquisitionType Zeichenfolge Eine der folgenden Zeichenfolgen, die den Typ des Kaufs angibt:
  • Kostenlos
  • Testversion
  • Bezahlt
  • Angebotscode
  • Iap
  • Abonnement-Iap
  • Private Zielgruppe
  • Vorbestellen
  • Xbox Game Pass (oder Game Pass, wenn die Abfrage Daten vor dem 23. März 2018 betrifft)
  • Datenträger
  • Prepaid-Code
  • Vorbestellung in Rechnung gestellt
  • Stornierte Vorbestellung
  • Fehlgeschlagene Vorbestellung
age Zeichenfolge Eine der folgenden Zeichenfolgen, die die Altersgruppe des Benutzers angibt, der den Kauf getätigt hat:
  • Weniger als 13
  • 13-17
  • 18-24
  • 25-34
  • 35-44
  • 44-55
  • Mehr als 55
  • Unbekannt
deviceType Zeichenfolge Eine der folgenden Zeichenfolgen, die den Gerätetyp angibt, der den Kauf abgeschlossen hat:
  • PC
  • Telefonnummer
  • Konsole-Xbox One
  • Konsole-Xbox Series X
  • IoT
  • Server
  • Tablet
  • Holographisch
  • Unbekannt
gender Zeichenfolge Eine der folgenden Zeichenfolgen, die das Geschlecht des Benutzers angibt, der den Kauf getätigt hat:
  • m
  • f
  • Unbekannt
market Zeichenfolge Der ISO 3166-Ländercode des Marktes, auf dem der Kauf erfolgte.
osVersion Zeichenfolge Die Betriebssystemversion, auf der der Erwerb erfolgte. Für diese Methode ist dieser Wert immer Windows 10 oder Windows 11.
paymentInstrumentType Zeichenfolge Eine der folgenden Zeichenfolgen, die die für den Erwerb verwendete Zahlungsanweisung angibt:
  • Kreditkarte
  • Debitkarte
  • Abgeleiteter Kauf
  • MS-Saldo
  • Mobilfunkanbieter
  • Online-Banküberweisung
  • PayPal
  • Geteilte Transaktion
  • Tokeneinlösung
  • Kein Betrag bezahlt
  • eWallet
  • Unbekannt
sandboxId Zeichenfolge Die für das Spiel erstellte Sandbox-ID. Dies kann der Wert RETAIL oder eine private Sandbox-ID sein.
storeClient Zeichenfolge Eine der folgenden Zeichenfolgen, die die Version des Stores angibt, in der der Kauf erfolgte:
  • Windows Phone Store (Client)
  • Microsoft Store (Client) (oder Windows Store (Client) bei Abfragen nach Daten vor dem 23. März 2018)
  • Microsoft Store (Web) (oder Windows Store (Web) bei Abfragen nach Daten vor dem 23. März 2018)
  • Volumenkauf durch Organisationen
  • Andere
xboxTitleId Zeichenfolge Die Xbox Live-Titel-ID (dargestellt im Hexadezimalwert), die vom Xbox Developer Portal (XDP) für Xbox Live-fähige Spiele zugewiesen wird.
acquisitionQuantity Zahl Die Anzahl der Käufe, die auf der angegebenen Aggregationsebene stattgefunden haben.
purchasePriceUSDAmount Zahl Der vom Kunden für den Kauf gezahlte Betrag, der mit dem monatlichen Wechselkurs in USD umgewandelt wird.
purchaseTaxUSDAmount Zahl Der auf den Kauf angewendete Steuerbetrag, umgerechnet in USD.
localCurrencyCode Zeichenfolge Lokaler Währungscode basierend auf dem Land des Partner Center-Kontos.
xboxProductId Zeichenfolge Xbox-Produkt-ID des Produkts aus XDP, falls zutreffend.
availabilityId Zeichenfolge Verfügbarkeits-ID des Produkts aus XDP, falls zutreffend.
skuId Zeichenfolge SKU-ID des Produkts aus XDP, falls zutreffend.
skuDisplayName Zeichenfolge SKU-Anzeigename des Produkts aus XDP, falls zutreffend.
xboxParentProductId Zeichenfolge Xbox Übergeordnete Produkt-ID des Produkts aus XDP, falls zutreffend.
parentProductName Zeichenfolge Übergeordneter Produktname des Produkts aus XDP, falls zutreffend.
productTypeName Zeichenfolge Produkttypname des Produkts aus XDP, falls zutreffend.
purchaseTaxType Zeichenfolge Einkaufssteuertyp des Produkts aus XDP, falls zutreffend.
purchasePriceLocalAmount Zahl Kaufpreis lokaler Betrag des Produkts aus XDP, falls zutreffend.
purchaseTaxLocalAmount Zahl Einkaufssteuer lokaler Betrag des Produkts aus XDP, falls zutreffend.

Beispielantwort

Im folgenden Beispiel wird ein Beispiel für einen JSON-Antworttext für diese Anforderung veranschaulicht.

{ 
    "Value": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 11", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}