Mengakses data analitik menggunakan layanan Store

Artikel
06/14/2024

Gunakan API analitik Microsoft Store untuk mengambil data analitik secara terprogram untuk aplikasi yang didaftarkan ke akun Pusat Mitra Windows organisasi Anda atau Anda. API ini memungkinkan Anda mengambil data untuk aplikasi dan add-on (juga dikenal sebagai akuisisi produk dalam aplikasi atau IAP), kesalahan, peringkat aplikasi, dan ulasan. API ini menggunakan Microsoft Entra 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 MICROSOFT Store analytics API, dapatkan token akses Microsoft Entra. 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 menghasilkan token baru.
Panggil API analitik Microsoft Store.

Langkah 1: Lengkapi 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 Microsoft Entra dan Anda harus memiliki izin Administrator global untuk direktori tersebut. Jika Anda sudah menggunakan Microsoft 365 atau layanan bisnis lainnya dari Microsoft, Anda sudah memiliki direktori Microsoft Entra. Jika tidak, Anda dapat membuat yang baru di Pusat Mitra tanpa biaya tambahan.
Anda harus mengaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda, mengambil ID penyewa dan ID klien untuk aplikasi dan membuat kunci. Aplikasi Microsoft Entra mewakili aplikasi atau layanan tempat Anda ingin memanggil API analitik Microsoft Store. Anda memerlukan ID penyewa, ID klien, dan kunci untuk mendapatkan token akses Microsoft Entra yang Anda teruskan 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 membuat token akses Microsoft Entra baru.

Untuk mengaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda dan mengambil nilai yang diperlukan:

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

Langkah 2: Mendapatkan token akses Microsoft Entra

Sebelum memanggil salah satu metode di API analitik Microsoft Store, Anda harus terlebih dahulu mendapatkan token akses Microsoft Entra yang Anda teruskan ke header Otorisasi dari setiap metode di API. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakan token akses 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.

Catatan

ResourceType=Graph.windows.net tidak digunakan lagi pada Bulan September 2023. Silakan migrasikan ke ResourceType =Graph.microsoft.com.

Langkah 3: Panggil API analitik Microsoft Store

Setelah Anda memiliki token akses Microsoft Entra, 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 dan 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 menurut saluran Mendapatkan akuisisi add-on Mendapatkan akuisisi add-on langganan Mendapatkan konversi add-on menurut 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
Insights	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 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 Dapatkan 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
Insights	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 milik 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 Microsoft Entra 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"
}

Bagikan melalui