Obtenir les acquisitions d’extensions d’inscriptionGet subscription add-on acquisitions

Utilisez cette méthode dans l’API Microsoft Store Analytics pour obtenir des données d’acquisition agrégées pour les abonnements complémentaires de votre application pendant une plage de dates donnée et d’autres filtres facultatifs.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.

PrérequisPrerequisites

Pour utiliser cette méthode, vous devez d’abord effectuer les opérations suivantes :To use this method, you need to first do the following:

  • Si vous ne l’avez pas déjà fait, renseignez toutes les conditions préalables pour l’API Microsoft Store Analytics.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Obtenez un jeton d’accès Azure AD à utiliser dans l’en-tête de requête de cette méthode.Obtain an Azure AD access token to use in the request header for this method. Une fois que vous avez récupéré le jeton d’accès, vous avez 60 minutes pour l’utiliser avant qu’il n’expire.After you obtain an access token, you have 60 minutes to use it before it expires. Une fois le jeton arrivé à expiration, vous pouvez en obtenir un nouveau.After the token expires, you can obtain a new one.

RequêteRequest

Syntaxe de la requêteRequest syntax

MéthodeMethod URI de demandeRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions

En-tête de requêteRequest header

En-têteHeader TypeType DescriptionDescription
AutorisationAuthorization stringstring Obligatoire.Required. Jeton d’accès Azure AD sous la forme Bearer <jeton>.The Azure AD access token in the form Bearer <token>.

Paramètres de la demandeRequest parameters

ParamètreParameter TypeType DescriptionDescription ObligatoireRequired
applicationIdapplicationId stringstring ID de stockage de l’application pour laquelle vous souhaitez récupérer les données d’acquisition du module complémentaire d’abonnement.The Store ID of the app for which you want to retrieve subscription add-on acquisition data. OuiYes
subscriptionProductIdsubscriptionProductId stringstring ID de stockage du module complémentaire d’abonnement pour lequel vous souhaitez récupérer les données d’acquisition.The Store ID of the subscription add-on for which you want to retrieve acquisition data. Si vous ne spécifiez pas cette valeur, cette méthode retourne les données d’acquisition pour tous les modules complémentaires d’abonnement de l’application spécifiée.If you do not specify this value, this method returns acquisition data for all subscription add-ons for the specified app. NonNo
startDatestartDate Datedate Date de début dans la plage de dates des données d’acquisition du module complémentaire d’abonnement à récupérer.The start date in the date range of subscription add-on acquisition data to retrieve. La valeur par défaut est la date actuelle.The default is the current date. NonNo
endDateendDate Datedate Date de fin dans la plage de dates des données d’acquisition du module complémentaire d’abonnement à récupérer.The end date in the date range of subscription add-on acquisition data to retrieve. La valeur par défaut est la date actuelle.The default is the current date. NonNo
toptop intint Le nombre de lignes de données à renvoyer dans la requête.The number of rows of data to return in the request. La valeur maximale et la valeur par défaut s’il n’est pas spécifié sont 100.The maximum value and the default value if not specified is 100. Si la requête comporte davantage de lignes, le corps de la réponse inclut un lien sur lequel vous cliquez pour solliciter la page suivante de données.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. NonNo
skipskip intint Le nombre de lignes à ignorer dans la requête.The number of rows to skip in the query. Utilisez ce paramètre pour parcourir de grands ensembles de données.Use this parameter to page through large data sets. Par exemple, indiquez top=100 et skip=0 pour obtenir les 100 premières lignes de données, top=100 et skip=100 pour obtenir les 100 lignes suivantes, et ainsi de suite.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. NonNo
Filterfilter stringstring Une ou plusieurs instructions qui filtrent le corps de la réponse.One or more statements that filter the response body. Chaque instruction peut utiliser les opérateurs eq ou ne ; les instructions peuvent être combinées à l’aide de and ou or.Each statement can use the eq or ne operators, and statements can be combined using and or or. Vous pouvez spécifier les chaînes suivantes dans les instructions de filtre (celles-ci correspondent aux valeurs dans le corps de la réponse) :You can specify the following strings in the filter statements (these correspond to values in the response body):
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • négocimarket
  • deviceTypedeviceType

Voici un exemple de paramètre de filtre : Filter = date EQ' 2017-07-08 '.Here is an example filter parameter: filter=date eq '2017-07-08'.

NonNo
aggregationLevelaggregationLevel stringstring Indique la plage de temps pendant laquelle récupérer les données agrégées.Specifies the time range for which to retrieve aggregate data. Il peut s’agit des chaînes suivantes : day, week ou month.Can be one of the following strings: day, week, or month. Par défaut, la valeur est day.If unspecified, the default is day. NonNo
orderbyorderby stringstring Instruction qui classe les valeurs des données de résultat pour chaque acquisition du module complémentaire d’abonnement.A statement that orders the result data values for each subscription add-on acquisition. La syntaxe est orderby = Field [Order], champ [Order],.... Le paramètre Field peut être l’une des chaînes suivantes :The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • négocimarket
  • deviceTypedeviceType

Le paramètre order, facultatif, peut comporter les valeurs asc ou desc afin de spécifier l’ordre croissant ou décroissant pour chaque champ.The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. La valeur par défaut est ASC.The default is asc.

Voici un exemple de chaîne orderby : orderby = date, MarketHere is an example orderby string: orderby=date,market

NonNo
groupbygroupby stringstring Une instruction qui applique l’agrégation des données uniquement sur les champs spécifiés.A statement that applies data aggregation only to the specified fields. Vous pouvez spécifier les champs suivants :You can specify the following fields:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • négocimarket
  • deviceTypedeviceType

Le paramètre groupby peut être utilisé avec le paramètre aggregationLevel.The groupby parameter can be used with the aggregationLevel parameter. Par exemple : GroupBy = Market & aggregationLevel = weekFor example: groupby=market&aggregationLevel=week

NonNo

Exemple de requêteRequest example

Les exemples suivants montrent comment récupérer des données d’acquisition de compléments d’abonnement.The following examples demonstrates how to get subscription add-on acquisition data. Remplacez la valeur ApplicationID par l’ID de magasin approprié pour votre application.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>

responseResponse

Response bodyResponse body

ValeurValue TypeType DescriptionDescription
ValeurValue tableauarray Tableau d’objets qui contiennent les données d’acquisition du module complémentaire d’abonnement de l’agrégat.An array of objects that contain aggregate subscription add-on acquisition data. Pour plus d’informations sur les données de chaque objet, consultez la section valeurs d’acquisition d’abonnement ci-dessous.For more information about the data in each object, see the subscription acquisition values section below.
@nextLink stringstring S’il existe des pages supplémentaires de données, cette chaîne comporte un URI que vous pouvez utiliser pour solliciter la page suivante de données.If there are additional pages of data, this string contains a URI that you can use to request the next page of data. Par exemple, cette valeur est retournée si le paramètre supérieur de la demande est défini sur 100, mais qu’il y a plus de 100 lignes de données d’acquisition du module complémentaire d’abonnement pour la requête.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 Nombre total de lignes dans les résultats de la requête.The total number of rows in the data result for the query.

Valeurs d’acquisition d’abonnementSubscription acquisition values

Les éléments du tableau Value comportent les valeurs suivantes :Elements in the Value array contain the following values.

ValeurValue TypeType DescriptionDescription
Datedate stringstring Première date dans la plage de dates des données d’acquisition.The first date in the date range for the acquisition data. Si la requête spécifiait un jour précis, cette valeur correspond à la date.If the request specified a single day, this value is that date. Si la requête était relative à une semaine, un mois ou toute autre plage de dates, cette valeur correspond à la première date de la plage de dates.If the request specified a week, month, or other date range, this value is the first date in that date range.
subscriptionProductIdsubscriptionProductId stringstring ID de stockage du module complémentaire d’abonnement pour lequel vous extrayez des données d’acquisition.The Store ID of the subscription add-on for which you are retrieving acquisition data.
subscriptionProductNamesubscriptionProductName stringstring Nom complet du module complémentaire d’abonnement.The display name of the subscription add-on.
applicationIdapplicationId stringstring ID de stockage de l’application pour laquelle vous récupérez les données d’acquisition du module complémentaire d’abonnement.The Store ID of the app for which you are retrieving subscription add-on acquisition data.
applicationNameapplicationName stringstring Nom d’affichage de l’application.The display name of the app.
skuIdskuId stringstring ID de la référence SKU du module complémentaire d’abonnement pour lequel vous extrayez des données d’acquisition.The ID of the SKU of the subscription add-on for which you are retrieving acquisition data.
deviceTypedeviceType stringstring L’une des chaînes suivantes qui spécifie le type de périphérique qui a effectué l’acquisition :One of the following strings that specifies the type of device that completed the acquisition:
  • PCPC
  • NumérosPhone
  • Console-Xbox OneConsole-Xbox One
  • Console-série Xbox XConsole-Xbox Series X
  • IoTIoT
  • HologrammesHolographic
  • UnknownUnknown
marketmarket stringstring Le code pays ISO 3166 du marché dans lequel l’acquisition s’est produite.The ISO 3166 country code of the market where the acquisition occurred.
currencyCodecurrencyCode stringstring Code de la devise au format ISO 4217 pour les ventes brutes avant taxes.The currency code in ISO 4217 format for gross sales before taxes.
grossSalesBeforeTaxgrossSalesBeforeTax entierinteger Ventes brutes dans la devise locale spécifiée par la valeur currencyCode .The gross sales in the local currency specified by the currencyCode value.
totalActiveCounttotalActiveCount entierinteger Nombre total d’abonnements actifs au cours de la période spécifiée.The number of total active subscriptions during the specified time period. Cela équivaut à la somme des valeurs goodStandingActiveCount, pendingGraceActiveCount, graceActiveCountet lockedActiveCount .This is equivalent to the sum of the goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount, and lockedActiveCount values.
totalChurnCounttotalChurnCount entierinteger Nombre total d’abonnements qui ont été désactivés au cours de la période spécifiée.The total count of subscriptions that were deactivated during the specified time period. Cela équivaut à la somme des valeurs billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCountet otherChurnCount .This is equivalent to the sum of the billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount, and otherChurnCount values.
newCountnewCount entierinteger Nombre de nouvelles acquisitions d’abonnements au cours de la période spécifiée, y compris les versions d’évaluation.The number of new subscription acquisitions during the specified time period, including trials.
renewCountrenewCount entierinteger Nombre de renouvellements d’abonnements au cours de la période spécifiée, y compris les renouvellements initiés par l’utilisateur et les renouvellements automatiques.The number of subscription renewals during the specified time period, including user-initiated renewals and automatic renewals.
goodStandingActiveCountgoodStandingActiveCount entierinteger Nombre d’abonnements qui étaient actifs au cours de la période spécifiée et où la date d’expiration est >= la valeur de date de fin de la requête .The number of subscriptions that were active during the specified time period and where the expiration date is >= the endDate value for the query.
pendingGraceActiveCountpendingGraceActiveCount entierinteger Nombre d’abonnements actifs au cours de la période spécifiée, mais avec un échec de facturation, et où la date d’expiration de l’abonnement est >= la valeur de la date de fin de la requête.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 entierinteger Nombre d’abonnements qui ont été actifs au cours de la période spécifiée mais dont la facturation a échoué, et où :The number of subscriptions that were active during the specified time period but had a billing failure, and where:
  • La date d’expiration de l’abonnement est < la valeur de EndDate pour la requête.The subscription expiration date is < the endDate value for the query.
  • La fin de la période de grâce est >= la valeur de EndDate .The end of the grace period is >= the endDate value.
lockedActiveCountlockedActiveCount entierinteger Le nombre d’abonnements qui se trouvaient dans rappels (autrement dit, l’abonnement est proche de l’expiration et Microsoft tente d’acquérir des fonds pour renouveler automatiquement l’abonnement) au cours de la période spécifiée, et où :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:
  • La date d’expiration de l’abonnement est < la valeur de EndDate pour la requête.The subscription expiration date is < the endDate value for the query.
  • La fin de la période de grâce est <= la valeur de EndDate .The end of the grace period is <= the endDate value.
billingChurnCountbillingChurnCount entierinteger Nombre d’abonnements désactivés au cours de la période spécifiée en raison d’un échec de traitement des frais de facturation et de l’emplacement des abonnements précédemment dans rappels.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 entierinteger Nombre d’abonnements qui ont été désactivés au cours de la période spécifiée, car ils n’ont pas été renouvelés.The number of subscriptions that were deactivated during the specified time period because they were not renewed.
refundChurnCountrefundChurnCount entierinteger Nombre d’abonnements qui ont été désactivés au cours de la période spécifiée, car ils ont été remboursés.The number of subscriptions that were deactivated during the specified time period because they were refunded.
chargebackChurnCountchargebackChurnCount entierinteger Nombre d’abonnements désactivés au cours de la période spécifiée en raison d’une facturation.The number of subscriptions that were deactivated during the specified time period because of a chargeback.
earlyChurnCountearlyChurnCount entierinteger Nombre d’abonnements qui ont été désactivés au cours de la période spécifiée alors qu’ils étaient en bonne position.The number of subscriptions that were deactivated during the specified time period while they were in good standing.
otherChurnCountotherChurnCount entierinteger Nombre d’abonnements qui ont été désactivés au cours de la période spécifiée pour d’autres raisons.The number of subscriptions that were deactivated during the specified time period for other reasons.

Exemple de réponseResponse example

L’exemple suivant représente un corps de réponse JSON pour cette requête.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
}