Доступ к аналитическим данным с помощью служб Store

Используйте API аналитики Microsoft Store для программного получения данных аналитики для приложений, зарегистрированных в вашей учетной записи Центра партнеров Windows или вашей организации. Этот API позволяет получать данные для приобретения приложений и надстроек (также известных как приобретение в приложении или IAP), ошибок, оценок приложений и отзывов. Этот API использует Microsoft Entra для проверки подлинности вызовов из приложения или службы.

Следующие шаги описывают сквозной процесс.

1. Убедитесь, что вы выполнили все предварительные требования.
2. Перед вызовом метода в API аналитики Microsoft Store получите маркер доступа Microsoft Entra. После получения маркера у вас есть 60 минут для использования этого маркера в вызовах API аналитики Microsoft Store до истечения срока действия маркера. После истечения срока действия маркера можно создать новый маркер.
3. Вызовите API аналитики Microsoft Store.

Шаг 1. Выполнение предварительных требований для использования API аналитики Microsoft Store

Прежде чем приступить к написанию кода для вызова API аналитики Microsoft Store, убедитесь, что выполнены следующие предварительные требования.

• У вас (или вашей организации) должен быть каталог Microsoft Entra, и у вас должно быть разрешение глобального администратора для каталога. Если вы уже используете Microsoft 365 или другие бизнес-службы от Майкрософт, у вас уже есть каталог Microsoft Entra. В противном случае вы можете создать новую в Центре партнеров без дополнительной платы.

• Необходимо связать приложение Microsoft Entra с учетной записью Центра партнеров, получить идентификатор клиента и идентификатор клиента для приложения и создать ключ. Приложение Microsoft Entra представляет приложение или службу, из которой требуется вызвать API аналитики Microsoft Store. Вам потребуется идентификатор клиента, идентификатор клиента и ключ для получения маркера доступа Microsoft Entra, который передается в API.

  Примечание.

  Эту задачу нужно выполнить только один раз. После того как у вас есть идентификатор клиента, идентификатор клиента и ключ, вы можете повторно использовать их в любое время, чтобы создать новый маркер доступа Microsoft Entra.

Чтобы связать приложение Microsoft Entra с учетной записью Центра партнеров и получить необходимые значения:

1. В Центре партнеров свяжите учетную запись Центра партнеров вашей организации с каталогом Microsoft Entra вашей организации.
2. Затем на странице "Пользователи" в разделе параметров учетной записи Центра партнеров добавьте приложение Microsoft Entra, представляющее приложение или службу, которую вы будете использовать для доступа к данным аналитики для учетной записи Центра партнеров. Убедитесь, что этому приложению назначена роль Менеджер. Если приложение еще не существует в каталоге Microsoft Entra, вы можете создать новое приложение Microsoft Entra в Центре партнеров.
3. Вернитесь на страницу "Управление пользователями" и перейдите на вкладку приложений Microsoft Entra, щелкните имя приложения Microsoft Entra, чтобы перейти к параметрам приложения и скопировать значения идентификатора клиента и идентификатора клиента.
4. Щелкните Добавить новый ключ. На следующем экране скопируйте значение в поле Ключ. Покинув эту страницу, вы больше не сможете получить доступ к этим сведениям. Дополнительные сведения см. в разделе "Управление ключами" для приложения Microsoft Entra.

Шаг 2. Получение маркера доступа Microsoft Entra

Прежде чем вызывать любой из методов в API аналитики Microsoft Store, необходимо сначала получить маркер доступа Microsoft Entra, который передается в заголовок авторизации каждого метода в API. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера можно обновить маркер, чтобы продолжить использовать его в дальнейших вызовах API.

Чтобы получить маркер доступа, следуйте инструкциям в разделе "Вызовы службы для вызовов служб с использованием учетных данных клиента" для отправки HTTP POST в конечную точку https://login.microsoftonline.com/<tenant_id>/oauth2/token . Ниже приведен пример запроса.

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

Для значения tenant_id в URI POST и параметрах client_id и client_secret укажите идентификатор клиента, идентификатор клиента и ключ приложения, полученного из Центра партнеров в предыдущем разделе. Для параметра resource укажите значение https://manage.devcenter.microsoft.com.

После истечения срока действия маркера доступа его можно обновить, следуя инструкциям ниже.

Шаг 3. Вызов API аналитики Microsoft Store

Получив маркер доступа Microsoft Entra, вы можете вызвать API аналитики Microsoft Store. Необходимо передать маркер доступа в заголовок авторизации каждого метода.

Методы для приложений и игр UWP

Для приложений и игр и приобретений надстроек доступны следующие методы:

• Получение данных о приобретении игр и приложений
• Получение данных о приобретении надстроек для игр и приложений

Методы для приложений UWP

Следующие методы аналитики доступны для приложений UWP в Центре партнеров.

Методы для классических приложений

Следующие методы аналитики доступны для использования учетными записями разработчиков, принадлежащими программе классических приложений Windows.

Методы для служб Xbox Live

Следующие дополнительные методы доступны для использования учетными записями разработчиков с играми, используюющими службы Xbox Live. API Аналитики Microsoft Store для Xbox больше недоступен. gaming/xbox-live/get-started/join-dev-program/join-dev-program_nav

Методы для оборудования и драйверов

Учетные записи разработчиков, принадлежащие программе аппаратной панели мониторинга Windows, имеют доступ к дополнительному набору методов получения аналитических данных для оборудования и драйверов. Дополнительные сведения см. в разделе API аппаратной панели мониторинга.

Пример кода

В следующем примере кода показано, как получить маркер доступа Microsoft Entra и вызвать API аналитики Microsoft Store из консольного приложения C#. Чтобы использовать этот пример кода, назначьте идентификатор клиента, clientId, clientSecret и переменные appID соответствующим значениям для вашего сценария. В этом примере требуется пакет Json.NET из Newtonsoft для десериализации данных JSON, возвращаемых API аналитики 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;
        }
    }
}

Сообщения об ошибках

API аналитики Microsoft Store возвращает ответы об ошибках в объекте JSON, который содержит коды ошибок и сообщения. В следующем примере показан ответ на ошибку, вызванный недопустимым параметром.

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