Accedere ai dati di analisi usando i servizi dello Store

Articolo
04/01/2024

Usare l'API di analisi Microsoft Store per recuperare a livello di codice i dati analitici per le app registrate nell'account windows del Partner Center dell'utente o dell'organizzazione. Questa API consente di recuperare i dati per app e componenti aggiuntivi (noti anche come acquisizioni di prodotti in-app o IAP), errori, valutazioni e recensioni delle app. Questa API usa Azure Active Directory (Azure AD) per autenticare le chiamate dall'app o dal servizio.

Nelle istruzioni seguenti viene descritto il processo end-to-end:

Assicurarsi di aver completato tutti i prerequisiti.
Prima di chiamare un metodo nell'API di analisi di Microsoft Store, ottenere un token di accesso di Azure AD. Dopo aver ottenuto un token, hai 60 minuti per usare questo token nelle chiamate all'API di analisi Microsoft Store prima della scadenza del token. Dopo la scadenza del token, è possibile generare un nuovo token.
Chiamare l'API di analisi di Microsoft Store.

Passaggio 1: completare i prerequisiti per l'uso dell'API di analisi Microsoft Store

Prima di iniziare a scrivere il codice per chiamare l'API di analisi Microsoft Store, verificare di aver completato i prerequisiti seguenti.

L'utente o l'organizzazione deve disporre di una directory di Azure AD e dell'autorizzazione come amministratore aziendale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali Microsoft, si dispone già di una directory di Azure AD. In caso contrario, è possibile creare una nuova directory di Azure AD nel Partner Center senza costi aggiuntivi.
È necessario associare un'applicazione Azure AD all'account del Centro per i partner, recuperare l'ID tenant e l'ID client per l'applicazione e generare una chiave. L'applicazione Azure AD rappresenta l'app o il servizio da cui si vuole chiamare l'API di analisi Microsoft Store. Per ottenere un token di accesso di Azure AD da passare all'API, sono necessari l'ID tenant, l'ID client e la chiave.

Nota

È sufficiente eseguire questa attività una sola volta. Quando si dispone di ID tenant, ID client e chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso Azure AD.

Per associare un'applicazione Azure AD all'account del Partner Center e recuperare i valori necessari:

Nel Centro per i partner, associare l'account del Centro per i partner dell'organizzazione alla directory di Azure AD dell'organizzazione.
Quindi, dalla pagina Utenti nella sezione Impostazioni account del Centro per i partner, aggiungere l'applicazione Azure AD che rappresenta l'app o il servizio che verrà usato per accedere ai dati di analisi dell'account Partner Center. Assicurarsi di assegnare a questa applicazione il ruolo di Manager. Se l'applicazione non esiste ancora nella directory di Azure AD, è possibile creare una nuova applicazione Azure AD nel Centro per i partner.
Tornare alla pagina Utenti, fare clic sul nome dell'applicazione Azure AD per passare alle impostazioni e copiare i valori di ID tenant e ID client.
Fare clic su Aggiungi nuova chiave. Nella schermata seguente, copiare il valore della chiave. Non sarà più possibile accedere a queste informazioni dopo aver lasciato la pagina. Per altre informazioni, vedi Gestire le chiavi per un'applicazione Azure AD.

Passaggio 2: ottenere un token di accesso di Azure AD

Prima di chiamare un metodo nell'API di analisi Microsoft Store, è necessario ottenere un token di accesso di Azure AD da passare all'intestazione Autorizzazione di ogni metodo nell'API. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile aggiornarlo in modo da continuare a usarlo nelle successive chiamate all'API.

Per ottenere il token di accesso, seguire le istruzioni riportate in Chiamate da servizio a servizio mediante le credenziali client per inviare un HTTP POST all'endopoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Di seguito è riportata una richiesta di esempio.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://manage.devcenter.microsoft.com

Per il valore tenant_id in POST URI e per i parametri client_id e client_secret, specificare l'ID tenant, l'ID client e la chiave per l'applicazione recuperati dal Centro per i partner nella sezione precedente. Per il parametro resource è necessario specificare https://manage.devcenter.microsoft.com.

Dopo la scadenza del token di accesso, è possibile aggiornarlo seguendo le istruzioni riportate qui.

> [!NOTE]
> ResourceType='Graph.windows.net' will be deprecated after September 2023. Please migrate to ResourceType ='Graph.microsoft.com'

Passaggio 3: Chiamare l'API di analisi di Microsoft Store

Dopo aver ottenuto un token di accesso di Azure AD, è possibile chiamare l'API di analisi Microsoft Store. È necessario passare il token di accesso all'intestazione Autorizzazione di ogni metodo.

Metodi per app e giochi UWP

Per le app e le acquisizioni di giochi e acquisizioni di componenti aggiuntivi sono disponibili i metodi seguenti:

Metodi per le app UWP

I metodi di analisi seguenti sono disponibili per le app UWP nel Partner Center.

Scenario	Metodi
Acquisizioni, conversioni, installazioni e utilizzo	Ottenere le acquisizioni dell'app (precedenti) Recuperare i dati dell'imbuto per le acquisizioni di app (precedenti) Recuperare le conversioni di app per canale Ottenere le acquisizioni dei componenti aggiuntivi Recuperare le acquisizioni dei componenti aggiuntivi di sottoscrizione Recuperare le conversioni dei componenti aggiuntivi per canale Recuperare le installazioni di app Recuperare dati sull'utilizzo giornaliero dell'app Recuperare dati sull'utilizzo mensile dell'app
Errori dell'app	Ottenere i dati di segnalazione degli errori Ottenere i dettagli per un errore nell'app Recuperare l'analisi dello stack per un errore nell'app Scaricare il file CAB per un errore nell'app
Informazioni dettagliate	Recuperare informazioni sui dati per la tua app
Recensioni e valutazioni	Ottenere le classificazioni dell'app Ottenere le recensioni dell'app
Annunci in-app e campagne pubblicitarie	Ottenere dati sul rendimento degli annunci Ottenere i dati sulle prestazioni delle campagne pubblicitarie

Metodi per le applicazioni desktop

I metodi di analisi seguenti sono disponibili per l'uso da parte degli account sviluppatore che appartengono al programma Applicazione desktop di Windows.

Scenario	Metodi
Installs	Recuperare le installazioni di applicazioni desktop
Blocchi	Ottenere blocchi di aggiornamento per l'applicazione desktop Ottenere i dettagli dei blocchi di aggiornamento per l'applicazione desktop
Errori delle applicazioni	Recuperare i dati sulla segnalazione di errori per l'applicazione desktop Recuperare i dettagli su un errore nell'applicazione desktop Recuperare l'analisi dello stack per un errore nell'applicazione desktop Scaricare il file CAB per un errore nell'applicazione desktop
Informazioni dettagliate	Ottenere informazioni dettagliate per l'applicazione desktop

Metodi per i servizi Xbox Live

I metodi aggiuntivi seguenti sono disponibili per l'uso da parte degli account per sviluppatori con giochi che usano i servizi Xbox Live. L'API di Analisi di Microsoft Store per Xbox non è più disponibile. gaming/xbox-live/get-started/join-dev-program/join-dev-program_nav

Scenario	Metodi
Analisi generiche	Recuperare i dati di analisi di Xbox Live

Metodi per hardware e driver

Gli account per sviluppatori che appartengono al programma dashboard hardware di Windows hanno accesso a un set aggiuntivo di metodi per il recupero dei dati di analisi per hardware e driver. Per maggiori informazioni, vedere Hardware dashboard API.

Esempio di codice

L'esempio di codice seguente illustra come ottenere un token di accesso di Azure AD e chiamare l'API di analisi di Microsoft Store da un'app console C#. Per usare questo esempio di codice, assegnare le variabili tenantId, clientId, clientSecret, and appID ai valori appropriati per lo scenario. Questo esempio richiede che il pacchetto Json.NET di Newtonsoft deserializzi i dati JSON restituiti dall'API di analisi di Microsoft Store.

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

namespace TestAnalyticsAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            string tenantId = "<your tenant ID>";
            string clientId = "<your client ID>";
            string clientSecret = "<your secret>";

            string scope = "https://manage.devcenter.microsoft.com";

            // Retrieve an Azure AD access token
            string accessToken = GetClientCredentialAccessToken(
                    tenantId,
                    clientId,
                    clientSecret,
                    scope).Result;

            // This is your app's Store ID. This ID is available on
            // the App identity page of the Dev Center dashboard.
            string appID = "<your app's Store ID>";

            DateTime startDate = DateTime.Parse("08-01-2015");
            DateTime endDate = DateTime.Parse("11-01-2015");
            int pageSize = 1000;
            int startPageIndex = 0;

            // Call the Windows Store analytics API
            CallAnalyticsAPI(accessToken, appID, startDate, endDate, pageSize, startPageIndex);

            Console.Read();
        }

        private static void CallAnalyticsAPI(string accessToken, string appID, DateTime startDate, DateTime endDate, int top, int skip)
        {
            string requestURI;

            // Get app acquisitions
            requestURI = string.Format(
                "https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
                appID, startDate, endDate, top, skip);

            //// Get add-on acquisitions
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app failures
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/failurehits?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app ratings
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/ratings?applicationId={0}&startDate={1}&endDate={2}top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            //// Get app reviews
            //requestURI = string.Format(
            //    "https://manage.devcenter.microsoft.com/v1.0/my/analytics/reviews?applicationId={0}&startDate={1}&endDate={2}&top={3}&skip={4}",
            //    appID, startDate, endDate, top, skip);

            HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, requestURI);
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

            WebRequestHandler handler = new WebRequestHandler();
            HttpClient httpClient = new HttpClient(handler);

            HttpResponseMessage response = httpClient.SendAsync(requestMessage).Result;

            Console.WriteLine(response);
            Console.WriteLine(response.Content.ReadAsStringAsync().Result);

            response.Dispose();
        }

        public static async Task<string> GetClientCredentialAccessToken(string tenantId, string clientId, string clientSecret, string scope)
        {
            string tokenEndpointFormat = "https://login.microsoftonline.com/{0}/oauth2/token";
            string tokenEndpoint = string.Format(tokenEndpointFormat, tenantId);

            dynamic result;
            using (HttpClient client = new HttpClient())
            {
                string tokenUrl = tokenEndpoint;
                using (
                    HttpRequestMessage request = new HttpRequestMessage(
                        HttpMethod.Post,
                        tokenUrl))
                {
                    string content =
                        string.Format(
                            "grant_type=client_credentials&client_id={0}&client_secret={1}&resource={2}",
                            clientId,
                            clientSecret,
                            scope);

                    request.Content = new StringContent(content, Encoding.UTF8, "application/x-www-form-urlencoded");

                    using (HttpResponseMessage response = await client.SendAsync(request))
                    {
                        string responseContent = await response.Content.ReadAsStringAsync();
                        result = JsonConvert.DeserializeObject(responseContent);
                    }
                }
            }

            return result.access_token;
        }
    }
}

Risposte di errore

L'API di analisi Microsoft Store restituisce risposte di errore in un oggetto JSON che contiene codici di errore e messaggi. Nell'esempio seguente viene illustrata una risposta di errore causata da un parametro non valido.

{
    "code":"BadRequest",
    "data":[],
    "details":[],
    "innererror":{
        "code":"InvalidQueryParameters",
        "data":[
            "top parameter cannot be more than 10000"
        ],
        "details":[],
        "message":"One or More Query Parameters has invalid values.",
        "source":"AnalyticsAPI"
    },
    "message":"The calling client sent a bad request to the service.",
    "source":"AnalyticsAPI"
}