使用 Microsoft Store 服務存取分析資料

使用 Microsoft Store 分析 API ,以程式設計方式抓取向您或您組織的 Windows 合作夥伴中心帳戶註冊之應用程式的分析資料。 這個 API 可讓您擷取應用程式和附加元件 (也稱為應用程式內產品或 IAP) 下載數、錯誤、應用程式評分與評論的資料。 這個 API 使用 Azure Active Directory (Azure AD) 來驗證您 App 或服務的呼叫。

下列步驟說明端對端的程序:

  1. 請確定您已經完成所有先決條件
  2. 在呼叫 Microsoft Store 分析 API 中的方法之前,請先取得 Azure AD 存取權杖。 取得權杖之後,在權杖到期之前,您有 60 分鐘的時間可以使用這個權杖呼叫 Microsoft Store 分析 API。 權杖到期之後,您可以產生新的權杖。
  3. 呼叫 Microsoft Store 分析 API

步驟 1:完成使用 Microsoft Store 分析 API 的先決條件

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

  • 您 (或您的組織) 必須具有 Azure AD 目錄,且您必須具備該目錄的全域管理員 (部分機器翻譯) 權限。 如果您已經使用 Microsoft 365 或 Microsoft 的其他商務服務,則您已經有 Azure AD 目錄。 否則,您可以 在合作夥伴中心中建立新的 Azure AD ,而不需要額外收費。

  • 您必須將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯、取出應用程式的租使用者識別碼和用戶端識別碼,並產生金鑰。 Azure AD 應用程式代表您要呼叫 Microsoft Store 分析 API 的應用程式或服務。 您需要租用戶識別碼、用戶端識別碼及金鑰,以取得您會傳遞給 API 的 Azure AD 存取權杖。

    注意

    您只需要執行此工作一次。 在您取得租用戶識別碼、用戶端識別碼及金鑰之後,您便可以在未來需要建立新的 Azure AD 存取權杖時重複加以使用。

若要將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯,並取出所需的值:

  1. 在合作夥伴中心中,將您組織的合作夥伴中心帳戶與您組織的 Azure AD 目錄建立關聯 (部分機器翻譯)。

  2. 接下來,在合作夥伴中心的 [帳戶設定] 區段中的 [使用者] 頁面上,新增代表您將用來存取合作夥伴中心帳戶分析資料之應用程式或服務的 Azure AD 應用程式。 確定您將此應用程式指派為 [管理員] 角色。 如果該應用程式尚未存在於您的 Azure AD 目錄,您可以在合作夥伴中心中建立新的 Azure AD 應用程式 (部分機器翻譯)。

  3. 返回 [使用者] 頁面,按一下您 Azure AD 應用程式的名稱以移至應用程式設定,然後複製 [租用戶識別碼] 和 [用戶端識別碼] 值。

  4. 按一下 [新增金鑰]。 在後續畫面上,複製 [金鑰] 值。 在您離開此頁面之後,便無法再次存取此資訊。 如需詳細資訊,請參閱管理 Azure AD 應用程式的金鑰 (部分機器翻譯)。

步驟 2:取得 Azure AD 存取權杖

在 Microsoft Store 分析 API 中呼叫任何方法之前,您必須先取得傳遞至 API 中每個方法的 Authorization 標頭的 Azure AD 存取權杖。 在您取得存取權杖之後,您有 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 中的 租使用者 _ 識別碼 值,以及 客戶 _ 端識別碼 和用戶端 _ 密碼 參數,指定您的應用程式的租使用者識別碼、用戶端識別碼和金鑰,並從上一節的合作夥伴中心中取出。 針對 resource 參數,您必須指定 https://manage.devcenter.microsoft.com

存取權杖到期之後,您可以按照這裡的指示,重新整理權杖。

步驟 3:呼叫 Microsoft Store 分析 API

有了 Azure AD 存取權杖之後,就可以呼叫 Microsoft Store 分析 API。 您必須將存取權杖傳送給每個方法的 Authorization 標頭。

UWP 應用程式和遊戲的方法

下列方法適用于應用程式和遊戲的取得和附加元件的收購:

適用於 UWP app 的方法

下列分析方法適用于合作夥伴中心中的 UWP 應用程式。

案例 方法
收購、轉換、安裝和使用方式
App 錯誤
深入解析
評分與評論
應用程式內廣告與廣告行銷活動

傳統型應用程式的方法

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

案例 方法
安裝數
區塊
應用程式錯誤
深入解析

適用於 Xbox Live 服務的方法

下列其他方法可供使用 Xbox Live 服務的遊戲開發人員帳戶使用。

案例 方法
一般分析
健康情況分析
社群分析

硬體與驅動程式的方法

屬於Windows 硬體儀表板程式的開發人員帳戶,可以存取一組額外的方法來取得硬體和驅動程式的分析資料。 如需詳細資訊,請參閱 硬體儀表板 API

程式碼範例

下列程式碼範例示範如何取得 Azure AD 存取權杖,並從 C# 主控台應用程式呼叫 Microsoft Store 分析 API。 若要使用此程式碼範例,請針對您的案例將 tenantIdclientIdclientSecretappID 變數指定為適當的值。 此範例需要 Newtonsoft 的 Json.NET package,以還原序列化 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&quot;:&quot;AnalyticsAPI"
    },
    "message":"The calling client sent a bad request to the service.",
    "source&quot;:&quot;AnalyticsAPI"
}