Partager via

Obtenir des acquisitions de modules complémentaires d’abonnement

Utilisez cette méthode dans l’API d’analyse du Microsoft Store 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.

Conditions préalables

Pour utiliser cette méthode, vous devez d’abord effectuer les opérations suivantes :

  • Si vous ne l’avez pas déjà fait, remplissez tous les prérequis pour l’API d’analytique du Microsoft Store.
  • Obtenez 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 la requête
OBTENIR https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions

En-tête de requête

En-tête de page Catégorie Descriptif
Autorisation ficelle Obligatoire. Jeton d’accès Azure AD sous forme de Bearer<token>.

Paramètres de la demande

Paramètre Catégorie Descriptif Obligatoire
applicationId ficelle ID du Store de l’application pour laquelle vous souhaitez récupérer les données d’acquisition du module d’abonnement. Oui
identifiantProduitAbonnement ficelle L’ID Store de l’extension d’abonnement pour laquelle vous voulez récupérer des 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
date de début 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
date de fin 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 de page Int Nombre de lignes de données à retourner dans la requête. La valeur maximale et la valeur par défaut si elle n’est pas spécifiée est 100. 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
passer 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 ficelle 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 etou. 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) :
  • date
  • subscriptionProductName
  • nomapplication
  • skuId
  • marché
  • type d'appareil

Voici un exemple de paramètre de filtre : filter=date eq '2017-07-08'.

 Non
niveau d'agrégation ficelle 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. S’il n’est pas spécifié, la valeur par défaut est le jour. Non
classer par ficelle Instruction qui organise les valeurs de données de résultat pour chaque acquisition d’options d’abonnement. La syntaxe est orderby=field [order],field [order],.... Le paramètre de champ peut être l’une des chaînes suivantes :
  • date
  • subscriptionProductName
  • nomapplication
  • skuId
  • marché
  • type d'appareil

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
grouppar ficelle Instruction qui applique l’agrégation de données uniquement aux champs spécifiés. Vous pouvez spécifier les champs suivants :
  • date
  • subscriptionProductName
  • nomapplication
  • skuId
  • marché
  • type d'appareil

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>

Réponse

Corps de réponse

Valeur Catégorie Descriptif
Valeur tableau Tableau d’objets contenant des données agrégées sur l'acquisition de modules complémentaires d’abonnement. Pour plus d’informations sur les données de chaque objet, consultez la section valeurs d’acquisition d’abonnement ci-dessous.
@nextLink ficelle 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.
NombreTotal 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 Value contiennent les valeurs suivantes.

Valeur Catégorie Descriptif
date ficelle La date de début 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 demande 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.
identifiantProduitAbonnement ficelle L’ID Store de l’extension d’abonnement pour laquelle vous récupérez des données d’acquisition.
NomDuProduitDAbonnement ficelle Nom complet du module complémentaire d’abonnement.
applicationId ficelle ID du Store de l’application pour laquelle vous récupérez les données d’acquisition des extensions d’abonnement.
Nom de l'application ficelle Nom d'affichage de l'application.
skuId ficelle ID de la référence SKU du module complémentaire d’abonnement pour lequel vous récupérez des données d’acquisition.
type de dispositif ficelle Une chaîne suivante spécifiant le type d'appareil ayant achevé l'acquisition :
  • PC
  • Téléphone
  • Console-Xbox Un
  • Console-Xbox Série X
  • IdO
  • Holographique
  • Inconnu
marché ficelle Code pays ISO 3166 du marché où l’acquisition s’est produite.
code de devise ficelle Code monétaire au format ISO 4217 pour les ventes brutes avant taxes.
ventesBrutesAvantTaxes 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 .
nombre total de désabonnements 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 otherChurnCount.
nouveauNombre 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.
nombreActifBonnePosition 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ù :
  • La date d’expiration de l’abonnement est < la valeur endDate de la requête.
  • La fin de la période de grâce est >= la valeur de endDate.
lockedActiveCount entier Nombre d’abonnements qui étaient dans de (autrement dit, l’abonnement approche de l’expiration et Microsoft essaie d’acquérir des fonds pour renouveler automatiquement l’abonnement) pendant la période spécifiée, et où :
  • La date d’expiration de l’abonnement est < la valeur endDate de la requête.
  • La fin de la période de grâce est <= la valeur de endDate.
facturationChurnCount entier Nombre d’abonnements qui ont été désactivés pendant la période spécifiée en raison d’un échec du traitement d'un montant de facturation et où les abonnements étaient précédemment en cours de recouvrement.
compteDesAbandonsNonRenouvelés 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 rétrofacturation.
earlyChurnCount entier Nombre d’abonnements qui ont été désactivés pendant la période spécifiée pendant qu’ils étaient en bonne position.
otherChurnCount entier Nombre d’abonnements qui ont été désactivés pendant la période spécifiée pour d’autres raisons.

Exemple de demande 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
}

 

 

  • Last updated on