Acessar dados analíticos usando serviços da Store

Artigo
03/18/2023

Use a API de análise da Microsoft Store para recuperar programaticamente dados de análise para aplicativos registrados na conta do Windows Partner Center da sua organização. 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. Essa API usa o Active Directory do Azure (Azure AD) para autenticar as chamadas do seu aplicativo ou serviço.

As etapas a seguir descrevem o processo completo:

Certifique-se de que você tenha concluído todos os pré-requisitos.
Antes de chamar um método na API de análise da Microsoft Store obtenha um token de acesso do Azure AD. 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. Depois que o token expirar, será possível gerar um novo.
Chame a API de análise da Microsoft Store.

Etapa 1: Concluir os pré-requisitos para usar a API de análise da Microsoft Store

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.

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. Se já usa o Microsoft 365 ou outros serviços comerciais da Microsoft, você já tem o diretório do Azure AD. Caso contrário, você poderá criar uma nova Azure AD no Partner Center sem custo adicional.
Você deve associar um aplicativo 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. O aplicativo do Azure AD representa o aplicativo ou serviço do qual você quer chamar a API de análise da Microsoft Store. Você precisa da ID do locatário, da ID do cliente e da chave para obter um token de acesso do Azure AD que é passado para a API.

Observação

Você só precisa executar essa tarefa uma vez. Depois de obter a ID do locatário, a ID do cliente e a chave, você poderá reutilizá-las sempre que precisar criar um novo token de acesso do Azure AD.

Para associar um aplicativo Azure AD à sua conta do Partner Center e recuperar os valores necessários:

No Partner Center, associe a conta do Partner Center da sua organização ao diretório do Azure AD da sua organização.
Em seguida, na página Usuários na seção Configurações da conta do Partner Center, adicione o aplicativo Azure AD que representa o aplicativo ou serviço que você usará para acessar dados de análise para sua conta do Partner Center. Lembre-se de atribuir esse aplicativo à função de Gerenciador. Se o aplicativo ainda não existir no diretório do Azure AD, crie um novo aplicativo do Azure AD no Partner Center.
Retorne à página Usuários, clique no nome do seu aplicativo do Azure AD para acessar as configurações do aplicativo e copie os valores de ID do Locatário e ID do Cliente.
Clique em Adicionar nova chave. Na tela a seguir, copie o valor da Chave. Você não poderá acessar essas informações novamente depois de sair da página. Para saber mais, veja Gerenciar chaves de um aplicativo do Azure AD.

Etapa 2: Obtenção de um token de acesso do Azure AD

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. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá atualizar o token para que você possa continuar a usá-lo em outras chamadas à 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. Aqui está um exemplo de solicitação.

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 de tenant_id no URI POST e os parâmetros client_id e client_secret , 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. Para o parâmetro resource, especifique https://manage.devcenter.microsoft.com.

Depois que seu token de acesso expirar, você poderá atualizá-lo seguindo as instruções descritas aqui.

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

Etapa 3: Chamar a API de análise da Microsoft Store

Depois que tiver um token de acesso do Azure AD, você estará pronto para chamar a API de análise da Microsoft Store. Você deve passar o token de acesso no cabeçalho Autorização de cada método.

Métodos para jogos e aplicativos UWP

Os seguintes métodos estão disponíveis para aquisições de aplicativos e jogos e aquisições de complementos:

Métodos para aplicativos UWP

Os métodos de análise a seguir estão disponíveis para aplicativos UWP no Partner Center.

Cenário	Métodos
Aquisições, conversões, instalações e uso	Obter aquisições de aplicativos (herdadas) Obter dados de funil de aquisição de aplicativo (herdado ) Obter conversões de aplicativo por canal Obter aquisições de complemento Obter aquisições de complemento de assinatura Obter conversões de complemento por canal Obter instalações do aplicativo Obter uso diário do aplicativo Obter uso mensal do aplicativo
Erros de app	Obter dados de relatório de erros Obter detalhes de um erro em seu aplicativo Obter o rastreamento de pilha de um erro em seu app Baixar o arquivo CAB de um erro em seu aplicativo
Insights	Obter dados de insights do seu aplicativo
Classificações e opiniões	Obter classificações de aplicativo Obter avaliações de aplicativo
Anúncios no app e campanhas publicitárias	Obter dados de desempenho de anúncios Obter dados de desempenho da campanha publicitária

Métodos para aplicativos da área de trabalho

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.

Cenário	Métodos
Instalações	Obter instalações de aplicativo da área de trabalho
Blocos	Obter bloqueios de atualização para seu aplicativo da área de trabalho Obter detalhes do bloqueio de atualização para seu aplicativo da área de trabalho
Erros de aplicativos	Obter dados de relatório de erros do seu aplicativo da área de trabalho Obter detalhes de um erro em seu aplicativo da área de trabalho Obter o rastreamento de pilha de um erro em seu aplicativo da área de trabalho Baixar o arquivo CAB de um erro em seu aplicativo da área de trabalho
Insights	Obter dados de insights do seu aplicativo da área de trabalho

Métodos para serviços Xbox Live

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. A API de Análise da Microsoft Store para Xbox não está mais disponível. gaming/xbox-live/get-started/join-dev-program/join-dev-program_nav

Cenário	Métodos
Análises gerais	Obter dados de análise do Xbox Live

Métodos para hardware e drivers

As contas de desenvolvedor que pertencem ao programa de dashboard de hardware do Windows têm acesso a um conjunto adicional de métodos para recuperar dados de análise para hardware e drivers. Para obter mais informações, consulte Hardware dashboard API.

Exemplo de código

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#. Para usar este exemplo de código, atribua as variáveis tenantId, clientId, clientSecret e appID aos valores adequados ao seu cenário. Este exemplo exige o pacote Json.NET da Newtonsoft para desserializar os dados JSON retornados pela API de análise da 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;
        }
    }
}

Respostas de erro

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. O exemplo a seguir demonstra uma resposta de erro causada por um parâmetro inválido.

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