Accedere ai dati di analisi usando i servizi dello Store

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 Microsoft Entra per autenticare le chiamate dall'app o dal servizio.

I seguenti passaggi descrivono il processo end-to-end:

1. Assicurarsi di aver completato tutti i prerequisiti.
2. Prima di chiamare un metodo nell'API di analisi di Microsoft Store, ottenere un token di accesso di Microsoft Entra. 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.
3. 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 Microsoft Entra ed è necessario disporre dell'autorizzazione di amministratore globale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali di Microsoft, si dispone già di una directory Microsoft Entra. In caso contrario, è possibile crearne uno nuovo nel Centro per i partner senza costi aggiuntivi.

• È necessario associare un'applicazione Microsoft Entra all'account del Centro per i partner, recuperare l'ID tenant e l'ID client per l'applicazione e generare una chiave. L'applicazione Microsoft Entra rappresenta l'app o il servizio da cui vuoi chiamare l'API di analisi di Microsoft Store. Sono necessari l'ID tenant, l'ID client e la chiave per ottenere un token di accesso Di Microsoft Entra passato all'API.

  Nota

  È sufficiente eseguire questa attività una sola volta. Dopo aver ottenuto l'ID tenant, l'ID client e la chiave, è possibile riutilizzarli ogni volta che è necessario creare un nuovo token di accesso di Microsoft Entra.

Per associare un'applicazione Microsoft Entra all'account del Centro per i partner e recuperare i valori necessari:

1. Nel Centro per i partner associare l'account del Centro per i partner dell'organizzazione alla directory Microsoft Entra dell'organizzazione.
2. Successivamente, dalla pagina Utenti nella sezione Impostazioni account del Centro per i partner aggiungere l'applicazione Microsoft Entra che rappresenta l'app o il servizio che si userà per accedere ai dati analitici per l'account del Centro per i partner. Assicurarsi di assegnare a questa applicazione il ruolo di Manager. Se l'applicazione non esiste ancora nella directory Microsoft Entra, è possibile creare una nuova applicazione Microsoft Entra nel Centro per i partner.
3. Tornare alla pagina Gestione utenti e passare alla scheda Applicazioni Microsoft Entra, fare clic sul nome dell'applicazione Microsoft Entra per passare alle impostazioni dell'applicazione e copiare i valori ID tenant e ID client.
4. 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, vedere Gestire le chiavi per un'applicazione Microsoft Entra.

Passaggio 2: Ottenere un token di accesso di Microsoft Entra

Prima di chiamare uno dei metodi nell'API di analisi di Microsoft Store, è necessario ottenere un token di accesso Di Microsoft Entra passato all'intestazione Authorization 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'endpoint 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.

Una volta scaduto il token di accesso, puoi aggiornarlo seguendo le istruzioni qui.

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

Dopo aver ottenuto un token di accesso di Microsoft Entra, si è pronti per chiamare l'API di analisi di 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:

• Ottenere i dati sulle acquisizioni per giochi e app
• Ottenere i dati sulle acquisizioni dei componenti aggiuntivi per giochi e app

Metodi per le app UWP

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

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.

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

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 Microsoft Entra 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"
}