Bagikan melalui

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 Microsoft 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 Active Directory.

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, merekonsiliasi 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 ACTIVE Directory.
  2. Kaitkan ID aplikasi Microsoft Azure ACTIVE Directory Anda dengan aplikasi Anda di Pusat Mitra.
  3. Di layanan Anda, buat token akses Azure ACTIVE Directory 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 ACTIVE Directory yang diperlukan untuk skenario dan untuk memanggil REST URI 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 ACTIVE Directory

Sebelum dapat menggunakan API pengumpulan Microsoft Store atau membeli API, Anda harus membuat aplikasi Web Azure AD, mengambil ID penyewa dan ID aplikasi untuk aplikasi, dan membuat kunci. Aplikasi Web Azure ACTIVE Directory 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 Microsoft Azure AD yang perlu Anda panggil API.

  1. Jika Anda belum melakukannya, ikuti instruksi dalam Mengintegrasikan Aplikasi dengan Azure Active Directory untuk mendaftarkan aplikasi Web /API dengan Microsoft 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 MEMBELI API, Anda harus memberikan rahasia klien saat meminta token akses dari Microsoft Azure ACTIVE Directory 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 Microsoft Azure ACTIVE Directory Anda dengan aplikasi klien Anda di Pusat Mitra

Sebelum dapat menggunakan API pengumpulan Microsoft Store atau membeli API untuk mengonfigurasi kepemilikan dan pembelian untuk aplikasi atau add-on, Anda harus mengaitkan ID aplikasi Microsoft Azure ACTIVE Directory Anda 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 ACTIVE Directory baru.

  1. Masuk ke Pusat Mitra dan pilih aplikasi Anda.
  2. Buka halaman Koleksi dan pembelian Produk Layanan>dan masukkan ID aplikasi Microsoft Azure ACTIVE Directory Anda ke salah satu bidang ID Klien yang tersedia.

Langkah 3: Membuat token akses Microsoft 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 ACTIVE Directory berbeda yang mewakili identitas penerbit Anda. Setiap token akan digunakan dengan API yang berbeda. Masa pakai setiap token adalah 60 menit, dan Anda dapat menyegarkannya setelah kedaluwarsa.

Penting

Buat token akses Azure ACTIVE Directory 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 koleksi 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 koleksi Microsoft Store atau MEMBELI API.

    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 koleksi Microsoft Store untuk mengkueri produk yang dimiliki oleh pengguna atau melaporkan produk yang dapat dikonsumsi sebagai terpenuhi, 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 MICROSOFT Store purchase API 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 di Service to Service Calls Using Client Credentials 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 MEMBELI API.

  • 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 koleksi Microsoft Store

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

  1. Teruskan token akses Microsoft Azure Active Directory 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:

  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 Microsoft Azure Active Directory 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:

  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 di mana kunci dikeluarkan. Klaim ini dapat digunakan untuk menentukan usia token. Nilai ini dinyatakan sebagai waktu epoch.
  • 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 epoch.
  • nbf: Mengidentifikasi waktu di mana token akan diterima untuk diproses. Nilai klaim ini dinyatakan sebagai waktu epoch.
  • 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
}