Acessar dados analíticos usando os serviços da Loja

Utilize a API de análise da Microsoft Store para recuperar programaticamente dados de análise de aplicações que estão registadas na sua conta do Windows Partner Center ou na conta da sua organização. Essa API permite que você recupere dados para aquisições, erros, classificações e avaliações de aplicativos e complementos (também conhecidos como produtos no aplicativo ou IAP). Essa API usa o Microsoft Entra para autenticar as chamadas do seu aplicativo ou serviço.

As etapas a seguir descrevem o processo de ponta a ponta:

1. Certifique-se de ter cumprido todos os pré-requisitos.
2. Antes de chamar um método na API de análise da Microsoft Store, obter um token de acesso do Microsoft Entra. 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 o token expire. Depois que o token expirar, você poderá gerar um novo token.
3. 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 código para chamar a API de análise da Microsoft Store, certifique-se de ter concluído os seguintes pré-requisitos.

• Você (ou sua organização) deve ter um diretório do Microsoft Entra e deve ter permissão de de administrador global para o diretório. Se você já usa o Microsoft 365 ou outros serviços empresariais da Microsoft, já tem um diretório do Microsoft Entra. Caso contrário, você pode criar um novo no Partner Center sem custo adicional.

• Você deve associar um aplicativo Microsoft Entra à 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 Microsoft Entra representa o aplicativo ou serviço do qual você deseja 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 Microsoft Entra que você passa para a API.

  Observação

  Você só precisa executar essa tarefa uma vez. Depois de ter o ID do locatário, o ID do cliente e a chave, você pode reutilizá-los sempre que precisar criar um novo token de acesso do Microsoft Entra.

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

1. No Partner Center, associar a conta do Partner Center da sua organização ao diretório Microsoft Entra da sua organização.
2. Em seguida, na página Usuários na seção Configurações da Conta do Partner Center, adicione o aplicativo Microsoft Entra que representa o aplicativo ou serviço que usará para acessar dados analíticos da sua conta do Partner Center. Certifique-se de atribuir a função Manager a esta aplicação. Se o aplicativo ainda não existir no diretório do Microsoft Entra, você poderá criar um novo aplicativo Microsoft Entra no Partner Center.
3. Retorne à página Gerenciamento de Usuários e navegue até guia aplicativos Microsoft Entra, clique no nome do seu aplicativo Microsoft Entra para ir para as configurações do aplicativo e copie para baixo o de ID do Locatário e os valores ID do Cliente.
4. Clique Adicionar nova chave. No ecrã seguinte, copie o valor da chave . Você não poderá acessar essas informações novamente depois de sair desta página. Para obter mais informações, consulte Gerenciar chaves para um aplicativo Microsoft Entra.

Etapa 2: Obter um token de acesso do Microsoft Entra

Antes de chamar qualquer um dos métodos na API de análise da Microsoft Store, deve primeiro obter um token de acesso do Microsoft Entra que passa para o cabeçalho de Autorização de cada método na API. Depois de obter um token de acesso, você tem 60 minutos para usá-lo antes que ele expire. Depois que o token expirar, você poderá atualizá-lo para continuar a usá-lo em outras chamadas para a API.

Para obter o token de acesso, siga as instruções na seção Service to Service Calls Using Client Credentials para enviar um HTTP POST para o endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está um pedido de amostra.

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 tenant_id no URI POST e os parâmetros client_id e client_secret, especifique o ID do locatário, o ID do cliente e a chave do aplicativo que você recuperou do Partner Center na seção anterior. Você deve especificar o parâmetro do recurso ao definir https://manage.devcenter.microsoft.com.

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

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

Depois de ter um token de acesso do Microsoft Entra, você estará pronto para chamar a API de análise da Microsoft Store. Você deve passar o token de acesso no cabeçalho Authorization de cada método.

Métodos para aplicativos e jogos UWP

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

• Obter dados de aquisições para os seus jogos e aplicações
• Obter dados de aquisições adicionais para os seus jogos e aplicações

Métodos para aplicativos UWP

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

Métodos para aplicações de ambiente de trabalho

Os seguintes métodos de análise estão disponíveis para uso por contas de desenvolvedor que pertencem ao programa Windows Desktop Application.

Métodos para serviços do Xbox Live

Os seguintes métodos adicionais estão disponíveis para utilização por contas de desenvolvedor com jogos que utilizam serviços Xbox Live. A API do Microsoft Store Analytics para Xbox não está mais disponível. jogos/xbox-live/começar/aderir-programa-desenvolvedor/aderir-programa-desenvolvedor_nav

Métodos para hardware e drivers

As contas de desenvolvedor que pertencem ao programa do painel de controlo de hardware do Windows têm acesso a um conjunto adicional de métodos para obter dados analíticos de hardware e controladores. Para obter mais informações, consulte API do painel de hardware.

Exemplo de código

O exemplo de código a seguir demonstra como obter um token de acesso do Microsoft Entra 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, clientSecrete appID aos valores apropriados para o seu cenário. Este exemplo requer 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"
}