使用 Store 服務存取分析資料

發行項
06/14/2024

使用 Microsoft Store 分析 API，以程式設計方式擷取已註冊至您的或貴組織的 Windows 合作夥伴中心帳戶之應用程式的分析資料。此 API 可讓您擷取應用程式與附加元件 (也稱為應用程式內產品或 IAP) 下載數、錯誤、應用程式評分和評論的資料。此 API 會使用 Microsoft Entra 來驗證來自您的應用程式或服務的呼叫。

下列步驟描述端到端的處理流程：

請確定您已完成所有必要條件。
在Microsoft市集分析 API 中呼叫方法之前，請先取得Microsoft Entra 存取令牌。取得權杖之後，您有 60 分鐘的時間使用此權杖來呼叫 Microsoft Store 分析 API，之後權杖才會到期。權杖過期後，您可以生成新的權杖。
呼叫 Microsoft Store 分析 API。

步驟 1：完成使用 Microsoft Store 分析 API 的必要條件

開始撰寫程式碼以呼叫 Microsoft Store 分析 API 之前，請確定您已完成下列必要條件。

您（或貴組織）必須具有 Microsoft Entra 目錄，而且您必須具有目錄的全域管理員許可權。如果您已經從 Microsoft 使用 Microsoft 365 或其他商務服務，則已經有 Microsoft Entra 目錄。否則，您可以在合作夥伴中心建立新的帳戶，不需額外費用。
您必須將Microsoft Entra 應用程式與您的合作夥伴中心帳戶產生關聯、擷取應用程式的租用戶標識碼和用戶端標識符，併產生密鑰。 Microsoft Entra 應用程式代表您想要從中呼叫 Microsoft Store 分析 API 的應用程式或服務。您需要租使用者標識碼、用戶端標識碼和密鑰，才能取得您傳遞至 API 的 Microsoft Entra 存取令牌。

注意

您只需要執行此工作一次。擁有租使用者標識碼、用戶端標識碼和密鑰之後，您隨時都可以重複使用它們，以建立新的Microsoft Entra 存取令牌。

若要將Microsoft Entra 應用程式與您的合作夥伴中心帳戶產生關聯，並擷取所需的值：

在合作夥伴中心中，將組織的合作夥伴中心帳戶與組織的 Microsoft Entra 目錄建立關聯。
接下來，從合作夥伴中心的 [帳戶設定] 區段中的 [使用者] 頁面，新增Microsoft Entra 應用程式，代表您將用來存取合作夥伴中心帳戶分析數據的應用程式或服務。請確定為此應用程式指派管理員角色。如果您的 Microsoft Entra 目錄中還沒有任何應用程式存在，您可以在合作夥伴中心建立新的Microsoft Entra 應用程式。
返回 [ 使用者管理 ] 頁面並流覽至 [Microsoft Entra 應用程式] 索引標籤，按兩下Microsoft Entra 應用程式 的名稱以移至應用程式設定，然後複製 [租使用者識別符 ] 和 [用戶端識別符 ] 值。
按一下 [新增金鑰]。在後續的畫面上，複製 [金鑰] 值。離開此頁面之後，您將無法再次存取此資訊。如需詳細資訊，請參閱管理Microsoft Entra 應用程式的密鑰。

步驟 2：取得Microsoft Entra 存取令牌

在呼叫 Microsoft Store 分析 API 中的任何方法之前，您必須先取得傳遞至 API 中每個方法的 Authorization 標頭的 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 參數，請在上一節中指定您從合作夥伴中心擷取的應用程式租用戶識別碼、用戶端識別碼和金鑰。針對 resource 參數，您必須指定 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 檔案
深入解析	取得應用程式的深入解析資料
評分並評論	取得應用程式評分取得應用程式評論
應用程式內廣告和廣告行銷活動	取得廣告績效資料取得廣告活動績效資料

傳統型應用程式的方法

下列分析方法可供屬於 Windows 傳統型應用程式計畫的開發人員帳戶使用。

案例	方法
安裝	取得傳統型應用程式安裝
區塊	取得傳統型應用程式的升級區塊取得傳統型應用程式的升級區塊詳細資料
應用程式錯誤	取得傳統型應用程式的錯誤報告資料取得傳統型應用程式中錯誤的詳細資料取得傳統型應用程式中錯誤的堆疊追蹤下載傳統型應用程式中錯誤的 CAB 檔案
深入解析	取得傳統型應用程式的深入解析資料

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 變數至適用您案例的適當值。此範例需要 Newtonsoft 的 Json.NET 套件，才能對 Microsoft Store 分析 API 所傳回的 JSON 資料還原序列化。

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

共用方式為