Abrufen von Xbox Live MultiplayerdatenGet Xbox Live multiplayer data

Verwenden Sie diese Methode in der Microsoft Store Analytics-API, um für Ihr Xbox Live-fähiges Spiel täglich oder monatlich multiplayerdaten zu erhalten.Use this method in the Microsoft Store analytics API to get multiplayer data for your Xbox Live-enabled game on a daily or monthly basis. Diese Informationen sind auch im Bericht " Xbox Analytics " im Partner Center verfügbar.This information is also available in the Xbox analytics report in Partner Center.

Wichtig

Diese Methode unterstützt nur Spiele für Xbox oder Spiele, die Xbox Live-Dienste verwenden.This method only supports games for Xbox or games that use Xbox Live services. Diese Spiele müssen den Genehmigungsprozess des Konzeptsdurchlaufen, der Spiele umfasst, die von Microsoft-Partnern und über das ID@Xbox Programmgesendeten spielen veröffentlicht wurden.These games must go through the concept approval process, which includes games published by Microsoft partners and games submitted via the ID@Xbox program. Diese Methode unterstützt zurzeit keine Spiele, die über das Xbox Live Creators-Programmveröffentlicht wurden.This method does not currently support games published via the Xbox Live Creators Program.

VoraussetzungenPrerequisites

Zur Verwendung dieser Methode sind folgende Schritte erforderlich:To use this method, you need to first do the following:

  • Wenn Sie dies nicht bereits getan haben, müssen Sie alle Voraussetzungen für die Microsoft Store Analytics-API erfüllen.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Rufen Sie ein Azure AD-Zugriffstoken ab, das im Anforderungsheader für diese Methode verwendet wird.Obtain an Azure AD access token to use in the request header for this method. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft.After you obtain an access token, you have 60 minutes to use it before it expires. Wenn das Token abgelaufen ist, können Sie ein neues abrufen.After the token expires, you can obtain a new one.

AnforderungRequest

AnforderungssyntaxRequest syntax

MethodeMethod Anforderungs-URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics

AnforderungsheaderRequest header

HeaderHeader typeType BESCHREIBUNGDescription
AuthorizationAuthorization Zeichenfolgestring Erforderlich.Required. Das Azure AD-Zugriffstoken im Format Bearer <token>.The Azure AD access token in the form Bearer <token>.

AnforderungsparameterRequest parameters

ParameterParameter TypType BESCHREIBUNGDescription ErforderlichRequired
applicationIdapplicationId Zeichenfolgestring Die Speicher-ID des Spiels, für das Sie Xbox Live-multiplayerdaten abrufen möchten.The Store ID of the game for which you want to retrieve Xbox Live multiplayer data. JaYes
metrictypemetricType Zeichenfolgestring Eine Zeichenfolge, die den Typ der abzurufenden Xbox Live Analytics-Daten angibt.A string that specifies the type of Xbox Live analytics data to retrieve. Geben Sie für diese Methode den Wert multiplayerdaily an, um tägliche multiplayerdaten und multiplayermonatlich zu erhalten, um monatliche multiplayerdaten zu erhalten.For this method, specify the value multiplayerdaily to get daily multiplayer data or multiplayermonthly to get monthly multiplayer data. JaYes
startDatestartDate datedate Das Startdatum im Datumsbereich von multiplayerdaten, die abgerufen werden sollen.The start date in the date range of multiplayer data to retrieve. Für multiplayerdailybeträgt der Standardwert drei Monate vor dem aktuellen Datum.For multiplayerdaily, the default is 3 months before the current date. Bei multiplayermonthlybeträgt der Standardwert 1 Jahr vor dem aktuellen Datum.For multiplayermonthly, the default is 1 year before the current date. NeinNo
endDateendDate datedate Das Enddatum im Datumsbereich von multiplayerdaten, die abgerufen werden sollen.The end date in the date range of multiplayer data to retrieve. Als Standardeinstellung wird das aktuelle Datum festgelegt.The default is the current date. NeinNo
toptop INTint Die Anzahl der Datenzeilen, die in der Anforderung zurückgegeben werden sollen.The number of rows of data to return in the request. Der Maximal- und Standardwert ist 10.000, wenn nicht anders angegeben.The maximum value and the default value if not specified is 10000. Sind in der Abfrage keine weiteren Zeilen, enthält der Antworttext den Link „Weiter“, über den Sie die nächste Seite mit Daten anfordern können.If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. NeinNo
skipskip INTint Die Anzahl der Zeilen, die in der Abfrage übersprungen werden sollen.The number of rows to skip in the query. Verwenden Sie diesen Parameter, um große Datensätze durchzublättern.Use this parameter to page through large data sets. Beispielsweise rufen „top=10000“ und „skip=0“ die ersten 10.000 Datenzeilen ab, „top=10000“ und „skip=10000“ die nächsten 10.000 Datenzeilen usw.For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. NeinNo
filterfilter Zeichenfolgestring Mindestens eine Anweisung, die die Zeilen in der Antwort filtert.One or more statements that filter the rows in the response. Jede-Anweisung enthält einen Feldnamen aus dem Antworttext und den Wert, die den EQ -oder ne -Operatoren zugeordnet sind, und-Anweisungen können mithilfe von and oder orkombiniert werden.Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. Zeichenfolgenwerte im Parameter filter müssen von einfachen Anführungszeichen eingeschlossen werden.String values must be surrounded by single quotes in the filter parameter. Sie können die folgenden Felder aus dem Antworttext angeben:You can specify the following fields from the response body:

  • den DeviceType "deviceType
  • packageVersionpackageVersion
  • Marktforschungsmarket
  • subscriptionNamesubscriptionName
NeinNo
groupbygroupby Zeichenfolgestring Eine Anweisung, die nur auf die angegebenen Felder Datenaggregationen anwendet.A statement that applies data aggregation only to the specified fields. Sie können die folgenden Felder aus dem Antworttext angeben:You can specify the following fields from the response body:

  • datedate
  • den DeviceType "deviceType
  • packageVersionpackageVersion
  • Marktforschungsmarket
  • subscriptionNamesubscriptionName

Wenn Sie ein oder mehrere GroupBy -Felder angeben, haben alle anderen GroupBy -Felder, die Sie nicht angeben, den Wert alle im Antworttext.If you specify one or more groupby fields, any other groupby fields you do not specify will have the value All in the response body.

NeinNo

AnforderungsbeispielRequest example

Das folgende Beispiel zeigt eine Anforderung zum erhalten von multiplayerdaten für Ihr Xbox Live-fähiges Spiel.The following example demonstrates a request for getting multiplayer data for your Xbox Live-enabled game. Ersetzen Sie den Wert ApplicationId durch die Store-ID für Ihr Spiel.Replace the applicationId value with the Store ID for your game.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/gameanalytics?applicationId=9NBLGGGZ5QDR&metrictype=multiplayerdaily&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

AntwortResponse

WertValue TypType BESCHREIBUNGDescription
WertValue arrayarray Ein Array von-Objekten, die multiplayerdaten enthalten, wobei jedes-Objekt eine Menge von Daten für den angegebenen Tages-oder Monats Zeitraum darstellt und nach dem angegebenen Filter und den GroupBy -Werten angeordnet ist.An array of objects that contain multiplayer data, where each object represents a set of data for the specified daily or monthly time period and organized by the specified filter and groupby values. Weitere Informationen zu den Daten in den einzelnen Objekten finden Sie in den Abschnitten zu den täglichen multiplayeranalysen und den monatlichen multiplayeranalysen .For more information about the data in each object, see the Daily multiplayer analytics and Monthly multiplayer analytics sections.
@nextLink Zeichenfolgestring Wenn weitere Seiten mit Daten vorhanden sind, enthält diese Zeichenfolge einen URI, mit dem Sie die nächste Seite mit Daten anfordern können.If there are additional pages of data, this string contains a URI that you can use to request the next page of data. Dieser Wert wird z. b. zurückgegeben, wenn der Top -Parameter der Anforderung auf 10000 festgelegt ist, aber mehr als 10000 Daten Zeilen für die Abfrage vorhanden sind.For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of data for the query.
TotalCountTotalCount INTint Die Gesamtzahl der Zeilen im Datenergebnis für die Abfrage.The total number of rows in the data result for the query.

Tägliche multiplayeranalysenDaily multiplayer analytics

Elemente im Wertarray enthalten die folgenden Werte, wenn Sie tägliche multiplayeranalysedaten anfordern (d. h., wenn Sie multiplayerdaily für den metrictype -Parameter angeben).Elements in the Value array contain the following values when you request daily multiplayer analytics data (that is, when you specify multiplayerdaily for the metricType parameter).

WertValue TypType BESCHREIBUNGDescription
datedate Zeichenfolgestring Das Datum der multiplayerdaten.The date for the multiplayer data.
applicationIdapplicationId Zeichenfolgestring Die Speicher-ID des Spiels, für das Sie multiplayerdaten abrufen.The Store ID of the game for which you are retrieving multiplayer data.
applicationNameapplicationName Zeichenfolgestring Der Name des Spiels, für das Sie multiplayerdaten abrufen.The name of the game for which you are retrieving multiplayer data.
marketmarket Zeichenfolgestring Der aus zwei Buchstaben bestehende ISO 3166-Ländercode des Markts, von dem die multiplayerdaten stammen.The two-letter ISO 3166 country code of the market where the multiplayer data came from.
packageVersionpackageVersion Zeichenfolgestring Die vierteilige Paketversion für das Spiel.The four-part package version for the game.
deviceTypedeviceType Zeichenfolgestring Eine der folgenden Zeichen folgen, die den Typ des Geräts angibt, von dem die multiplayerdaten stammen:One of the following strings that specifies the type of device where the multiplayer data came from:

  • KonsoleConsole
  • PCsPC
  • UnbekanntUnknown
subscriptionNamesubscriptionName Zeichenfolgestring Der Name des Abonnements, das für die multiplayerdaten verwendet wird.The name of the subscription used for the multiplayer data. Mögliche Werte sind " Xbox Game Pass " und "" (für kein Abonnement).Possible values include Xbox Game Pass and "" (for no subscription).
dailysessioncountdailySessionCount numbernumber Die Anzahl der multiplayersitzungen für das Spiel am angegebenen Datum.The number of multiplayer sessions for the game on the specified date.
engagementdurationminutesengagementDurationMinutes numbernumber Die Gesamtanzahl der Minuten, die Kunden an dem angegebenen Datum mit multiplayersitzungen für das Spiel beschäftigt waren.The total number of minutes that customers were engaged with multiplayer sessions for the game on the specified date.
dailyactiveusersdailyActiveUsers numbernumber Die Gesamtanzahl aktiver multiplayerbenutzer für das Spiel am angegebenen Datum.The total number of active multiplayer users for the game on the specified date.
dailyactivedevicesdailyActiveDevices numbernumber Die Gesamtanzahl aktiver Geräte, die für das Spiel an dem angegebenen Datum multiplayersitzungen durchgespielt haben.The total number of active devices that played multiplayer sessions for the game on the specified date.
dailynewusersdailyNewUsers numbernumber Die Gesamtanzahl der neuen multiplayerbenutzer für das Spiel am angegebenen Datum.The total number of new multiplayer users for the game on the specified date.
monthlyactiveusersmonthlyActiveUsers numbernumber Die Gesamtanzahl aktiver multiplayerbenutzer für den Monat, in dem das angegebene Datum aufgetreten ist.The total number of active multiplayer users for the month in which the specified date occurred.
monthlyactivedevicesmonthlyActiveDevices numbernumber Die Gesamtanzahl aktiver Geräte, die Multiplayer-Sitzungen für das Spiel für den Monat abgespielt haben, in dem das angegebene Datum aufgetreten ist.The total number of active devices that played multiplayer sessions for the game for the month in which the specified date occurred.
monthlynewusersmonthlyNewUsers numbernumber Die Gesamtanzahl der neuen multiplayerbenutzer für das Spiel für den Monat, in dem das angegebene Datum aufgetreten ist.The total number of new multiplayer users for the game for the month in which the specified date occurred.

Monatliche multiplayeranalysenMonthly multiplayer analytics

Elemente im Wertarray enthalten die folgenden Werte, wenn Sie monatliche multiplayeranalysedaten anfordern (d. h., wenn Sie multiplayermonatlich für den metrictype -Parameter angeben).Elements in the Value array contain the following values when you request monthly multiplayer analytics data (that is, when you specify multiplayermonthly for the metricType parameter).

WertValue TypType BESCHREIBUNGDescription
datedate Zeichenfolgestring Das erste Datum des Monats für die multiplayerdaten.The first date of the month for the multiplayer data.
applicationIdapplicationId Zeichenfolgestring Die Speicher-ID des Spiels, für das Sie multiplayerdaten abrufen.The Store ID of the game for which you are retrieving multiplayer data.
applicationNameapplicationName Zeichenfolgestring Der Name des Spiels, für das Sie multiplayerdaten abrufen.The name of the game for which you are retrieving multiplayer data.
marketmarket Zeichenfolgestring Der aus zwei Buchstaben bestehende ISO 3166-Ländercode des Markts, von dem die multiplayerdaten stammen.The two-letter ISO 3166 country code of the market where the multiplayer data came from.
packageVersionpackageVersion Zeichenfolgestring Die vierteilige Paketversion für das Spiel.The four-part package version for the game.
deviceTypedeviceType Zeichenfolgestring Eine der folgenden Zeichen folgen, die den Typ des Geräts angibt, von dem die multiplayerdaten stammen:One of the following strings that specifies the type of device where the multiplayer data came from:

  • KonsoleConsole
  • PCsPC
  • UnbekanntUnknown
subscriptionNamesubscriptionName Zeichenfolgestring Der Name des Abonnements, das für die multiplayerdaten verwendet wird.The name of the subscription used for the multiplayer data. Mögliche Werte sind " Xbox Game Pass " und "" (für kein Abonnement).Possible values include Xbox Game Pass and "" (for no subscription).
monthlysessioncountmonthlySessionCount numbernumber Die Anzahl der multiplayersitzungen für das Spiel innerhalb des angegebenen Monats.The number of multiplayer sessions for the game during the specified month.
engagementdurationminutesengagementDurationMinutes numbernumber Die Gesamtanzahl der Minuten, die Kunden während des angegebenen Monats mit multiplayersitzungen für das Spiel beschäftigt waren.The total number of minutes that customers were engaged with multiplayer sessions for the game during the specified month.
monthlyactiveusersmonthlyActiveUsers numbernumber Die Gesamtanzahl aktiver multiplayerbenutzer innerhalb des angegebenen Monats.The total number of active multiplayer users during the specified month.
monthlyactivedevicesmonthlyActiveDevices numbernumber Die Gesamtanzahl aktiver Geräte, die während des angegebenen Monats multiplayersitzungen für das Spiel abgespielt haben.The total number of active devices that played multiplayer sessions for the game during the specified month.
monthlynewusersmonthlyNewUsers numbernumber Die Gesamtanzahl der neuen multiplayerbenutzer für das Spiel innerhalb des angegebenen Monats.The total number of new multiplayer users for the game during the specified month.
averagedailyactiveusersaverageDailyActiveUsers numbernumber Die durchschnittliche Anzahl der täglichen aktiven multiplayerbenutzer für das Spiel innerhalb des angegebenen Monats.The average number of daily active multiplayer users for the game during the specified month.
averagedailyactivedevicesaverageDailyActiveDevices numbernumber Die durchschnittliche Anzahl aktiver Geräte, die während des angegebenen Monats multiplayersitzungen für das Spiel abgespielt haben.The average number of active devices that played multiplayer sessions for the game during the specified month.

AntwortbeispielResponse example

Im folgenden Beispiel wird ein Beispiel für einen JSON-Antworttext für die Variante der täglichen Metriken dieser Anforderung veranschaulicht (d. h., wenn Sie multiplayerdaily für den metrictype -Parameter angeben).The following example demonstrates an example JSON response body for the daily metrics variant of this request (that is, when you specify multiplayerdaily for the metricType parameter).

{
  "Value": [
    {
      "date": "2018-01-07",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso Sports",
      "market": "All",
      "packageVersion": "",
      "deviceType": "All",
      "subscriptionName": "All",
      "dailySessionCount": 976711,
      "engagementDurationMinutes": 16836064.5,
      "dailyActiveUsers": 180377,
      "dailyActiveDevices": 153359,
      "dailyNewUsers": 8638,
      "monthlyActiveUsers": 779984,
      "monthlyActiveDevices": 606495,
      "monthlyNewUsers": 212093
    },
    {
      "date": "2018-01-05",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso Sports",
      "market": "All",
      "packageVersion": "",
      "deviceType": "All",
      "subscriptionName": "All",
      "dailySessionCount": 857433,
      "engagementDurationMinutes": 14087724.5,
      "dailyActiveUsers": 166630,
      "dailyActiveDevices": 143065,
      "dailyNewUsers": 9646,
      "monthlyActiveUsers": 764947,
      "monthlyActiveDevices": 595368,
      "monthlyNewUsers": 204248
    },
  ],
  "@nextLink": null,
  "TotalCount":2
}