Freigeben über

Abrufen von Kaufdaten für Ihre Spiele und Apps

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 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
ERHALTEN/Bekommen https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions

Anforderungsheader

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

Anforderungsparameter

Parameter Typ Beschreibung Erforderlich
Anwendungs-ID 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
Startdatum Datum Das Startdatum im Datumsbereich der abzurufenden Kaufdaten. Der Standardwert ist das aktuelle Datum. Nein
Enddatum Datum Das Enddatum im Datumsbereich der abzurufenden Kaufdaten. Der Standardwert 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 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. Beispielsweise filter=market eq 'US' and gender eq 'm'.
Sie können die folgenden Felder aus dem Antworttext angeben:
  • Erwerbsart
  • Alter
  • Kunde speichern
  • Geschlecht
  • Markt
  • Betriebssystemversion
  • Gerätetyp
  • sandboxId -
 Nein
Aggregationsniveau 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
Sortierung nach 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:
  • Datum
  • Erwerbsart
  • Alter
  • Kunde speichern
  • Geschlecht
  • Markt
  • Betriebssystemversion
  • Gerätetyp
  • Zahlungsmitteltyp
  • 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
GruppierenNach Zeichenfolge Eine Anweisung, die Datenaggregation nur auf die angegebenen Felder anwendet. Sie können die folgenden Felder angeben:
  • Datum
  • Name der Anwendung
  • Erwerbsart
  • Alter
  • Kunde speichern
  • Geschlecht
  • Markt
  • Betriebssystemversion
  • Gerätetyp
  • Zahlungsmitteltyp
  • sandboxId -
  • xboxTitleId
Die zurückgegebenen Datenzeilen enthalten die im Parameter groupby angegebenen Felder sowie folgendes:
  • Datum
  • Anwendungs-ID
  • Kaufmenge
Der Parameter groupby kann mit dem aggregationLevel-Parameter verwendet werden. Zum Beispiel: &groupby=age,market&aggregationLevel=week		 Nein

Anforderungsbeispiel

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 Typ 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‭.
Gesamtzahl Integer Die Gesamtanzahl der Zeilen im Datenergebnis für die Abfrage.

Akquisitionswerte

Elemente in der Matrix Wert enthalten die folgenden Werte.

Wert Typ 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.
Anwendungs-ID Zeichenfolge Die Produkt-ID des Xbox One-Spiels, für das Sie Kaufdaten abrufen.
Anwendungsname Zeichenfolge Der Anzeigename des Spiels.
Erwerbstyp Zeichenfolge Eine der folgenden Zeichenfolgen, die den Typ des Kaufs angibt:
  • Kostenlos
  • Testversion
  • Bezahlt
  • Angebotscode
  • Lap
  • Abonnement-Lap
  • Private Zielgruppe
  • Vorbestellung
  • Xbox Game Pass (oder Game Pass, wenn Daten vor dem 23. März 2018 abgefragt werden)
  • Datenträger
  • Prepaid-Code
  • Vorbestellung in Rechnung gestellt
  • Stornierte Vorbestellung
  • Fehlgeschlagene Vorbestellung
Alter 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
Gerätetyp Zeichenfolge Eine der folgenden Zeichenfolgen, die den Gerätetyp angibt, der den Kauf abgeschlossen hat:
  • PC
  • Telefonnummer
  • Konsolen-Xbox One
  • Konsolen-Xbox Series X
  • Iot
  • Server
  • Tablette
  • Holographisch
  • Unbekannt
Geschlecht Zeichenfolge Eine der folgenden Zeichenfolgen, die das Geschlecht des Benutzers angibt, der den Kauf getätigt hat:
  • m
  • f
  • Unbekannt
Markt 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.
Zahlungsinstrumenttyp 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.
Erwerbsmenge Zahl Die Anzahl der Käufe, die auf der angegebenen Aggregationsebene stattgefunden haben.
KaufpreisUSDBetrag Zahl Der vom Kunden für den Kauf gezahlte Betrag, der mit dem monatlichen Wechselkurs in USD umgewandelt wird.
KaufsteuerUSDBetrag Zahl Der auf den Kauf angewendete Steuerbetrag, umgerechnet in USD.
Lokalwährungscode Zeichenfolge Code der lokalen Währung basierend auf dem Land/der Region des Partner Center-Kontos.
xboxProdukt-ID Zeichenfolge Xbox-Produkt-ID des Produkts aus XDP, falls zutreffend.
Verfügbarkeits-ID Zeichenfolge Verfügbarkeits-ID des Produkts aus XDP, falls zutreffend.
SKU-Nummer 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.
übergeordnetesProduktName Zeichenfolge Übergeordneter Produktname des Produkts aus XDP, falls zutreffend.
ProduktTypName Zeichenfolge Produkttypname des Produkts aus XDP, falls zutreffend.
Kaufsteuertyp Zeichenfolge Einkaufssteuertyp des Produkts aus XDP, falls zutreffend.
KaufpreisBetragLokal Zahl Kaufpreis lokaler Betrag des Produkts aus XDP, falls zutreffend.
lokaler Kaufsteuerbetrag 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 
}