Abrufen von Add-On-Käufen für AbonnementsGet subscription add-on acquisitions

Verwenden Sie diese Methode in der Microsoft Store Analytics-API, um aggregierte Erfassungsdaten für Add-on-Abonnements für Ihre APP in einem bestimmten Datumsbereich und anderen optionalen Filtern zu erhalten.Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-on subscriptions for your app during a given date range and other optional filters.

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/subscriptions

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 typeType BESCHREIBUNGDescription ErforderlichRequired
applicationIdapplicationId Zeichenfolgestring Die Speicher-ID der APP, für die Sie Abonnement Daten des Abonnement-Add-Ins abrufen möchten.The Store ID of the app for which you want to retrieve subscription add-on acquisition data. JaYes
Abonnement ProductIDsubscriptionProductId Zeichenfolgestring Die Speicher-ID des Abonnement-Add-Ins, für das Sie Erwerbs Daten abrufen möchten.The Store ID of the subscription add-on for which you want to retrieve acquisition data. Wenn Sie diesen Wert nicht angeben, gibt diese Methode Erwerbs Daten für alle Abonnement-Add-ons für die angegebene app zurück.If you do not specify this value, this method returns acquisition data for all subscription add-ons for the specified app. NeinNo
startDatestartDate datedate Das Startdatum im Datumsbereich der abzurufenden Abruf Daten für Abonnement-Add-on.The start date in the date range of subscription add-on acquisition data to retrieve. Als Standardeinstellung wird das aktuelle Datum festgelegt.The default is the current date. NeinNo
endDateendDate datedate Das Enddatum im Datumsbereich der Abruf Daten, die abgerufen werden sollen.The end date in the date range of subscription add-on acquisition 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 Höchstwert und der Standardwert, falls nicht angegeben, ist 100.The maximum value and the default value if not specified is 100. 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=100 and skip=0 retrieves the first 100 rows of data, top=100 and skip=100 retrieves the next 100 rows of data, and so on. NeinNo
filterfilter Zeichenfolgestring Eine oder mehrere-Anweisungen, die den Antworttext filtern.One or more statements that filter the response body. Alle Anweisungen können die Operatoren eq oder ne verwenden. Zudem können sie mit and oder or kombiniert werden.Each statement can use the eq or ne operators, and statements can be combined using and or or. Sie können die folgenden Zeichen folgen in den Filter Anweisungen angeben (diese entsprechen den Werten im Antworttext):You can specify the following strings in the filter statements (these correspond to values in the response body):
  • datedate
  • Abonnement NamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • Marktforschungsmarket
  • deviceTypedeviceType

Hier ist ein Beispiel für einen Filter Parameter: Filter = Date EQ ' 2017-07-08 '.Here is an example filter parameter: filter=date eq '2017-07-08'.

NeinNo
aggregationLevelaggregationLevel Zeichenfolgestring Gibt den Zeitraum an, für den aggregierte Daten abgerufen werden sollen.Specifies the time range for which to retrieve aggregate data. Dies kann eine der folgenden Zeichenfolgen sein: day, week oder month.Can be one of the following strings: day, week, or month. Wenn keine Angabe erfolgt, lautet der Standardwert day.If unspecified, the default is day. NeinNo
orderbyorderby Zeichenfolgestring Eine-Anweisung, die die Ergebnisdaten Werte für die einzelnen Abonnement-Add-on-Käufe anordnet.A statement that orders the result data values for each subscription add-on acquisition. Die Syntax lautet OrderBy = Field [Order], Field [Order],.... Der Feld Parameter kann eine der folgenden Zeichen folgen sein:The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • Abonnement NamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • Marktforschungsmarket
  • deviceTypedeviceType

Der Parameter order ist optional und kann asc oder desc sein, um die auf- oder absteigende Anordnung der einzelnen Felder anzugeben.The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. Der Standardwert ist ASC.The default is asc.

Hier ist ein Beispiel für eine OrderBy -Zeichenfolge: OrderBy = Date, MarketHere is an example orderby string: orderby=date,market

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 angeben:You can specify the following fields:
  • datedate
  • Abonnement NamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • Marktforschungsmarket
  • deviceTypedeviceType

Der Parameter groupby kann mit dem Parameter aggregationLevel verwendet werden.The groupby parameter can be used with the aggregationLevel parameter. Beispiel: GroupBy = Market & aggregationlevel = WeekFor example: groupby=market&aggregationLevel=week

NeinNo

AnforderungsbeispielRequest example

In den folgenden Beispielen wird veranschaulicht, wie Sie Abonnement-Add-on-Erwerbs Daten abrufen.The following examples demonstrates how to get subscription add-on acquisition data. Ersetzen Sie den Wert ApplicationId durch die entsprechende Speicher-ID für Ihre APP.Replace the applicationId value with the appropriate Store ID for your app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 HTTP/1.1
Authorization: Bearer <your access token>

AntwortResponse

AntworttextResponse body

WertValue typeType BESCHREIBUNGDescription
WertValue arrayarray Ein Array von-Objekten, die Erfassungsdaten für das aggregierte Abonnement enthalten.An array of objects that contain aggregate subscription add-on acquisition data. Weitere Informationen zu den Daten in den einzelnen Objekten finden Sie im Abschnitt Abonnement Erwerbs Werte weiter unten.For more information about the data in each object, see the subscription acquisition values section below.
@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 100 festgelegt ist, aber mehr als 100 Zeilen mit Abonnement-Add-on-Erfassungsdaten für die Abfrage vorhanden sind.For example, this value is returned if the top parameter of the request is set to 100 but there are more than 100 rows of subscription add-on acquisition 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.

Abonnement Erfassungs WerteSubscription acquisition values

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

WertValue typeType BESCHREIBUNGDescription
datedate Zeichenfolgestring Das erste Datum im Datumsbereich für die Kaufdaten.The first date in the date range for the acquisition 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.
Abonnement ProductIDsubscriptionProductId Zeichenfolgestring Die Speicher-ID des Abonnement-Add-Ins, für das Sie Erfassungsdaten abrufen.The Store ID of the subscription add-on for which you are retrieving acquisition data.
Abonnement NamesubscriptionProductName Zeichenfolgestring Der Anzeige Name des Abonnement-Add-Ins.The display name of the subscription add-on.
applicationIdapplicationId Zeichenfolgestring Die Speicher-ID der APP, für die Sie Abonnement-Add-on-Erwerbs Daten abrufen.The Store ID of the app for which you are retrieving subscription add-on acquisition data.
applicationNameapplicationName Zeichenfolgestring Der Anzeigename der App.The display name of the app.
skuIdskuId Zeichenfolgestring Die ID der SKU des Abonnement-Add-Ins, für das Sie Erfassungsdaten abrufen.The ID of the SKU of the subscription add-on for which you are retrieving acquisition data.
deviceTypedeviceType Zeichenfolgestring Eine der folgenden Zeichen folgen, die den Typ des Geräts angibt, das den Erwerb abgeschlossen hat:One of the following strings that specifies the type of device that completed the acquisition:
  • PCPC
  • SmartphonePhone
  • Konsole-Xbox OneConsole-Xbox One
  • Konsole-Xbox Series XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • UnbekanntUnknown
marketmarket Zeichenfolgestring Die ISO 3166-Ländercode des Markts, in dem der Kauf erfolgte.The ISO 3166 country code of the market where the acquisition occurred.
currencyCodecurrencyCode Zeichenfolgestring Der Währungscode im ISO 4217-Format für Brutto Umsätze vor Steuern.The currency code in ISO 4217 format for gross sales before taxes.
Gross Vertriebs beforetaxgrossSalesBeforeTax integerinteger Der Bruttoumsatz in der lokalen Währung, die durch den Wert "Currency Code " angegeben wird.The gross sales in the local currency specified by the currencyCode value.
totalactivecounttotalActiveCount integerinteger Die Gesamtanzahl der aktiven Abonnements innerhalb des angegebenen Zeitraums.The number of total active subscriptions during the specified time period. Dies entspricht der Summe der Werte von " goodstandingactivecount", " pdinggraceactivecount", " graceactivecount" und " lockedactivecount ".This is equivalent to the sum of the goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount, and lockedActiveCount values.
totalchurncounttotalChurnCount integerinteger Die Gesamtanzahl der Abonnements, die während des angegebenen Zeitraums deaktiviert wurden.The total count of subscriptions that were deactivated during the specified time period. Dies entspricht der Summe der Werte " billingchurncount", " nonrenewalchurncount", " refundchanncount", " chargebacktschncount", " earlychurncount" und " otherchanncount ".This is equivalent to the sum of the billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount, and otherChurnCount values.
newcountnewCount integerinteger Die Anzahl der neuen Abonnement Überprüfungen innerhalb des angegebenen Zeitraums, einschließlich der Testversionen.The number of new subscription acquisitions during the specified time period, including trials.
erneuungsanzahlrenewCount integerinteger Die Anzahl der Abonnement Verlängerungen innerhalb des angegebenen Zeitraums, einschließlich der vom Benutzer initiierten Erneuerungen und automatischer Erneuerungen.The number of subscription renewals during the specified time period, including user-initiated renewals and automatic renewals.
goodstandingactivecountgoodStandingActiveCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums aktiv waren, und wobei das Ablaufdatum >= der EndDate -Wert für die Abfrage ist.The number of subscriptions that were active during the specified time period and where the expiration date is >= the endDate value for the query.
"pdinggraceactivecount"pendingGraceActiveCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums aktiv waren, bei denen ein Abrechnungsfehler aufgetreten ist und für die das Ablaufdatum des Abonnements >= der EndDate -Wert für die Abfrage ist.The number of subscriptions that were active during the specified time period but had a billing failure, and where the subscription expiration date is >= the endDate value for the query.
graceactivecountgraceActiveCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums aktiv waren, bei denen ein Abrechnungsfehler aufgetreten ist und bei dem Folgendes gilt:The number of subscriptions that were active during the specified time period but had a billing failure, and where:
  • Das Ablaufdatum des Abonnements ist < den EndDate -Wert für die Abfrage.The subscription expiration date is < the endDate value for the query.
  • Das Ende der Toleranz Periode ist >= der EndDate -Wert.The end of the grace period is >= the endDate value.
lockedactivecountlockedActiveCount integerinteger Die Anzahl der Abonnements, die sich in Dunning befanden (d. h., das Abonnement läuft bald ab, und Microsoft versucht, für die automatische Verlängerung des Abonnements Geld zu erwerben) während des angegebenen Zeitraums und in folgendem Zeitraum:The number of subscriptions that were in dunning (that is, the subscription is nearing expiration and Microsoft is trying to acquire funds to automatically renew the subscription) during the specified time period, and where:
  • Das Ablaufdatum des Abonnements ist < den EndDate -Wert für die Abfrage.The subscription expiration date is < the endDate value for the query.
  • Das Ende der Toleranz Periode ist <= der EndDate -Wert.The end of the grace period is <= the endDate value.
billingchurncountbillingChurnCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums deaktiviert wurden, weil eine Abrechnungsgebühr nicht verarbeitet werden konnte und in der sich die Abonnements zuvor in der Dämmerung befanden.The number of subscriptions that were deactivated during the specified time period because of a failure to process a billing charge and where the subscriptions were previously in dunning.
nonrenewalchurncountnonRenewalChurnCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums deaktiviert wurden, weil Sie nicht erneuert wurden.The number of subscriptions that were deactivated during the specified time period because they were not renewed.
refundchanncountrefundChurnCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums deaktiviert wurden, weil Sie zurückerstattet wurden.The number of subscriptions that were deactivated during the specified time period because they were refunded.
chargebacktschncountchargebackChurnCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums aufgrund einer Rück Belastung deaktiviert wurden.The number of subscriptions that were deactivated during the specified time period because of a chargeback.
earlychurncountearlyChurnCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums deaktiviert wurden, während Sie sich in einem ordnungsgemäßen Zustand befanden.The number of subscriptions that were deactivated during the specified time period while they were in good standing.
otherchanncountotherChurnCount integerinteger Die Anzahl der Abonnements, die während des angegebenen Zeitraums aus anderen Gründen deaktiviert wurden.The number of subscriptions that were deactivated during the specified time period for other reasons.

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.

{
  "Value": [
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9KDLGHH6R365",
      "subscriptionProductName": "Contoso App Subscription with One Month Free Trial",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "Unknown",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    },
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9JJFDHG4R478",
      "subscriptionProductName": "Contoso App Monthly Subscription",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "US",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    }
  ],
  "@nextLink": null,
  "TotalCount": 2
}