Recuperare dati sull'utilizzo mensile dell'app

  • Articolo

Usare questo metodo nell'API di analisi di Microsoft Store per ottenere dati aggregati sull'utilizzo (che non includono Xbox multiplayer) in formato JSON per un'applicazione durante un determinato intervallo di date (limitato agli ultimi 90 giorni) e altri filtri opzionali. Queste informazioni sono disponibili anche nel report sull'utilizzo del Centro per i partner.

I dati di telemetria per le app PWA basate su Anaheim vengono raccolti a livello di dispositivo. Pertanto, le metriche relative agli utenti non saranno disponibili per tali prodotti. Per ulteriori dettagli sulla validità dei campi, vedere la sezione Valori di utilizzo seguente.

Prerequisiti

Per usare questo metodo, è necessario prima eseguire le operazioni seguenti:

  • Se non lo si è ancora fatto, completare i prerequisiti per l'API di analisi di Microsoft Store.
  • Ottenere un token di accesso di Azure AD da usare nell'intestazione della richiesta per questo metodo. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile ottenerne uno nuovo.

Richiedi

Sintassi della richiesta

metodo URI della richiesta
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly

Intestazione della richiesta

Intestazione Type Descrizione
Autorizzazione stringa Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>.

Parametri della richiesta

Parametro Tipo Descrizione Richiesto
applicationId string ID dello Store dell'app per cui si desidera recuperare i dati sulle recensioni. Sì
startDate data Data di inizio nell'intervallo di date dei dati sulle recensioni da recuperare. L'impostazione predefinita è la data corrente. No
endDate data Data di fine nell'intervallo di date dei dati sulle recensioni da recuperare. L'impostazione predefinita è la data corrente. No
migliori int Numero di righe di dati da restituire nella richiesta. Il valore massimo e il valore predefinito, se non specificati, sono pari a 10000. Se nella query sono presenti più righe, il corpo della risposta includerà un collegamento che consente di richiedere la pagina successiva dei dati. No
skip int Numero di righe da ignorare nella query. Usare questo parametro per scorrere i set di dati di grandi dimensioni. Ad esempio, top=10000 e skip=0 recupera le prime 10.000 righe di dati, top=10000 e skip=10000 recupera le 10.000 righe di dati successive e così via. No
filter string Una o più istruzioni che filtrano le righe nella risposta. Ogni istruzione contiene un nome di campo dal corpo della risposta e dal valore associati agli operatori eq o ne e le istruzioni possono essere combinate usando e o o. I valori stringa devono essere racchiusi tra virgolette singole nel parametro filter. È possibile specificare i campi seguenti del corpo della risposta:
  • market
  • deviceType
  • packageVersion
 No
orderby string Istruzione che ordina i valori dei dati dei risultati. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
  • date
  • applicationId
  • applicationName
  • market
  • packageVersion
  • deviceType
  • subscriptionName
  • monthlySessionCount
  • engagementDurationMinutes
  • monthlyActiveUsers
  • monthlyActiveDevices
  • monthlyNewUsers
  • averageDailyActiveUsers
  • averageDailyActiveDevices
  • monthlyNewDevices

Il parametro order è facoltativo e può essere asc o desc per specificare l'ordine crescente o decrescente di ogni campo. Il valore predefinito è asc.

Di seguito è riportato un esempio di stringa orderby: orderby=date,market

 No
groupby string Istruzione che applica l'aggregazione dei dati solo ai campi specificati. È possibile specificare i campi seguenti del corpo della risposta:
  • applicationName
  • subscriptionName
  • deviceType
  • packageVersion
  • market
  • date

Le righe di dati restituite conterranno i campi specificati nel parametro groupby e i seguenti:

  • applicationId
  • subscriptionName
  • monthlySessionCount
  • engagementDurationMinutes
  • monthlyActiveUsers
  • monthlyActiveDevices
  • monthlyNewUsers
  • averageDailyActiveUsers
  • averageDailyActiveDevices
  • monthlyNewDevices

Il parametro groupby può essere usato con il parametro aggregationLevel. Ad esempio: &groupby=ageGroup,market&aggregationLevel=week

 No

Esempio di richiesta

L'esempio seguente illustra una richiesta di recupero dei dati di utilizzo mensile dell'app. Sostituire il valore applicationId con l'ID dello Store dell'app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=XXXXXXXXXXXX&startDate=2018-06-01&endDate=2018-07-01 HTTP/1.1  
Authorization: Bearer <your access token>

Response

Corpo della risposta

Valore Tipo Descrizione
valore matrice Matrice di oggetti che contengono dati aggregati sull'utilizzo. Per ulteriori informazioni sui dati in ogni oggetto, vedere la tabella seguente.
@nextLink string Se vi sono ulteriori pagine di dati, la stringa conterrà un URI che è possibile usare per richiedere la pagina di dati successiva. Ad esempio, questo valore viene restituito se il parametro top della richiesta è impostato su 10000 ma vi sono più di 10.000 righe di dati sulle recensioni per la query.
TotalCount int Numero totale di righe nei risultati di dati per la query.

 

Valori di utilizzo

Gli elementi nella matrice Value contengono i valori seguenti.

Valore Tipo Descrizione Disponibilità delle licenze UWP Disponibilità PWA basata su Anaheim Disponibilità Xbox
data string Prima data dell'intervallo di date per i dati sull'utilizzo. Se la richiesta ha specificato un singolo giorno, questo valore corrisponde alla data. Se la richiesta ha specificato una settimana, un mese o un altro intervallo di date, questo valore corrisponde alla prima data nell'intervallo di date. Sì Sì Sì
applicationId string ID dello Store dell'app per cui si stanno recuperando i dati sull'utilizzo. Sì Sì Sì
applicationName string Nome visualizzato dell'app. Sì Sì Sì
market string Codice Paese ISO 3166 del mercato in cui il cliente ha usato l'app. Sì Sì Sì
packageVersion string Versione del pacchetto in cui si è verificato l'utilizzo. Sì Sì No
deviceType string Una delle stringhe seguenti che specifica il tipo di dispositivo in cui si è verificato l'utilizzo:
  • PC
  • Telefono
  • Console-Xbox One
  • Console-Xbox Series X
  • Tablet
  • IoT
  • Server
  • Holographic
  • Unknown
 Sì Sì Sì
subscriptionName string Indica se l'utilizzo è stato effettuato tramite Xbox Game Pass. Sì No No
monthlySessionCount long Numero di sessioni utente durante il mese. Sì Sì Sì
engagementDurationMinutes double Minuti per cui gli utenti usano attivamente l'app misurati per periodo di tempo specifico, dall'avvio dell'app (avvio del processo) alla sua chiusura (fine del processo) o dopo un periodo di inattività. Sì Sì Sì
monthlyActiveUsers long Numero di clienti che usano l'app quel mese. Sì No Sì
monthlyActiveDevices long Numero di dispositivi che eseguono l'app per un periodo di tempo specifico, dall'avvio dell'app (avvio del processo) alla sua chiusura (fine del processo) o dopo un periodo di inattività. Sì Sì Sì
monthlyNewUsers long Numero di clienti che hanno usato l'app per la prima volta quel mese. Sì No Sì
averageDailyActiveUsers double Numero medio di clienti che usano l'app su base giornaliera. Sì No Sì
averageDailyActiveDevices double Numero medio di dispositivi usati per interagire con l'app da parte di tutti gli utenti su base giornaliera. Sì Sì Sì
monthlyNewDevices long Numero di dispositivi che hanno usato l'app per la prima volta in quel mese. No Sì Numero

Nota

Se un campo non è valido per un prodotto specifico, il valore relativo verrà inviato come 0 o null nella risposta. Il calcolo di nuovi utenti e nuovi dispositivi viene eseguito con la finestra mobile di 3 anni, ad esempio se un utente/dispositivo non usa l'applicazione per 3 anni e versioni successive, questi verranno considerati come nuovi utenti/dispositivi dopo 3 anni.

Esempio di richiesta e risposta

I frammenti di codice seguenti illustrano alcune richieste di esempio e il corpo della risposta JSON per tali richieste.

Richiesta di esempio

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Risposta di esempio

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "deviceType": "All",
            "packageVersion": "All",
            "market": "All",
            "engagementDurationMinutes": 2828568.3,
            "monthlyActiveUsers": 165249,
            "monthlyActiveDevices": 165753,
            "monthlyNewUsers": 95787,
            "monthlySessionCount": 314263,
            "averageDailyActiveUsers": 192.506111111111,
            "averageDailyActiveDevices": 191.199722222222,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 1
}

Richiesta di esempio

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/usagemonthly?applicationId=9NBLGGGZ5QDR&startDate=2022-06-01&endDate=2022-07-01&groupby=applicationName,subscriptionName,deviceType,packageVersion,market,date&top=10&skip=0
HTTP/1.1
Authorization: Bearer <your access token>

Risposta di esempio

{
    "Value": [
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "JP",
            "engagementDurationMinutes": 0.3,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "MX",
            "engagementDurationMinutes": 2.7,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "Unknown",
            "engagementDurationMinutes": 0.1,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "1.0.0.4957",
            "market": "US",
            "engagementDurationMinutes": 0.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AE",
            "engagementDurationMinutes": 3.2,
            "monthlyActiveUsers": 2,
            "monthlyActiveDevices": 2,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 3,
            "averageDailyActiveUsers": 0.07,
            "averageDailyActiveDevices": 0.07,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AO",
            "engagementDurationMinutes": 1.2,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AR",
            "engagementDurationMinutes": 574.7,
            "monthlyActiveUsers": 39,
            "monthlyActiveDevices": 39,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 53,
            "averageDailyActiveUsers": 1.43,
            "averageDailyActiveDevices": 1.43,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AT",
            "engagementDurationMinutes": 5.3,
            "monthlyActiveUsers": 4,
            "monthlyActiveDevices": 4,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 9,
            "averageDailyActiveUsers": 0.17,
            "averageDailyActiveDevices": 0.17,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AU",
            "engagementDurationMinutes": 434.7,
            "monthlyActiveUsers": 22,
            "monthlyActiveDevices": 22,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 36,
            "averageDailyActiveUsers": 0.9,
            "averageDailyActiveDevices": 0.9,
            "monthlyNewDevices": 0
        },
        {
            "date": "2022-06-01",
            "applicationId": "9NBLGGGZ5QDR",
            "applicationName": "Contoso Demo",
            "subscriptionName": "null",
            "deviceType": "PC",
            "packageVersion": "2.5.2.34894",
            "market": "AZ",
            "engagementDurationMinutes": 13.5,
            "monthlyActiveUsers": 1,
            "monthlyActiveDevices": 1,
            "monthlyNewUsers": 0,
            "monthlySessionCount": 1,
            "averageDailyActiveUsers": 0.03,
            "averageDailyActiveDevices": 0.03,
            "monthlyNewDevices": 0
        }
    ],
    "TotalCount": 10
}