Mengelola pemberian izin produk dari layanan

  • Artikel

Jika Anda memiliki katalog aplikasi dan add-on, Anda dapat menggunakan API koleksi Microsoft Store dan API pembelian Microsoft Store untuk mengakses informasi pemberian hak untuk produk ini dari layanan Anda. Hak mewakili hak pelanggan untuk menggunakan aplikasi atau add-on yang diterbitkan melalui Microsoft Store.

API ini terdiri dari metode REST yang dirancang untuk digunakan oleh pengembang dengan katalog add-on yang didukung oleh layanan lintas platform. API ini memungkinkan Anda melakukan hal berikut:

Catatan

API pengumpulan Microsoft Store dan API pembelian menggunakan autentikasi Azure Active Directory (Azure AD) untuk mengakses informasi kepemilikan pelanggan. Untuk menggunakan API ini, 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.

Pustaka Microsoft.StoreServices

Untuk membantu menyederhanakan alur autentikasi dan memanggil Microsoft Store Services, tinjau proyek Microsoft.StoreServices dan sampel di Github. Pustaka Microsoft.StoreServices akan membantu mengelola kunci autentikasi dan menyediakan API pembungkus untuk dipanggil ke Microsoft Store Services untuk mengelola produk. Proyek sampel menyoroti bagaimana layanan dapat menggunakan pustaka Microsoft.StoreServices, contoh logika untuk mengelola produk yang dapat dikonsumsi, menyesuaikan pembelian yang dikembalikan dananya, memperbarui kredensial yang kedaluwarsa, dan banyak lagi. Panduan konfigurasi langkah demi langkah disertakan dengan sampel untuk menyiapkan layanan sampel di PC Anda atau melalui Azure.

Gambaran Umum

Langkah-langkah berikut menjelaskan proses end-to-end untuk menggunakan API pengumpulan Microsoft Store dan API pembelian:

  1. Mengonfigurasi aplikasi di Azure AD.
  2. Kaitkan ID aplikasi Azure AD Anda dengan aplikasi Anda di Pusat Mitra.
  3. Di layanan Anda, buat Azure AD token akses yang mewakili identitas penerbit Anda.
  4. Di aplikasi Windows klien Anda, buat kunci ID Microsoft Store yang mewakili identitas pengguna saat ini, dan teruskan kunci ini kembali ke layanan Anda.

Proses end-to-end ini melibatkan dua komponen perangkat lunak yang melakukan tugas yang berbeda:

  • Layanan Anda. Ini adalah aplikasi yang berjalan dengan aman dalam konteks lingkungan bisnis Anda, dan dapat diimplementasikan menggunakan platform pengembangan apa pun yang Anda pilih. Layanan Anda bertanggung jawab untuk membuat token akses Azure AD yang diperlukan untuk skenario dan untuk memanggil URI REST untuk API pengumpulan Microsoft Store dan membeli API.
  • Aplikasi Windows klien Anda. Ini adalah aplikasi yang ingin Anda akses dan kelola informasi pemberian hak pelanggan (termasuk add-on untuk aplikasi). Aplikasi ini bertanggung jawab untuk membuat kunci ID Microsoft Store yang Anda butuhkan untuk memanggil API pengumpulan Microsoft Store dan membeli API dari layanan Anda.

Langkah 1: Mengonfigurasi aplikasi di Azure AD

Sebelum dapat menggunakan API pengumpulan Microsoft Store atau API pembelian, Anda harus membuat aplikasi web Azure AD, mengambil ID penyewa dan ID aplikasi untuk aplikasi, dan membuat kunci. Aplikasi web Azure AD mewakili layanan tempat Anda ingin memanggil API pengumpulan Microsoft Store atau membeli API. Anda memerlukan ID penyewa, ID aplikasi, dan kunci untuk menghasilkan token akses Azure AD yang Anda butuhkan untuk memanggil API.

  1. Jika Anda belum melakukannya, ikuti instruksi dalam Mengintegrasikan Aplikasi dengan Azure Active Directory untuk mendaftarkan aplikasi Web /API dengan Azure AD.

    Catatan

    Saat mendaftarkan aplikasi, Anda harus memilih Aplikasi web/API sebagai jenis aplikasi sehingga Anda dapat mengambil kunci (juga disebut rahasia klien) untuk aplikasi Anda. Untuk memanggil API pengumpulan Microsoft Store atau API pembelian, Anda harus memberikan rahasia klien saat meminta token akses dari Azure AD di langkah selanjutnya.

  2. Di Portal Manajemen Azure, navigasikan ke Azure Active Directory. Pilih direktori Anda, klik Pendaftaran aplikasi di panel navigasi kiri, lalu pilih aplikasi Anda.

  3. Anda dibawa ke halaman pendaftaran utama aplikasi. Pada halaman ini, salin nilai ID Aplikasi untuk digunakan nanti.

  4. Buat kunci yang akan Anda butuhkan nanti (ini semua disebut rahasia klien). Di panel kiri, klik Pengaturan lalu Kunci. Pada halaman ini, selesaikan langkah-langkah untuk membuat kunci. Salin kunci ini untuk digunakan nanti.

Langkah 2: Kaitkan ID aplikasi Azure AD Anda dengan aplikasi klien Anda di Pusat Mitra

Sebelum dapat menggunakan API koleksi Microsoft Store atau membeli API untuk mengonfigurasi kepemilikan dan pembelian untuk aplikasi atau add-on, Anda harus mengaitkan ID aplikasi Azure AD dengan aplikasi (atau aplikasi yang berisi add-on) di Pusat Mitra.

Catatan

Anda hanya perlu melakukan tugas ini satu kali. Setelah Anda memiliki ID penyewa, ID aplikasi, dan rahasia klien, Anda dapat menggunakan kembali nilai-nilai ini kapan saja Anda perlu membuat token akses Azure AD baru.

  1. Masuk ke Pusat Mitra dan pilih aplikasi Anda.
  2. Buka halamanKoleksi dan pembelian ProdukLayanan> dan masukkan ID aplikasi Azure AD Anda ke salah satu bidang ID Klien yang tersedia.

Langkah 3: Membuat token akses Azure AD

Sebelum Anda dapat mengambil kunci ID Microsoft Store atau memanggil API pengumpulan Microsoft Store atau membeli API, layanan Anda harus membuat beberapa token akses Azure AD berbeda yang mewakili identitas penerbit Anda. Setiap token akan digunakan dengan API yang berbeda. Masa pakai setiap token adalah 60 menit, dan Anda dapat merefreshnya setelah kedaluwarsa.

Penting

Buat token akses Azure AD hanya dalam konteks layanan Anda, bukan di aplikasi Anda. Rahasia klien Anda dapat disusupi jika dikirim ke aplikasi Anda.

Memahami berbagai token dan URI audiens

Bergantung pada metode mana yang ingin Anda panggil di API pengumpulan Microsoft Store atau API pembelian, Anda harus membuat dua atau tiga token yang berbeda. Setiap token akses dikaitkan dengan URI audiens yang berbeda.

  • Dalam semua kasus, Anda harus membuat token dengan https://onestore.microsoft.com URI audiens. Di langkah selanjutnya, Anda akan meneruskan token ini ke header Otorisasi metode di API pengumpulan Microsoft Store atau API pembelian.

    Penting

    https://onestore.microsoft.com Gunakan audiens hanya dengan token akses yang disimpan dengan aman dalam layanan Anda. Mengekspos token akses dengan audiens ini di luar layanan Anda dapat membuat layanan Anda rentan terhadap serangan pemutaran ulang.

  • Jika Anda ingin memanggil metode di API pengumpulan Microsoft Store untuk mengkueri produk yang dimiliki oleh pengguna atau melaporkan produk yang dapat dikonsumsi sesuai kebutuhan, Anda juga harus membuat token dengan https://onestore.microsoft.com/b2b/keys/create/collections URI audiens. Di langkah selanjutnya, Anda akan meneruskan token ini ke metode klien di Windows SDK untuk meminta kunci ID Microsoft Store yang dapat Anda gunakan dengan API koleksi Microsoft Store.

  • Jika Anda ingin memanggil metode di API pembelian Microsoft Store untuk memberikan produk gratis kepada pengguna, mendapatkan langganan untuk pengguna, atau mengubah status penagihan langganan untuk pengguna, Anda juga harus membuat token dengan https://onestore.microsoft.com/b2b/keys/create/purchase URI audiens. Di langkah selanjutnya, Anda akan meneruskan token ini ke metode klien di Windows SDK untuk meminta kunci ID Microsoft Store yang dapat Anda gunakan dengan API pembelian Microsoft Store.

Membuat token

Untuk membuat token akses, gunakan API OAuth 2.0 di layanan Anda dengan mengikuti 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://onestore.microsoft.com

Untuk setiap token, tentukan data parameter berikut:

  • Untuk parameter client_id dan client_secret , tentukan ID aplikasi dan rahasia klien untuk aplikasi yang Anda ambil dari Portal Manajemen Azure. Kedua parameter ini diperlukan untuk membuat token akses dengan tingkat autentikasi yang diperlukan oleh API pengumpulan Microsoft Store atau API pembelian.

  • Untuk parameter sumber daya , tentukan salah satu URI audiens yang tercantum di bagian sebelumnya, tergantung pada jenis token akses yang Anda buat.

Setelah token akses kedaluwarsa, Anda dapat merefreshnya dengan mengikuti instruksi di sini. Untuk detail selengkapnya tentang struktur token akses, lihat Jenis Token dan Klaim yang Didukung.

Langkah 4: Membuat kunci ID Microsoft Store

Sebelum Dapat memanggil metode apa pun di API pengumpulan Microsoft Store atau membeli API, aplikasi Anda harus membuat kunci ID Microsoft Store dan mengirimkannya ke layanan Anda. Kunci ini adalah JSON Web Token (JWT) yang mewakili identitas pengguna yang informasi kepemilikan produknya ingin Anda akses. Untuk informasi selengkapnya tentang klaim dalam kunci ini, lihat Klaim di kunci ID Microsoft Store.

Saat ini, satu-satunya cara untuk membuat kunci ID Microsoft Store adalah dengan memanggil API Platform Windows Universal (UWP) dari kode klien di aplikasi Anda. Kunci yang dihasilkan mewakili identitas pengguna yang saat ini masuk ke Microsoft Store di perangkat.

Catatan

Setiap kunci ID Microsoft Store berlaku selama 90 hari. Setelah kunci kedaluwarsa, Anda dapat memperbarui kunci. Kami menyarankan agar Anda memperbarui kunci ID Microsoft Store daripada membuat yang baru.

Untuk membuat kunci ID Microsoft Store untuk API pengumpulan Microsoft Store

Ikuti langkah-langkah ini untuk membuat kunci ID Microsoft Store yang dapat Anda gunakan dengan API koleksi Microsoft Store untuk mengkueri produk yang dimiliki oleh pengguna atau melaporkan produk yang dapat dikonsumsi sebagai terpenuhi.

  1. Teruskan token akses Azure AD yang memiliki nilai https://onestore.microsoft.com/b2b/keys/create/collections URI audiens dari layanan Anda ke aplikasi klien Anda. Ini adalah salah satu token yang Anda buat sebelumnya di langkah 3.

  2. Dalam kode aplikasi Anda, panggil salah satu metode ini untuk mengambil kunci ID Microsoft Store:

  • Jika aplikasi Anda menggunakan kelas StoreContext di namespace Windows.Services.Store untuk mengelola pembelian dalam aplikasi, gunakan metode StoreContext.GetCustomerCollectionsIdAsync .

  • Jika aplikasi Anda menggunakan kelas CurrentApp di namespace Windows.ApplicationModel.Store untuk mengelola pembelian dalam aplikasi, gunakan metode CurrentApp.GetCustomerCollectionsIdAsync .

    Teruskan token akses Azure AD Anda ke parameter serviceTicket metode . Jika Anda mempertahankan ID pengguna anonim dalam konteks layanan yang Anda kelola sebagai penerbit aplikasi saat ini, Anda juga dapat meneruskan ID pengguna ke parameter publisherUserId untuk mengaitkan pengguna saat ini dengan kunci ID Microsoft Store baru (ID pengguna akan disematkan di kunci). Jika tidak, jika Anda tidak perlu mengaitkan ID pengguna dengan kunci ID Microsoft Store, Anda dapat meneruskan nilai string apa pun ke parameter publisherUserId .

  1. Setelah aplikasi Anda berhasil membuat kunci ID Microsoft Store, teruskan kunci kembali ke layanan Anda.

Untuk membuat kunci ID Microsoft Store untuk API pembelian Microsoft Store

Ikuti langkah-langkah ini untuk membuat kunci ID Microsoft Store yang dapat Anda gunakan dengan API pembelian Microsoft Store untuk memberikan produk gratis kepada pengguna, mendapatkan langganan untuk pengguna, atau mengubah status penagihan langganan untuk pengguna.

  1. Teruskan token akses Azure AD yang memiliki nilai https://onestore.microsoft.com/b2b/keys/create/purchase URI audiens dari layanan Anda ke aplikasi klien Anda. Ini adalah salah satu token yang Anda buat sebelumnya di langkah 3.

  2. Dalam kode aplikasi Anda, panggil salah satu metode ini untuk mengambil kunci ID Microsoft Store:

  • Jika aplikasi Anda menggunakan kelas StoreContext di namespace Windows.Services.Store untuk mengelola pembelian dalam aplikasi, gunakan metode StoreContext.GetCustomerPurchaseIdAsync .

  • Jika aplikasi Anda menggunakan kelas CurrentApp di namespace Windows.ApplicationModel.Store untuk mengelola pembelian dalam aplikasi, gunakan metode CurrentApp.GetCustomerPurchaseIdAsync .

    Teruskan token akses Azure AD Anda ke parameter serviceTicket metode . Jika Anda mempertahankan ID pengguna anonim dalam konteks layanan yang Anda kelola sebagai penerbit aplikasi saat ini, Anda juga dapat meneruskan ID pengguna ke parameter publisherUserId untuk mengaitkan pengguna saat ini dengan kunci ID Microsoft Store baru (ID pengguna akan disematkan di kunci). Jika tidak, jika Anda tidak perlu mengaitkan ID pengguna dengan kunci ID Microsoft Store, Anda dapat meneruskan nilai string apa pun ke parameter publisherUserId .

  1. Setelah aplikasi Anda berhasil membuat kunci ID Microsoft Store, teruskan kunci kembali ke layanan Anda.

Diagram

Diagram berikut mengilustrasikan proses pembuatan kunci ID Microsoft Store.

Membuat kunci ID Windows Store

Klaim dalam kunci ID Microsoft Store

Kunci ID Microsoft Store adalah JSON Web Token (JWT) yang mewakili identitas pengguna yang informasi kepemilikan produknya ingin Anda akses. Saat didekodekan menggunakan Base64, kunci ID Microsoft Store berisi klaim berikut.

  • iat: Mengidentifikasi waktu saat kunci dikeluarkan. Klaim ini dapat digunakan untuk menentukan usia token. Nilai ini dinyatakan sebagai waktu zaman.
  • iss: Mengidentifikasi penerbit. Ini memiliki nilai yang sama dengan aud klaim.
  • aud: Mengidentifikasi audiens. Harus salah satu nilai berikut: https://collections.mp.microsoft.com/v6.0/keys atau https://purchase.mp.microsoft.com/v6.0/keys.
  • exp: Mengidentifikasi waktu kedaluwarsa pada atau setelah itu kunci tidak akan lagi diterima untuk memproses apa pun kecuali untuk memperbarui kunci. Nilai klaim ini dinyatakan sebagai waktu zaman.
  • nbf: Mengidentifikasi waktu di mana token akan diterima untuk diproses. Nilai klaim ini dinyatakan sebagai waktu zaman.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: ID klien yang mengidentifikasi pengembang.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: Payload buram (dienkripsi dan dikodekan Base64) yang berisi informasi yang hanya dimaksudkan untuk digunakan oleh layanan Microsoft Store.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: ID pengguna yang mengidentifikasi pengguna saat ini dalam konteks layanan Anda. Ini adalah nilai yang sama dengan yang Anda berikan ke parameter publisherUserId opsional dari metode yang Anda gunakan untuk membuat kunci.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: URI yang dapat Anda gunakan untuk memperbarui kunci.

Berikut adalah contoh header kunci ID Microsoft Store yang didekodekan.

{
    "typ":"JWT",
    "alg":"RS256",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

Berikut adalah contoh kumpulan klaim kunci ID Microsoft Store yang didekodekan.

{
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d5773695a3b44928227393bfef1e13d",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "ZdcOq0/N2rjytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQMLaYCrgtC0d/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
    "iat": 1442395542,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1450171541,
    "nbf": 1442391941
}