Abrufen von Xbox Live-IntegritätsdatenGet Xbox Live health data

Verwenden Sie diese Methode in der Microsoft Store Analytics-API, um Integritäts Daten für das Live aktivierte Xbox-Spielzu erhalten.Use this method in the Microsoft Store analytics API to get health data for your Xbox Live-enabled game. 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 die Xbox Live Health-Daten abrufen möchten.The Store ID of the game for which you want to retrieve Xbox Live health 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 callingpatternan.For this method, specify the value callingpattern. JaYes
startDatestartDate datedate Das Startdatum im Datumsbereich der abzurufenden Integritäts Daten.The start date in the date range of health data to retrieve. Der Standardwert ist 30 Tage vor dem aktuellen Datum.The default is 30 days before the current date. NeinNo
endDateendDate datedate Das Enddatum im Datumsbereich von Integritäts Daten, die abgerufen werden sollen.The end date in the date range of health 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
  • sandboxIdsandboxId
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
  • sandboxIdsandboxId

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 Integritäts Daten für Ihr Xbox Live-fähiges Spiel.The following example demonstrates a request for getting health 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=callingpattern&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

AntwortResponse

WertValue TypType BESCHREIBUNGDescription
WertValue arrayarray Ein Array von-Objekten, die Integritäts Daten enthalten.An array of objects that contain health data. Weitere Informationen zu den Daten in den einzelnen Objekten finden Sie in der folgenden Tabelle.For more information about the data in each object, see the following table.
@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.

Elemente im Array Value enthalten die folgenden Werte.Elements in the Value array contain the following values.

WertValue TypType BESCHREIBUNGDescription
applicationIdapplicationId Zeichenfolgestring Die Speicher-ID des Spiels, für das Sie Integritäts Daten abrufen.The Store ID of the game for which you are retrieving health data.
datedate Zeichenfolgestring Das erste Datum im Datumsbereich für die Integritäts Daten.The first date in the date range for the health data. Wenn die Anforderung einen einzelnen Tag angibt, ist dieses Datum dieser Wert.If the request specified a single day, this value is that date. Wenn die Anforderung eine Woche, einen Monat oder einen anderen Datumsbereich angibt, ist dieser Wert das erste Datum in diesem Datumsbereich.If the request specified a week, month, or other date range, this value is the first date in that date range.
deviceTypedeviceType Zeichenfolgestring Eine der folgenden Zeichen folgen, die den Typ des Geräts angibt, auf dem das Spiel verwendet wurde:One of the following strings that specifies the type of device on which your game was used:

  • XboxoneXboxOne
  • Windowsonecore (dieser Wert weist auf einen PC hin)WindowsOneCore (this value indicates a PC)
  • UnbekanntUnknown
sandboxIdsandboxId Zeichenfolgestring Die Sandbox-ID, die für das Spiel erstellt wurde.The sandbox ID created for the game. Hierbei kann es sich um den Wert Retail oder die ID eines privaten Sandkastens handeln.This can be the value RETAIL or the ID for a private sandbox.
packageVersionpackageVersion Zeichenfolgestring Die vierteilige Paketversion für das Spiel.The four-part package version for the game.
callingpatterncallingPattern Objekt (object)object Ein callingpattern -Objekt, das Dienst Antworten, Geräte und Benutzerdaten für jeden Statuscode bereitstellt, der von jedem Xbox Live-Dienst zurückgegeben wird, der von Ihrem Spiel für den angegebenen Datumsbereich verwendet wird.A callingPattern object that provides service responses, devices, and user data for each status code returned by each Xbox Live service used by your game for the specified date range.

callingpatterncallingPattern

WertValue TypType BESCHREIBUNGDescription
Dienstservice Zeichenfolgestring Der Name des Xbox Live-Dienstanbieter, auf den sich die Integritäts Daten beziehen.The name of the Xbox Live service that the health data relates to.
endpointendpoint Zeichenfolgestring Der Endpunkt des Xbox Live-Dienstanbieter, auf den sich die Integritäts Daten beziehen.The endpoint of the Xbox Live service that the health data relates to.
HttpStatusCodehttpStatusCode Zeichenfolgestring Der HTTP-Statuscode für diesen Satz von Integritäts Daten.The HTTP status code for this set of health data.

Note   Hinweis   Der Statuscode 429e gibt an, dass der Dienst nur erfolgreich ausgeführt wurde, weil eine differenzierte Raten Begrenzung während des Aufrufes ausgenommen war.Note  The status code 429E indicates that the service call succeeded only because fine grained rate limiting was exempt during the call. Eine differenzierte Raten Beschränkung könnte in Zukunft erzwungen werden, wenn der Dienst ein hohes Volumen hat, und in diesem Fall würde der-Befehl zu einem http 429-Statuscodeführen.Fine grained rate limited could be enforced in the future if the service experiences high volume, and in that case the call would result in an HTTP 429 status code.

serviceresponsesserviceResponses numbernumber Die Anzahl der Dienst Antworten, die den angegebenen Statuscode zurückgegeben haben.The number of service responses that returned the specified status code.
uniquedevicesuniqueDevices numbernumber Die Anzahl eindeutiger Geräte, von denen der Dienst aufgerufen und der angegebene Statuscode empfangen wurde.The number of unique devices that called the service and received the specified status code.
uniqueUsersuniqueUsers numbernumber Die Anzahl der eindeutigen Benutzer, die den angegebenen Statuscode empfangen haben.The number of unique users who received the specified status code.

AntwortbeispielResponse example

Das folgende Beispiel zeigt ein Beispiel für einen JSON-Antworttext für diese Anforderung.The following example demonstrates an example JSON response body for this request. Die in diesem Beispiel gezeigten Dienstnamen und Endpunkte sind nicht real und dienen nur zu Beispiel Zwecken.The service names and endpoints shown in this example are not real, and are used for example purposes only.

{
  "Value": [
    {
      "applicationId": "9NBLGGGZ5QDR",
      "date": "2018-01-30",
      "deviceType": "All",
      "sandboxId": "RETAIL",
      "packageVersion": "Unknown",
      "callingpattern": [
        {
          "service": "userstats",
          "endpoint": "UserStats.BatchReadHandler.POST",
          "httpStatusCode": "200",
          "serviceResponses": 160891,
          "uniqueDevices": 410,
          "uniqueUsers": 410
        },
        {
          "service": "userstats",
          "endpoint": "UserStats.BatchStatReadHandler.GET",
          "httpStatusCode": "200",
          "serviceResponses": 422,
          "uniqueDevices": 0,
          "uniqueUsers": 30
        }
      ],
    }
  ],
  "@nextLink": null,
  "TotalCount": 1
}