使用 Microsoft Store 服務存取分析資料Access analytics data using Store services

使用 Microsoft Store 分析 API ,以程式設計方式抓取向您或您組織的 Windows 合作夥伴中心帳戶註冊之應用程式的分析資料。Use the Microsoft Store analytics API to programmatically retrieve analytics data for apps that are registered to your or your organization's Windows Partner Center account. 這個 API 可讓您擷取應用程式和附加元件 (也稱為應用程式內產品或 IAP) 下載數、錯誤、應用程式評分與評論的資料。This API enables you to retrieve data for app and add-on (also known as in-app product or IAP) acquisitions, errors, app ratings and reviews. 這個 API 使用 Azure Active Directory (Azure AD) 來驗證您 App 或服務的呼叫。This API uses Azure Active Directory (Azure AD) to authenticate the calls from your app or service.

下列步驟說明端對端的程序:The following steps describe the end-to-end process:

  1. 請確定您已經完成所有先決條件Make sure that you have completed all the prerequisites.
  2. 在呼叫 Microsoft Store 分析 API 中的方法之前,請先取得 Azure AD 存取權杖Before you call a method in the Microsoft Store analytics API, obtain an Azure AD access token. 取得權杖之後,在權杖到期之前,您有 60 分鐘的時間可以使用這個權杖呼叫 Microsoft Store 分析 API。After you obtain a token, you have 60 minutes to use this token in calls to the Microsoft Store analytics API before the token expires. 權杖到期之後,您可以產生新的權杖。After the token expires, you can generate a new token.
  3. 呼叫 Microsoft Store 分析 APICall the Microsoft Store analytics API.

步驟 1:完成使用 Microsoft Store 分析 API 的先決條件Step 1: Complete prerequisites for using the Microsoft Store analytics API

開始撰寫程式碼以呼叫 Microsoft Store 分析 API 之前,請先確定您已完成下列先決條件。Before you start writing code to call the Microsoft Store analytics API, make sure that you have completed the following prerequisites.

  • 您 (或您的組織) 必須具有 Azure AD 目錄,且您必須具備該目錄的全域管理員 (部分機器翻譯) 權限。You (or your organization) must have an Azure AD directory and you must have Global administrator permission for the directory. 如果您已經使用 Microsoft 365 或 Microsoft 的其他商務服務,則您已經有 Azure AD 目錄。If you already use Microsoft 365 or other business services from Microsoft, you already have Azure AD directory. 否則,您可以 在合作夥伴中心中建立新的 Azure AD ,而不需要額外收費。Otherwise, you can create a new Azure AD in Partner Center for no additional charge.

  • 您必須將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯、取出應用程式的租使用者識別碼和用戶端識別碼,並產生金鑰。You must associate an Azure AD application with your Partner Center account, retrieve the tenant ID and client ID for the application and generate a key. Azure AD 應用程式代表您要呼叫 Microsoft Store 分析 API 的應用程式或服務。The Azure AD application represents the app or service from which you want to call the Microsoft Store analytics API. 您需要租用戶識別碼、用戶端識別碼及金鑰,以取得您會傳遞給 API 的 Azure AD 存取權杖。You need the tenant ID, client ID and key to obtain an Azure AD access token that you pass to the API.

    注意

    您只需要執行此工作一次。You only need to perform this task one time. 在您取得租用戶識別碼、用戶端識別碼及金鑰之後,您便可以在未來需要建立新的 Azure AD 存取權杖時重複加以使用。After you have the tenant ID, client ID and key, you can reuse them any time you need to create a new Azure AD access token.

若要將 Azure AD 應用程式與您的合作夥伴中心帳戶建立關聯,並取出所需的值:To associate an Azure AD application with your Partner Center account and retrieve the required values:

  1. 在合作夥伴中心中,將您組織的合作夥伴中心帳戶與您組織的 Azure AD 目錄建立關聯 (部分機器翻譯)。In Partner Center, associate your organization's Partner Center account with your organization's Azure AD directory.

  2. 接下來,在合作夥伴中心的 [帳戶設定] 區段中的 [使用者] 頁面上,新增代表您將用來存取合作夥伴中心帳戶分析資料之應用程式或服務的Azure AD 應用程式Next, from the Users page in the Account settings section of Partner Center, add the Azure AD application that represents the app or service that you will use to access analytics data for your Partner Center account. 確定您將此應用程式指派為 [管理員] 角色。Make sure you assign this application the Manager role. 如果該應用程式尚未存在於您的 Azure AD 目錄,您可以在合作夥伴中心中建立新的 Azure AD 應用程式 (部分機器翻譯)。If the application doesn't exist yet in your Azure AD directory, you can create a new Azure AD application in Partner Center.

  3. 返回 [使用者] 頁面,按一下您 Azure AD 應用程式的名稱以移至應用程式設定,然後複製 [租用戶識別碼] 和 [用戶端識別碼] 值。Return to the Users page, click the name of your Azure AD application to go to the application settings, and copy down the Tenant ID and Client ID values.

  4. 按一下 [新增金鑰]。Click Add new key. 在後續畫面上,複製 [金鑰] 值。On the following screen, copy down the Key value. 在您離開此頁面之後,便無法再次存取此資訊。You won't be able to access this info again after you leave this page. 如需詳細資訊,請參閱管理 Azure AD 應用程式的金鑰 (部分機器翻譯)。For more information, see Manage keys for an Azure AD application.

步驟 2:取得 Azure AD 存取權杖Step 2: Obtain an Azure AD access token

在 Microsoft Store 分析 API 中呼叫任何方法之前,您必須先取得傳遞至 API 中每個方法的 Authorization 標頭的 Azure AD 存取權杖。Before you call any of the methods in the Microsoft Store analytics API, you must first obtain an Azure AD access token that you pass to the Authorization header of each method in the API. 在您取得存取權杖之後,您有 60 分鐘的使用時間,之後其便會到期。After you obtain an access token, you have 60 minutes to use it before it expires. 權杖到期之後,您可以重新整理權杖以便在後續呼叫 API 時繼續使用。After the token expires, you can refresh the token so you can continue to use it in further calls to the API.

若要取得存取權杖,請按照使用用戶端認證的服務對服務呼叫中的指示,將 HTTP POST 傳送至 https://login.microsoftonline.com/<tenant_id>/oauth2/token 端點。To obtain the access token, follow the instructions in Service to Service Calls Using Client Credentials to send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. 以下是範例要求。Here is a sample request.

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 中的 租使用者 _ 識別碼 值,以及 客戶 _ 端識別碼 和用戶端 * _ 密碼* 參數,指定您的應用程式的租使用者識別碼、用戶端識別碼和金鑰,並從上一節的合作夥伴中心中取出。For the tenant_id value in the POST URI and the client_id and client_secret parameters, specify the tenant ID, client ID and the key for your application that you retrieved from Partner Center in the previous section. 針對 resource 參數,您必須指定 https://manage.devcenter.microsoft.comFor the resource parameter, you must specify https://manage.devcenter.microsoft.com.

存取權杖到期之後,您可以按照這裡的指示,重新整理權杖。After your access token expires, you can refresh it by following the instructions here.

步驟 3:呼叫 Microsoft Store 分析 APIStep 3: Call the Microsoft Store analytics API

有了 Azure AD 存取權杖之後,就可以呼叫 Microsoft Store 分析 API。After you have an Azure AD access token, you are ready to call the Microsoft Store analytics API. 您必須將存取權杖傳送給每個方法的 Authorization 標頭。You must pass the access token to the Authorization header of each method.

UWP 應用程式和遊戲的方法Methods for UWP apps and games

下列方法適用于應用程式和遊戲的取得和附加元件的收購:The following methods are available for apps and games acquisitions and add-on acquisitions:

適用於 UWP app 的方法Methods for UWP apps

下列分析方法適用于合作夥伴中心中的 UWP 應用程式。The following analytics methods are available for UWP apps in Partner Center.

案例Scenario 方法Methods
收購、轉換、安裝和使用方式Acquisitions, conversions, installs, and usage
App 錯誤App errors
深入解析Insights
評分與評論Ratings and reviews
應用程式內廣告與廣告行銷活動In-app ads and ad campaigns

傳統型應用程式的方法Methods for desktop applications

下列分析方法可供隸屬於 Windows 傳統型應用程式計畫的開發人員帳戶使用。The following analytics methods are available for use by developer accounts that belong to the Windows Desktop Application program.

案例Scenario 方法Methods
安裝數Installs
區塊Blocks
應用程式錯誤Application errors
深入解析Insights

適用於 Xbox Live 服務的方法Methods for Xbox Live services

下列其他方法可供使用 Xbox Live 服務的遊戲開發人員帳戶使用。The following additional methods are available for use by developer accounts with games that use Xbox Live services.

案例Scenario 方法Methods
一般分析General analytics
健康情況分析Health analytics
社群分析Community analytics

硬體與驅動程式的方法Methods for hardware and drivers

屬於 Windows 硬體儀表板程式 的開發人員帳戶,可以存取一組額外的方法來取得硬體和驅動程式的分析資料。Developer accounts that belong to the Windows hardware dashboard program have access to an additional set of methods for retrieving analytics data for hardware and drivers. 如需詳細資訊,請參閱 硬體儀表板 APIFor more information, see Hardware dashboard API.

程式碼範例Code example

下列程式碼範例示範如何取得 Azure AD 存取權杖,並從 C# 主控台應用程式呼叫 Microsoft Store 分析 API。The following code example demonstrates how to obtain an Azure AD access token and call the Microsoft Store analytics API from a C# console app. 若要使用此程式碼範例,請針對您的案例將 tenantIdclientIdclientSecretappID 變數指定為適當的值。To use this code example, assign the tenantId, clientId, clientSecret, and appID variables to the appropriate values for your scenario. 此範例需要 Newtonsoft 的 Json.NET package,以還原序列化 Microsoft Store 分析 API 傳回的 JSON 資料。This example requires the Json.NET package from Newtonsoft to deserialize the JSON data returned by the Microsoft Store analytics API.

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

錯誤回應Error responses

Microsoft Store 分析 API 會以包含錯誤碼和訊息的 JSON 物件,傳回錯誤回應。The Microsoft Store analytics API returns error responses in a JSON object that contains error codes and messages. 下列範例示範由無效的參數造成的錯誤回應。The following example demonstrates an error response caused by an invalid parameter.

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