Mengakses data analitik menggunakan layanan Store

Artikel
03/18/2023

Gunakan API analitik Microsoft Store untuk mengambil data analitik secara terprogram untuk aplikasi yang terdaftar ke akun Pusat Mitra Windows organisasi Anda atau Anda. API ini memungkinkan Anda mengambil data untuk akuisisi aplikasi dan add-on (juga dikenal sebagai produk dalam aplikasi atau IAP), kesalahan, peringkat aplikasi, dan ulasan. API ini menggunakan Azure Active Directory (Azure AD) untuk mengautentikasi panggilan dari aplikasi atau layanan Anda.

Langkah-langkah berikut ini menjelaskan proses end-to-end:

Pastikan Anda telah menyelesaikan semua prasyarat.
Sebelum Anda memanggil metode di API analitik Microsoft Store, dapatkan token akses Azure AD. Setelah mendapatkan token, Anda memiliki waktu 60 menit untuk menggunakan token ini dalam panggilan ke API analitik Microsoft Store sebelum token kedaluwarsa. Setelah token kedaluwarsa, Anda dapat membuat token baru.
Panggil API analitik Microsoft Store.

Langkah 1: Selesaikan prasyarat untuk menggunakan API analitik Microsoft Store

Sebelum Anda mulai menulis kode untuk memanggil API analitik Microsoft Store, pastikan Anda telah menyelesaikan prasyarat berikut.

Anda (atau organisasi Anda) harus memiliki direktori Azure AD dan Anda harus memiliki izin Administrator global untuk direktori tersebut. Jika sudah menggunakan Microsoft 365 atau layanan bisnis lainnya dari Microsoft, Anda sudah memiliki direktori Azure AD. Jika tidak, Anda dapat membuat Azure AD baru di Pusat Mitra tanpa biaya tambahan.
Anda harus mengaitkan aplikasi Azure AD dengan akun Pusat Mitra Anda, mengambil ID penyewa dan ID klien untuk aplikasi dan membuat kunci. Aplikasi Azure AD mewakili aplikasi atau layanan tempat Anda ingin memanggil API analitik Microsoft Store. Anda memerlukan ID penyewa, ID klien, dan kunci untuk mendapatkan token akses Azure AD yang Anda berikan ke API.

Catatan

Anda hanya perlu melakukan tugas ini satu kali. Setelah Anda memiliki ID penyewa, ID klien, dan kunci, Anda dapat menggunakannya kembali kapan saja Anda perlu untuk membuat token akses Azure AD baru.

Untuk mengaitkan aplikasi Azure AD dengan akun Pusat Mitra Anda dan mengambil nilai yang diperlukan:

Di Pusat Mitra, kaitkan akun Pusat Mitra organisasi Anda dengan direktori Azure AD organisasi Anda.
Selanjutnya, dari halaman Pengguna di bagian Pengaturan akun di Pusat Mitra, tambahkan aplikasi Azure AD yang mewakili aplikasi atau layanan yang akan Anda gunakan untuk mengakses data analitik untuk akun Pusat Mitra Anda. Pastikan Anda menetapkan aplikasi ini sebagai peranManager. Jika aplikasi belum ada di direktori Azure AD, Anda dapat membuat aplikasi Azure AD baru di Pusat Mitra.
Kembali ke halaman Pengguna, klik nama aplikasi Azure AD Anda untuk masuk ke pengaturan aplikasi, dan salin nilai ID Penyewa dan ID Klien.
Klik Tambahkan kunci baru. Pada layar berikut, salin ke bawah nilai Kunci. Anda tidak akan bisa mengakses info ini lagi setelah meninggalkan halaman ini. Untuk informasi selengkapnya, lihat Mengelola kunci untuk aplikasi Azure AD.

Langkah 2 : Mendapatkan token akses Azure AD

Sebelum memanggil salah satu metode di API analitik Microsoft Store, Anda harus terlebih dahulu mendapatkan token akses Azure AD yang Anda berikan ke header Otorisasi dari setiap metode di API. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakannya sebelum masa berlakunya habis. Setelah token kedaluwarsa, Anda dapat merefresh token sehingga Anda dapat terus menggunakannya dalam panggilan lebih lanjut ke API.

Untuk mendapatkan token akses, ikuti instruksi dalam Panggilan Layanan ke Layanan Menggunakan Kredensial Klien untuk mengirim HTTP POST ke https://login.microsoftonline.com/<tenant_id>/oauth2/token titik akhir. Berikut adalah contoh permintaan.

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

Untuk nilai tenant_id di POST URI dan parameter client_id dan client_secret , tentukan ID penyewa, ID klien, dan kunci untuk aplikasi yang Anda ambil dari Pusat Mitra di bagian sebelumnya. Untuk parameter sumber daya, Anda harus menentukan https://manage.devcenter.microsoft.com.

Setelah token akses kedaluwarsa, Anda dapat merefreshnya dengan mengikuti instruksi di sini.

> [!NOTE]
> ResourceType='Graph.windows.net' will be deprecated after September 2023. Please migrate to ResourceType ='Graph.microsoft.com'

Langkah 3: Memanggil API analitik Microsoft Store

Setelah Anda memiliki token akses Azure AD, Anda siap untuk memanggil API analitik Microsoft Store. Anda harus meneruskan token akses ke header Otorisasi dari setiap metode.

Metode untuk aplikasi dan game UWP

Metode berikut tersedia untuk akuisisi aplikasi dan game serta akuisisi add-on:

Metode untuk aplikasi UWP

Metode analitik berikut tersedia untuk aplikasi UWP di Pusat Mitra.

Skenario	Metode
Akuisisi, konversi, penginstalan, dan penggunaan	Mendapatkan akuisisi aplikasi (warisan ) Mendapatkan data corong akuisisi aplikasi (warisan) Mendapatkan konversi aplikasi berdasarkan saluran Mendapatkan akuisisi add-on Mendapatkan akuisisi add-on langganan Mendapatkan konversi add-on berdasarkan saluran Mendapatkan penginstalan aplikasi Mendapatkan penggunaan aplikasi harian Mendapatkan penggunaan aplikasi bulanan
Kesalahan aplikasi	Mendapatkan data pelaporan kesalahan Mendapatkan detail untuk kesalahan di aplikasi Anda Dapatkan jejak tumpukan untuk kesalahan di aplikasi Anda Unduh file CAB untuk kesalahan di aplikasi Anda
Wawasan	Mendapatkan data wawasan untuk aplikasi Anda
Peringkat dan ulasan	Mendapatkan peringkat aplikasi Mendapatkan ulasan aplikasi
Iklan dalam aplikasi dan kampanye iklan	Mendapatkan data performa iklan Mendapatkan data performa kampanye iklan

Metode untuk aplikasi desktop

Metode analitik berikut ini tersedia untuk digunakan oleh akun pengembang milik program Aplikasi Desktop Windows.

Skenario	Metode
Menginstal	Mendapatkan penginstalan aplikasi desktop
Blok	Mendapatkan blok peningkatan untuk aplikasi desktop Anda Mendapatkan detail blok peningkatan untuk aplikasi desktop Anda
Kesalahan aplikasi	Mendapatkan data pelaporan kesalahan untuk aplikasi desktop Anda Mendapatkan detail untuk kesalahan di aplikasi desktop Anda Dapatkan jejak tumpukan untuk kesalahan di aplikasi desktop Anda Unduh file CAB untuk kesalahan di aplikasi desktop Anda
Wawasan	Mendapatkan data wawasan untuk aplikasi desktop Anda

Metode untuk layanan Xbox Live

Metode tambahan berikut ini tersedia untuk digunakan oleh akun pengembang dengan game yang menggunakan layanan Xbox Live. Microsoft Store Analytics API untuk Xbox tidak lagi tersedia. gaming/xbox-live/get-started/join-dev-program/join-dev-program_nav

Skenario	Metode
Analitik umum	Mendapatkan data analitik Xbox Live

Metode untuk perangkat keras dan driver

Akun pengembang yang termasuk dalam program dasbor perangkat keras Windows memiliki akses ke serangkaian metode tambahan untuk mengambil data analitik untuk perangkat keras dan driver. Untuk informasi selengkapnya, lihat API dasbor perangkat keras.

Contoh kode

Contoh kode berikut menunjukkan cara mendapatkan token akses Azure AD dan memanggil API analitik Microsoft Store dari aplikasi konsol C#. Untuk menggunakan contoh kode ini, tetapkan variabel tenantId, clientId, clientSecret, dan appID ke nilai yang sesuai untuk skenario Anda. Contoh ini memerlukan paket Json.NET dari Newtonsoft untuk mendeserialisasi data JSON yang dikembalikan oleh API analitik 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;
        }
    }
}

Respons kesalahan

API analitik Microsoft Store mengembalikan respons kesalahan dalam objek JSON yang berisi kode kesalahan dan pesan. Contoh berikut menunjukkan respons kesalahan yang disebabkan oleh parameter yang tidak valid.

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