Acessar dados analíticos usando serviços da StoreAccess analytics data using Store services

Use a API de análise de Microsoft Store para recuperar dados de análise programaticamente para aplicativos registrados em sua conta do Windows Partner Center da sua organização.Use the Microsoft Store analytics API to programmatically retrieve analytics data for apps that are registered to your or your organization's Windows Partner Center account. Essa API permite que você recupere dados para aquisições de aplicativos e complementos (também conhecidos como produto no aplicativo ou IAP), erros, classificações de aplicativos e avaliações.This API enables you to retrieve data for app and add-on (also known as in-app product or IAP) acquisitions, errors, app ratings and reviews. Essa API usa o Active Directory do Azure (Azure AD) para autenticar as chamadas do seu aplicativo ou serviço.This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

As etapas a seguir descrevem o processo completo:The following steps describe the end-to-end process:

  1. Certifique-se de que você tenha concluído todos os pré-requisitos.Make sure that you have completed all the prerequisites.
  2. Antes de chamar um método na API de análise da Microsoft Store obtenha um token de acesso do Azure AD.Before you call a method in the Microsoft Store analytics API, obtain an Azure AD access token. Depois de obter um token, você tem 60 minutos para usá-lo em chamadas para a API de análise da Microsoft Store antes que ele expire.After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store analytics API before the token expires. Depois que o token expirar, será possível gerar um novo.After the token expires, you can generate a new token.
  3. Chame a API de análise da Microsoft Store.Call the Microsoft Store analytics API.

Etapa 1: Concluir os pré-requisitos para usar a API de análise da Microsoft StoreStep 1: Complete prerequisites for using the Microsoft Store analytics API

Antes de começar a escrever o código para chamar a API de análise da Microsoft Store, certifique-se de que você concluiu os pré-requisitos a seguir.Before you start writing code to call the Microsoft Store analytics API, make sure that you have completed the following prerequisites.

  • Você (ou sua organização) deve ter um diretório do Azure AD, e você deve ter permissão de Administrador global para o diretório.You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. Se você já usa o Office 365 ou outros serviços comerciais da Microsoft, você já tem o diretório Azure AD.If you already use Office 365 or other business services from Microsoft, you already have Azure AD directory. Caso contrário, você pode criar um novo Azure AD no Partner Center sem custo adicional.Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • Você deve associar um aplicativo do Azure AD à sua conta do Partner Center, recuperar a ID do locatário e a ID do cliente para o aplicativo e gerar uma chave.You must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. O aplicativo do Azure AD representa o aplicativo ou serviço do qual você quer chamar a API de análise da Microsoft Store.The Azure AD application represents the app or service from which you want to call the Microsoft Store analytics API. Você precisa da ID do locatário, ID do cliente e da chave para obter um token de acesso do Azure AD que você passa para a API.You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    Observação

    Você só precisa executar essa tarefa uma vez.You only need to perform this task one time. Depois que você tiver a ID do locatário, a ID do cliente e a chave, poderá reutilizá-las sempre que precisa criar um novo token de acesso do Azure AD.After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

Para associar um aplicativo do Azure AD à sua conta do Partner Center e recuperar os valores necessários:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. No Partner Center, associe a conta do Partner Center da sua organização ao diretório do Azure ad da sua organização.In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. Em seguida, na página usuários na seção configurações de conta do Partner Center, adicione o aplicativo do Azure ad que representa o aplicativo ou serviço que você usará para acessar dados de análise para sua conta do Partner Center.Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to access analytics data for your Partner Center account. Certifique-se de atribuir esse aplicativo à Manager.Make sure you assign this application the Manager role. Se o aplicativo ainda não existir no diretório do Azure AD, você poderá criar um novo aplicativo do Azure AD no Partner Center.If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. Volte para a página Usuários, clique no nome do seu aplicativo Azure AD para ir para as configurações do aplicativo e copie os valores da ID do locatário e da ID do cliente.Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. Clique em Adicionar nova chave.Click Add new key. Na tela seguinte, copie o valor da Chave.On the following screen, copy down the Key value. Você não poderá acessar essas informações novamente depois que você sair desta página.You won't be able to access this info again after you leave this page. Para obter mais informações, consulte Gerenciar chaves para um aplicativo do Azure AD.For more information, see Manage keys for an Azure AD application.

Etapa 2: Obter um token de acesso do Azure ADStep 2: Obtain an Azure AD access token

Antes de chamar qualquer um dos métodos na API de análise da Microsoft Store, primeiro você deve obter um token de acesso do Azure AD que você passa para o cabeçalho Autorização de cada método na API.Before you call any of the methods in the Microsoft Store analytics API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. Depois de obter um token de acesso, você terá 60 minutos para usá-lo antes que ele expire.After you obtain an access token, you have 60 minutes to use it before it expires. Depois que o token expirar, você poderá atualizar o token para que você possa continuar a usá-lo em outras chamadas à API.After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

Para obter o token de acesso, siga as instruções em Chamadas de serviço a serviço usando credenciais do cliente para enviar um HTTP POST para o ponto de extremidade https://login.microsoftonline.com/<tenant_id>/oauth2/token.To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Aqui está um exemplo de solicitação.Here is a sample request.

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

Para o valor da ID de_do locatário no URI de postagem e os parâmetros de id de _ do cliente e_de segredo do cliente , especifique a ID do locatário, a ID do cliente e a chave do aplicativo que você recuperou do Partner Center na seção anterior.For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. Para o parâmetro resource, especifique https://manage.devcenter.microsoft.com.For the resource parameter, you must specify https://manage.devcenter.microsoft.com.

Depois que seu token de acesso expirar, você poderá atualizá-lo seguindo as instruções descritas aqui.After your access token expires, you can refresh it by following the instructions here.

Etapa 3: Chamar a API de análise da Microsoft StoreStep 3: Call the Microsoft Store analytics API

Depois que tiver um token de acesso do Azure AD, você estará pronto para chamar a API de análise da Microsoft Store.After you have an Azure AD access token, you are ready to call the Microsoft Store analytics API. Você deve passar o token de acesso no cabeçalho Autorização de cada método.You must pass the access token to the Authorization header of each method.

Métodos para aplicativos UWP e jogosMethods for UWP apps and games

Os métodos a seguir estão disponíveis para aquisições de aplicativos e jogos e aquisições de complemento:The following methods are available for apps and games acquisitions and add-on acquisitions:

Métodos para aplicativos UWPMethods for UWP apps

Os seguintes métodos de análise estão disponíveis para aplicativos UWP no Partner Center.The following analytics methods are available for UWP apps in Partner Center.

CenárioScenario MétodosMethods
Aquisições, conversões, instalações e usoAcquisitions, conversions, installs, and usage
Erros de appApp errors
InsightsInsights
Classificações e opiniõesRatings and reviews
Anúncios no app e campanhas publicitáriasIn-app ads and ad campaigns

Métodos para aplicativos da área de trabalhoMethods for desktop applications

Os métodos de análise a seguir estão disponíveis para uso por contas de desenvolvedor que pertencem ao programa Aplicativo da Área de Trabalho do Windows.The following analytics methods are available for use by developer accounts that belong to the Windows Desktop Application program.

CenárioScenario MétodosMethods
InstalaçõesInstalls
BlocksBlocks
Erros de aplicativoApplication errors
InsightsInsights

Métodos para serviços Xbox LiveMethods for Xbox Live services

Os métodos adicionais a seguir estão disponíveis para uso por contas de desenvolvedor com jogos que usam os serviços Xbox Live.The following additional methods are available for use by developer accounts with games that use Xbox Live services.

CenárioScenario MétodosMethods
Análises geraisGeneral analytics
Análise de integridadeHealth analytics
Análise de comunidadeCommunity analytics

Métodos para hardware e driversMethods for hardware and drivers

As contas de desenvolvedor que pertencem ao programa do painel de hardware do Windows têm acesso a um conjunto adicional de métodos para recuperar dados de análise de hardware e drivers.Developer accounts that belong to the Windows hardware dashboard program have access to an additional set of methods for retrieving analytics data for hardware and drivers. Para obter mais informações, consulte API do painel de hardware.For more information, see Hardware dashboard API.

Exemplo de códigoCode example

O exemplo de código a seguir demonstra como obter um token de acesso do Azure AD e chamar a API de análise da Microsoft Store de um aplicativo de console C#.The following code example demonstrates how to obtain an Azure AD access token and call the Microsoft Store analytics API from a C# console app. Para usar este exemplo de código, atribua as variáveis tenantId, clientId, clientSecret e appID aos valores adequados ao seu cenário.To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. Este exemplo exige o pacote Json.NET da Newtonsoft para desserializar os dados JSON retornados pela API de análise da Microsoft Store.This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Microsoft Store analytics API.

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;
        }
    }
}

Respostas de erroError responses

A API de análise da Microsoft Store retorna respostas de erro em um objeto JSON que contém códigos de erro e mensagens.The Microsoft Store analytics API returns error responses in a JSON object that contains error codes and messages. O exemplo a seguir demonstra uma resposta de erro causada por um parâmetro inválido.The following example demonstrates an error response caused by an invalid parameter.

{
    "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"
}