Store 서비스를 사용하여 분석 데이터에 액세스

아티클
06/14/2024

Microsoft Store 분석 API를 사용하여 사용자 또는 조직의 Windows 파트너 센터 계정에 등록된 앱에 대한 분석 데이터를 프로그래밍 방식으로 검색합니다. 이 API를 사용하면 앱 및 추가 기능(앱 내 제품[IAP]이라고도 함) 구입, 오류, 앱 평점 및 리뷰에 대한 데이터를 검색할 수 있습니다. 이 API는 Microsoft Entra를 사용하여 앱 또는 서비스의 호출을 인증합니다.

다음 단계에서는 엔드투엔드 프로세스를 설명합니다.

모든 필수 조건을 충족하였는지 확인합니다.
Microsoft Store 분석 API 에서 메서드를 호출하기 전에 Microsoft Entra 액세스 토큰을 가져옵니다. 토큰을 가져온 후 만료되기 전에 이 토큰을 Microsoft Store 분석 API에 대한 호출에 사용할 수 있는 시간은 60분입니다. 토큰이 만료되고 나면 새 토큰을 생성할 수 있습니다.
Microsoft Store 분석 API를 호출합니다.

단계 1: Microsoft Store 분석 API를 사용하기 위한 필수 조건 완료

Microsoft Store 분석 API를 호출하는 코드를 작성하기 전에 다음과 같은 필수 조건을 완료했는지 확인합니다.

사용자(또는 조직)에게는 Microsoft Entra 디렉터리가 있어야 하며 디렉터리에 대한 전역 관리자 권한이 있어야 합니다. 이미 Microsoft 365 또는 Microsoft의 다른 비즈니스 서비스를 사용하는 경우 이미 Microsoft Entra 디렉터리가 있습니다. 그렇지 않으면 추가 비용 없이 파트너 센터에서 새 항목을 만들 수 있습니다.
Microsoft Entra 애플리케이션을 파트너 센터 계정과 연결하고, 애플리케이션의 테넌트 ID 및 클라이언트 ID를 검색하고, 키를 생성해야 합니다. Microsoft Entra 애플리케이션은 Microsoft Store 분석 API를 호출하려는 앱 또는 서비스를 나타냅니다. API에 전달하는 Microsoft Entra 액세스 토큰을 가져오려면 테넌트 ID, 클라이언트 ID 및 키가 필요합니다.

참고 항목

이 작업은 한 번만 수행하면 됩니다. 테넌트 ID, 클라이언트 ID 및 키가 있으면 새 Microsoft Entra 액세스 토큰을 만들어야 할 때마다 다시 사용할 수 있습니다.

Microsoft Entra 애플리케이션을 파트너 센터 계정과 연결하고 필요한 값을 검색하려면 다음을 수행합니다.

파트너 센터에서 조직의 파트너 센터 계정을 조직의 Microsoft Entra 디렉터리에 연결합니다.
다음으로 파트너 센터의 계정 설정 섹션에 있는 사용자 페이지에서 파트너 센터 계정의 분석 데이터에 액세스하는 데 사용할 앱 또는 서비스를 나타내는 Microsoft Entra 애플리케이션을 추가합니다. 이 응용 프로그램에 관리자 역할을 할당해야 합니다. 애플리케이션이 Microsoft Entra 디렉터리에 아직 없는 경우 파트너 센터에서 새 Microsoft Entra 애플리케이션을 만들 수 있습니다.
사용자 관리 페이지로 돌아가서 Microsoft Entra 애플리케이션 탭으로 이동하고, Microsoft Entra 애플리케이션의 이름을 클릭하여 애플리케이션 설정으로 이동하고, 테넌트 ID 및 클라이언트 ID 값을 복사합니다.
새 키 추가를 클릭합니다. 다음 화면에서 키 값을 복사합니다. 이 페이지를 나간 후에는 이 정보에 다시 액세스할 수 없습니다. 자세한 내용은 Microsoft Entra 애플리케이션에 대한 키 관리를 참조하세요.

2단계: Microsoft Entra 액세스 토큰 가져오기

Microsoft Store 분석 API에서 메서드를 호출하기 전에 먼저 API에서 각 메서드의 권한 부여 헤더에 전달하는 Microsoft Entra 액세스 토큰을 가져와야 합니다. 액세스 토큰을 가져온 후 만료되기까지 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

POST URI의 tenant_id 값, client_id 및 client_secret 매개 변수에는 이전 섹션의 파트너 센터에서 검색한 애플리케이션의 테넌트 ID, 클라이언트 ID 및 키를 지정합니다. 리소스 매개 변수의 경우에는 https://manage.devcenter.microsoft.com을 지정해야 합니다.

액세스 토큰이 만료되면 여기에 있는 지침에 따라 새로 고칠 수 있습니다.

참고 항목

ResourceType=Graph.windows.net 은 2023년 9월에 더 이상 사용되지 않습니다. ResourceType =Graph.microsoft.com으로 마이그레이션하세요.

3단계: Microsoft Store 분석 API 호출

Microsoft Entra 액세스 토큰이 있으면 Microsoft Store 분석 API를 호출할 준비가 된 것입니다. 액세스 토큰은 각 메서드의 인증 헤더에 전달해야 합니다.

UWP 앱 및 게임에 대한 메서드

앱/게임 취득 및 추가 기능 취득에 사용할 수 있는 메서드는 다음과 같습니다.

UWP 앱에 대한 메서드

파트너 센터의 UWP 앱에 사용할 수 있는 분석 메서드는 다음과 같습니다.

시나리오	메서드
취득, 변환, 설치 및 사용	앱 취득 가져오기(레거시) 앱 취득 깔때기 데이터 가져오기(레거시) 채널별 앱 변환 가져오기 추가 기능 취득 가져오기 구독 추가 기능 취득 가져오기 채널별 추가 기능 변환 가져오기 앱 설치 가져오기 일일 앱 사용 현황 가져오기 월별 앱 사용 현황 가져오기
앱 오류	오류 보고 데이터 가져오기 앱에서 오류에 대한 세부 정보 가져오기 앱 내 오류에 대한 스택 추적 가져오기 앱의 오류에 대한 CAB 파일 다운로드
Insights	앱에 대한 인사이트 데이터 가져오기
등급 및 리뷰	앱 등급 가져오기 앱 리뷰 가져오기
인앱 광고 및 광고 캠페인	광고 성과 데이터 가져오기 광고 캠페인 성과 데이터 가져오기

데스크톱 애플리케이션에 대한 메서드

Windows 데스크톱 애플리케이션 프로그램에 속하는 개발자 계정에서 사용할 수 있는 분석 메서드는 다음과 같습니다.

시나리오	메서드
설치	데스크톱 애플리케이션 설치 가져오기
블록	데스크톱 애플리케이션에 대한 업그레이드 차단 가져오기 데스크톱 애플리케이션에 대한 업그레이드 차단 세부 정보 가져오기
애플리케이션 오류	데스크톱 애플리케이션에 대한 오류 보고 데이터 가져오기 데스크톱 애플리케이션에서 오류 세부 정보 가져오기 데스크톱 애플리케이션에서 오류에 대한 스택 추적 가져오기 데스크톱 애플리케이션의 오류에 대한 CAB 파일 다운로드
Insights	데스크톱 애플리케이션에 대한 인사이트 데이터 가져오기

Xbox Live 서비스에 대한 메서드

Xbox Live 서비스를 사용하는 게임의 개발자 계정에서 사용할 수 있는 추가 메서드는 다음과 같습니다. Xbox용 Microsoft Store Analytics API는 더 이상 사용할 수 없습니다. gaming/xbox-live/get-started/join-dev-program/join-dev-program_nav

시나리오	메서드
일반 분석	Xbox Live 분석 데이터 가져오기

하드웨어 및 드라이버에 대한 메서드

Windows 하드웨어 대시보드 프로그램에 속하는 개발자 계정은 하드웨어 및 드라이버에 대한 분석 데이터를 검색하기 위한 추가 메서드 세트에 액세스할 수 있습니다. 자세한 내용은 하드웨어 대시보드 API를 참조하세요.

코드 예

다음 코드 예제에서는 Microsoft Entra 액세스 토큰을 가져오고 C# 콘솔 앱에서 Microsoft Store 분석 API를 호출하는 방법을 보여 줍니다. 이 코드 예제를 사용하려면 tenantId 변수, clientId 변수, clientSecret 변수 및 appID 변수를 시나리오에 적합한 값에 할당하세요. 이 예제에는 Microsoft Store 분석 API에서 반환하는 JSON 데이터를 역직렬화하기 위해 Newtonsoft의 Json.NET 패키지가 필요합니다.

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

오류 응답

Microsoft Store 분석 API는 오류 코드와 메시지를 포함한 오류 응답을 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"
}

다음을 통해 공유