Obtenir les acquisitions d’extensions d’inscription
Utilisez cette méthode dans l’API d’analyse de la Boutique Microsoft pour obtenir des données d’acquisition agrégées pour les abonnements de module complémentaire pour votre application pendant une plage de dates donnée et d’autres filtres facultatifs.
Prérequis
Pour utiliser cette méthode, vous devez d’abord effectuer les opérations suivantes :
- Si ce n’est pas déjà fait, remplissez toutes les conditions préalables relatives à l’API d’analyse de la Boutique Microsoft.
- Obtenir un jeton d’accès Azure AD à utiliser dans l’en-tête de requête pour cette méthode. 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. Une fois le jeton expiré, vous pouvez en obtenir un nouveau.
Requête
Syntaxe de la requête
| Méthode | URI de demande |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions |
En-tête de requête
| En-tête | Type | Description |
|---|---|---|
| Autorisation | string | Obligatoire. Jeton d’accès Azure AD au format porteur<jeton>. |
Paramètres de la demande
| Paramètre | Type | Description | Obligatoire |
|---|---|---|---|
| applicationId | string | ID Store de l’application pour laquelle vous souhaitez récupérer les données d’acquisition d’extension d’abonnement. | Oui |
| subscriptionProductId | string | ID Store du module complémentaire d’abonnement pour lequel vous souhaitez récupérer les données d’acquisition. 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 pour l’application spécifiée. | Non |
| startDate | date | Date de début dans la plage de dates des données d’acquisition d’extension d’abonnement à récupérer. La valeur par défaut est la date actuelle. | Non |
| endDate | date | Date de fin dans la plage de dates des données d’acquisition d’extension d’abonnement à récupérer. La valeur par défaut est la date actuelle. | Non |
| haut | int | Nombre de lignes de données à retourner dans la requête. La valeur maximale, soit la valeur par défaut, est 100 (si cette valeur n’est pas spécifiée). S’il existe plus de lignes dans la requête, le corps de la réponse inclut un lien suivant que vous pouvez utiliser pour demander la page suivante de données. | Non |
| skip | int | Nombre de lignes à ignorer dans la requête. Utilisez ce paramètre pour parcourir des jeux de données volumineux. Par exemple, top=100 et skip=0 récupère les 100 premières lignes de données, top=100 et skip=100 récupère les 100 lignes de données suivantes, et ainsi de suite. | Non |
| filter | string | Une ou plusieurs instructions qui filtrent le corps de la réponse. Chaque instruction peut utiliser les opérateurs eq ou ne, et les instructions peuvent être combinées à l’aide et ou ou. 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) :
Voici un exemple de paramètre de filtre : filter=date eq '2017-07-08'. |
Non |
| aggregationLevel | string | Spécifie l’intervalle de temps pour lequel récupérer des données agrégées. Il peut s’agir de l’une des chaînes suivantes : jour, semaine ou mois. Si aucune valeur n’est spécifiée, la valeur par défaut est jour. | Non |
| orderby | string | Instruction qui commande les valeurs de données de résultat pour chaque acquisition d’extension d’abonnement. La syntaxe est orderby=field [order],field [order],.... Le paramètre de champ peut être l’une des chaînes suivantes :
Le paramètre d’ordre est facultatif et peut être asc ou desc pour spécifier l’ordre croissant ou décroissant pour chaque champ. La valeur par défaut est asc. Voici un exemple de chaîne orderby : orderby=date,market |
Non |
| groupby | string | Instruction qui applique l’agrégation de données uniquement aux champs spécifiés. Spécifiez les champs suivants :
Le paramètre groupby peut être utilisé avec le paramètre aggregationLevel. Par exemple : groupby=market&aggregationLevel=week |
Non |
Exemple de requête
Les exemples suivants montrent comment obtenir des données d’acquisition d’extension d’abonnement. Remplacez la valeur applicationId par l’ID Store approprié pour votre application.
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>
Response
Response body
| Valeur | Type | Description |
|---|---|---|
| active | tableau | Tableau d’objets qui contiennent des données d’acquisition d’extension d’abonnement agrégées. Pour plus d’informations sur les données de chaque objet, consultez la section valeurs d’acquisition d’abonnement ci-dessous. |
| @nextLink | string | S’il existe des pages de données supplémentaires, cette chaîne contient un URI que vous pouvez utiliser pour demander la page suivante des données. Par exemple, cette valeur est retournée si le paramètre supérieur de la requête est défini sur 100, mais qu’il existe plus de 100 lignes de données d’acquisition d’extension d’abonnement pour la requête. |
| TotalCount | int | Nombre total de lignes dans le résultat des données de la requête. |
Valeurs d’acquisition d’abonnement
Les éléments du tableau Valeur contiennent les valeurs suivantes.
| Valeur | Type | Description |
|---|---|---|
| date | string | La première date de la plage de dates pour les données d’acquisition. Si la demande a spécifié un jour unique, cette valeur est cette date. Si la requête a spécifié une semaine, un mois ou une autre plage de dates, cette valeur est la première date de cette plage de dates. |
| subscriptionProductId | string | ID Store du module complémentaire d’abonnement pour lequel vous récupérez des données d’acquisition. |
| subscriptionProductName | string | Nom d’affichage de l’extension d’abonnement. |
| applicationId | string | ID Store de l’application pour laquelle vous récupérez des données d’acquisition d’extension d’abonnement. |
| applicationName | string | Nom complet de l'application. |
| skuId | string | ID du SKU du module complémentaire d’abonnement pour lequel vous récupérez des données d’acquisition. |
| deviceType | string | Une des chaînes suivantes qui spécifie le type d’appareil qui a terminé l’acquisition :
|
| market | string | Code pays ISO 3166 du marché où l’acquisition s’est produite. |
| currencyCode | string | Code monétaire au format ISO 4217 pour les ventes brutes avant taxes. |
| grossSalesBeforeTax | entier | Ventes brutes dans la devise locale spécifiée par la valeur currencyCode. |
| totalActiveCount | entier | Nombre total d’abonnements actifs pendant la période spécifiée. Cela équivaut à la somme des valeurs goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount et lockedActiveCount. |
| totalChurnCount | entier | Nombre total d’abonnements qui ont été désactivés pendant la période spécifiée. Cela équivaut à la somme de billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount et autres valeursChurnCount. |
| newCount | entier | Nombre de nouvelles acquisitions d’abonnements pendant la période spécifiée, y compris les essais. |
| renewCount | entier | Nombre de renouvellements d’abonnement pendant la période spécifiée, y compris les renouvellements initiés par l’utilisateur et les renouvellements automatiques. |
| goodStandingActiveCount | entier | Nombre d’abonnements actifs pendant la période spécifiée et où la date d’expiration est >= la valeur endDate de la requête. |
| pendingGraceActiveCount | entier | Nombre d’abonnements actifs pendant la période spécifiée, mais ayant un échec de facturation, et où la date d’expiration de l’abonnement est >= la valeur endDate de la requête. |
| graceActiveCount | entier | Nombre d’abonnements actifs pendant la période spécifiée, mais ayant un échec de facturation et où :
|
| lockedActiveCount | entier | Le nombre d’abonnements qui étaient en service (autrement dit, l’abonnement est proche de l’expiration et Microsoft tente d’acquérir des fonds pour renouveler automatiquement l’abonnement) pendant la période spécifiée, et où :
|
| billingChurnCount | entier | Nombre d’abonnements qui ont été désactivés pendant la période spécifiée en raison d’un échec de traitement d’un frais de facturation et où les abonnements étaient précédemment au statut de relance. |
| nonRenewalChurnCount | entier | Nombre d’abonnements désactivés pendant la période spécifiée, car ils n’ont pas été renouvelés. |
| refundChurnCount | entier | Nombre d’abonnements désactivés pendant la période spécifiée, car ils ont été remboursés. |
| chargebackChurnCount | entier | Nombre d’abonnements qui ont été désactivés pendant la période spécifiée en raison d’une facturation interne. |
| earlyChurnCount | entier | Nombre d’abonnements qui ont été désactivés pendant la période spécifiée pendant qu’ils étaient en règle. |
| otherChurnCount | entier | Nombre d’abonnements qui ont été désactivés pendant la période spécifiée pour d’autres raisons. |
Exemple de requête et de réponse
Les extraits de code suivants illustrent un exemple de corps de requête et de réponse JSON pour cette requête.
Exemple de requête
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
Exemple de réponse
{
"Value": [
{
"date": "2022-04-18",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"grossSalesBeforeTax": 3460656.260391250,
"totalActiveCount": 20211321,
"totalChurnCount": 5605,
"newCount": 3810366,
"renewCount": 12102044,
"goodStandingActiveCount": 17893664,
"pendingGraceActiveCount": 2255792,
"graceActiveCount": 61833,
"lockedActiveCount": 32,
"billingChurnCount": 4,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 2717,
"otherChurnCount": 2884
},
{
"date": "2022-04-18",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Unknown",
"grossSalesBeforeTax": 2342.580615228,
"totalActiveCount": 50550,
"totalChurnCount": 7,
"newCount": 8312,
"renewCount": 31446,
"goodStandingActiveCount": 44047,
"pendingGraceActiveCount": 6503,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 5,
"otherChurnCount": 2
}
],
"TotalCount": 2
}
Exemple de requête
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=12/19/2021&endDate=04/20/2022&top=10&skip=0&orderby=date&groupby=date,subscriptionProductName,applicationName,skuId,market,deviceType&aggregationLevel=week
HTTP/1.1
Authorization: Bearer <your access token>
Exemple de réponse
{
"Value": [
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "IT",
"deviceType": "Console-Xbox One",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 0,
"totalChurnCount": 0,
"newCount": 2,
"renewCount": 0,
"goodStandingActiveCount": 0,
"pendingGraceActiveCount": 0,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
},
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "NO",
"deviceType": "Unknown",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 0,
"totalChurnCount": 0,
"newCount": 0,
"renewCount": 13,
"goodStandingActiveCount": 0,
"pendingGraceActiveCount": 0,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
},
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.02",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "CA",
"deviceType": "Unknown",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 152,
"totalChurnCount": 0,
"newCount": 0,
"renewCount": 270,
"goodStandingActiveCount": 133,
"pendingGraceActiveCount": 19,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
}
],
"TotalCount": 3
}
Rubriques connexes
- Rapport sur les acquisitions des extensions
- Accéder aux données d’analyse à l’aide des services de la Boutique Microsoft