Bagikan melalui

Mengelola penghasilan menggunakan API Layanan Penghasilan

Artikel ini menjelaskan bagaimana Anda dapat mengakses data penghasilan melalui Earnings APIs, bukan melalui Partner Center UI. API ini menyediakan cara terprogram untuk menyediakan kemampuan fitur Ekspor data di Pusat Mitra.

Penting

Grafik Azure Active Directory (Azure AD) tidak digunakan lagi per 30 Juni 2023. Ke depannya, kami tidak melakukan investasi lebih lanjut di Azure AD Graph. API Azure AD Graph tidak memiliki komitmen SLA atau pemeliharaan di luar perbaikan terkait keamanan. Investasi dalam fitur dan fungsionalitas baru hanya akan dilakukan di Microsoft Graph.

Kami akan menghentikan Azure AD Graph dalam langkah-langkah bertahap sehingga Anda memiliki waktu yang cukup untuk memigrasikan aplikasi Anda ke MICROSOFT Graph API. Di kemudian hari yang akan kami umumkan, kami akan memblokir pembuatan aplikasi baru apa pun menggunakan Azure AD Graph.

Untuk mempelajari selengkapnya, lihat Penting: Pemensiunan Azure AD Graph dan Penghapusan Modul PowerShell.

API yang Tersedia

Lihat semua API yang tersedia di Pembayaran Mitra.

Prasyarat

  • Memiliki langganan yang berfungsi di portal Microsoft Azure.
  • Memiliki akses ke browser web.
  • Dapat melakukan panggilan REST API, baik secara terprogram atau melalui perangkat lunak khusus.

Mendaftarkan aplikasi dengan platform identitas Microsoft

  1. Ikuti instruksi untuk membuat Pendaftaran Aplikasi dengan Microsoft Identity Platform.

  2. Berikan aplikasi izin yang didelegasikan yang sesuai.

    1. Di pendaftaran aplikasi yang baru dibuat, buka Mengelola Izin API →. Pilih "Tambahkan izin." Cuplikan layar memperlihatkan tombol Tambahkan Izin.
    2. Pilih tab "API yang digunakan organisasi saya", lalu cari AppId "4990cffe-04e8-4e8b-808a-1175604b879f" atau dengan nama "Microsoft Dev Center." Untuk izin, pilih "user_impersonation." Pilih "Tambahkan izin."
      • Pemecahan masalah: Jika pencarian Dev Center API tidak menghasilkan apa pun, Anda mungkin perlu membuat prinsipal layanan yang diperlukan untuk mengakses API ini secara manual. Mereka dapat dibuat dengan AzCLI: 
        az ad sp create --id 4990cffe-04e8-4e8b-808a-1175604b879f
        Setelah itu, izin API harus tersedia untuk dipilih dari dialog pencarian. Cuplikan layar memperlihatkan izin penyamaran_pengguna.
    3. Selain itu, pastikan aplikasi Anda memiliki izin "User.Read" di Microsoft Graph. Jika tidak, tambahkan dengan memilih Microsoft Graph di tab API Microsoft.
    4. Pilih "Berikan persetujuan admin" untuk ketiga izin yang Anda peroleh.
    5. Izin aplikasi Anda akan terlihat sebagai berikut (perhatikan tanda centang hijau di samping setiap izin): Cuplikan layar memperlihatkan daftar izin yang diperlukan dengan persetujuan admin yang diberikan.

  3. Siapkan URI pengalihan untuk platform Web.

    1. Pergi ke Kelola → Autentikasi. Pilih "Tambahkan platform." Cuplikan layar memperlihatkan tombol Tambahkan platform.
    2. Pilih "Web."
    3. Di URI Pengalihan, masukkan URI yang ingin Anda gunakan untuk aplikasi Anda, misalnya https://localhost:3000. Catat URI ini untuk nanti. Tekan "Konfigurasikan." Cuplikan layar memperlihatkan tab URI Pengalihan dengan contoh URI port 3000 di localhost.

  4. Buat rahasia klien untuk digunakan saat mendapatkan token akses.

    1. Pergi ke Kelola → Sertifikat & rahasia. Buka tab "Rahasia klien", pilih "Rahasia klien baru." Cuplikan layar memperlihatkan tombol Tambahkan Rahasia Klien.
    2. Masukkan nama dan durasi yang diinginkan.
    3. Pilih Tambahkan rahasia.
    4. Catat nilai tersebut di tempat lain. Pastikan untuk menyimpannya di lokasi yang aman, misalnya brankas kunci. Anda menggunakan rahasia ini saat meminta AccessToken dan RefreshToken.

Dapatkan Token Akses - Akun yang mendukung MFA

API Penghasilan memerlukan AccessToken untuk disediakan sebagai token pembawa Otorisasi dalam permintaan, dengan awalan Bearer <access-token> di header Otorisasi. Anda dapat memperoleh token ini dengan masuk dengan akun Anda; namun, token akses berumur pendek. Masuk ke akun berkemampuan MFA untuk menghasilkan token setiap kali Anda perlu memanggil API tidak praktis untuk alur kerja yang melibatkan otomatisasi. Langkah-langkah ini memandu Anda melalui proses untuk menghasilkan RefreshToken. Ini memiliki umur yang lebih lama (sekitar 3 bulan) dan dapat digunakan untuk mendapatkan AccessToken. Dengan menyimpan RefreshToken di lokasi yang aman, Anda dapat menggunakannya untuk mendapatkan AccessToken secara terprogram untuk memanggil API Penghasilan. Catatan: RefreshToken hanya dapat digunakan sekali, setelah itu menjadi usang. Dalam respons, RefreshToken baru dikembalikan bersama dengan AccessToken. Pastikan untuk mengganti nilai lama RefreshToken di penyimpanan aman Anda setiap kali Anda menggunakan RefreshToken.

  1. Dapatkan AuthCode melalui browser. Saat ini, proses ini harus dilakukan menggunakan UI browser web dan tidak dapat dilakukan secara terprogram.

    1. Ikuti templat di sini untuk membuat URL yang digunakan untuk mengambil AuthCode.
      1. Gunakan ID penyewa dan ID klien untuk aplikasi yang dibuat.
      2. Atur cakupan ke https://api.partner.microsoft.com/.default.
      3. Atur URL pengalihan ke URL pengalihan yang dikonfigurasi sebelumnya. Templat URL adalah: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize?client_id=<client-id>&response_type=code&redirect_uri=<redirect-uri>&scope=https%3A%2F%2Fapi.partner.microsoft.com%2F.default
    2. Buka URL bawaan dan masuk menggunakan kredensial pengguna yang berwenang.
    3. Setelah berhasil masuk, browser Anda mencoba membuka URL format <redirect-uri>/?code=<auth-code>&session_state=<state-id>#. Untuk contoh URI pengalihan di langkah sebelumnya, URL yang seharusnya Anda kunjungi adalah .https://localhost:3000/?code=<auth-code>?session_state=<state-id># Simpan AuthCode yang dikembalikan di tempat yang aman.
      • Karena biasanya tidak ada aplikasi yang mendengarkan di localhost:3000, browser memberikan pesan kesalahan "tidak dapat terhubung." Kesalahan ini diharapkan, karena kita hanya perlu menyalin nilai AuthCode secara manual dari parameter kueri URL yang code ditunjukkan sebelumnya.
      • Dalam solusi prod, seseorang mungkin membuat aplikasi yang secara otomatis menangani bagian proses autentikasi ini. Misalnya, itu bisa menjadi alur kerja di mana pengguna masuk ke aplikasi satu halaman (SPA). Pengguna memilih tombol "masuk" yang membawa mereka ke URL yang dibangun sebelumnya. Setelah masuk, SPA mengekstrak nilai AuthCode dan menyimpannya ke vault. SPA kemudian menggunakan AuthCode untuk mendapatkan RefreshToken dan AccessToken seperti yang dijelaskan dalam langkah berikutnya.

  2. Gunakan AuthCode untuk mendapatkan RefreshToken dan AccessToken awal. Catatan: RefreshToken kedaluwarsa setiap 3 bulan dan perlu dipertahankan dan disimpan di beberapa brankas kunci.

    1. Buat permintaan POST API dengan mengikuti templat yang disediakan di sini.
      1. Gunakan nilai yang sama untuk ID penyewa/klien dan url pengalihan.
      2. Atur cakupan ke https://api.partner.microsoft.com/.default offline_access.
      3. Atur kode ke AuthCode yang diperoleh pada langkah sebelumnya.
      4. Atur client_secret ke rahasia yang dihasilkan untuk aplikasi yang dibuat. URL kemudian harus disusun sebagai berikut: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token

  3. Nantinya, Anda dapat menggunakan RefreshToken untuk mendapatkan AccessToken baru.

    1. Buat permintaan POST API dengan mengikuti templat yang disediakan di sini.
      1. Gunakan nilai yang sama untuk ID penyewa/klien dan url pengalihan.
      2. Atur cakupan ke https://api.partner.microsoft.com/.default
      3. Atur refresh_token ke RefreshToken yang diperoleh di langkah sebelumnya
      4. Atur client_secret ke rahasia yang dihasilkan untuk aplikasi yang dibuat.

Dapatkan Token Akses - Akun non-MFA

  1. Dapatkan AccessToken menggunakan informasi untuk pendaftaran aplikasi baru.
    1. Buat permintaan POST API dengan mengikuti templat yang disediakan di sini.
      1. Gunakan nilai yang sama untuk ID penyewa/klien
      2. Atur cakupan ke https://api.partner.microsoft.com/.default
      3. Gunakan nama pengguna/kata sandi untuk pengguna yang berwenang URL kemudian harus disusun sebagai berikut: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    2. Permintaan mengembalikan AccessToken dan RefreshToken baru. Pastikan untuk memperbarui nilai tersimpan untuk RefreshToken, karena Anda tidak dapat lagi menggunakan nilai lama.

Pendapatan Panggilan (sebelumnya disebut riwayattransaksi)/Pembayaran

Konten terkait

  • Last updated on