Menetapkan peran Perjanjian Enterprise ke perwakilan layanan

2025-06-26

Anda dapat mengelola pendaftaran Perjanjian Enterprise (EA) di portal Azure. Anda dapat membuat berbagai peran untuk mengelola organisasi Anda, menampilkan biaya, dan membuat langganan. Artikel ini membantu Anda mengotomatiskan beberapa tugas tersebut dengan menggunakan Azure PowerShell dan REST API dengan perwakilan layanan ID Microsoft Entra.

Catatan

Jika Anda memiliki beberapa akun penagihan EA di organisasi, Anda harus memberikan peran EA kepada perwakilan layanan ID Microsoft Entra satu per satu di setiap akun penagihan EA.

Sebelum memulai, pastikan Anda sudah terbiasa dengan artikel berikut:

Anda memerlukan cara untuk memanggil REST API. Beberapa cara populer untuk mengkueri API adalah:

Membuat dan mengautentikasi perwakilan layanan Anda

Untuk mengotomatiskan tindakan EA dengan menggunakan perwakilan layanan, Anda perlu membuat identitas aplikasi Microsoft Entra, yang kemudian dapat mengautentikasi secara otomatis.

Ikuti langkah-langkah dalam artikel ini untuk membuat dan mengautentikasi menggunakan perwakilan layanan Anda.

Berikut adalah contoh halaman pendaftaran aplikasi.

Temukan ID perwakilan layanan dan penyewa Anda

Anda memerlukan ID objek prinsipal layanan dan ID penyewa. Anda memerlukan informasi ini untuk operasi penetapan izin nanti di artikel ini. Semua aplikasi terdaftar di ID Microsoft Entra di penyewa. Dua jenis objek dibuat saat pendaftaran aplikasi selesai:

Objek aplikasi - ID aplikasi adalah apa yang Anda lihat di bawah Aplikasi Perusahaan. Jangan gunakan ID untuk memberikan peran EA apa pun.
Objek Perwakilan Layanan - Objek Perwakilan Layanan adalah apa yang Anda lihat di jendela Pendaftaran Perusahaan di ID Microsoft Entra. ID objek digunakan untuk memberikan peran EA kepada prinsipal layanan.

Buka ID Microsoft Entra, lalu pilih Aplikasi perusahaan.
Temukan aplikasi Anda dalam daftar.
Pilih aplikasi untuk menemukan ID aplikasi dan ID objek:
Buka halaman Gambaran Umum Microsoft Entra ID untuk menemukan ID penyewa.

Catatan

Nilai ID penyewa Microsoft Entra Anda mirip dengan GUID dengan format berikut: aaaabbbb-0000-cccc-1111-dddd2222eeee.

Izin yang dapat ditetapkan ke prinsipal layanan

Selanjutnya dalam artikel ini, Anda memberikan izin kepada aplikasi Microsoft Entra untuk bertindak dengan menggunakan peran EA. Anda hanya dapat menetapkan peran berikut ke perwakilan layanan, dan Anda memerlukan ID definisi peran, persis seperti yang ditunjukkan.

Peranan	Tindakan yang diizinkan	ID peran definisi
EnrollmentReader	Lihat data di cakupan pendaftaran, departemen, dan akun. Data tersebut berisi biaya untuk semua langganan di bawah ruang lingkup, termasuk lintas penyewa. Dapat melihat saldo Azure Prepayment (sebelumnya disebut komitmen moneter) yang terkait dengan pendaftaran.	24f8edb6-1668-4659-b5e2-40bb5f3a7d7e
Pembeli EA	Beli pesanan reservasi dan lihat transaksi reservasi. Ini memiliki semua izin yang dimiliki oleh EnrollmentReader, yang pada gilirannya memiliki semua izin yang dimiliki oleh DepartmentReader. Dapat melihat penggunaan dan biaya di semua akun dan langganan. Dapat melihat saldo Azure Prepayment (sebelumnya disebut komitmen moneter) yang terkait dengan pendaftaran.	da6647fb-7651-49ee-be91-c43c4877f0c4
DepartmentReader	Unduh detail penggunaan untuk departemen yang mereka kelola. Dapat melihat penggunaan dan biaya yang terkait dengan departemen mereka.	db609904-a47f-4794-9be8-9bd86fbffd8a
Pembuat Langganan	Buat langganan baru dalam cakupan Akun tertentu.	a0bcee42-bf30-4d1b-926a-48d21664ef71
Pembaca Admin Kemitraan	Lihat data untuk semua pendaftaran di bawah organisasi mitra. Peran ini hanya tersedia untuk API berikut: - Saldo - Mengekspor V2 (versi API 2025-03-01 saja) - Hasilkan Laporan Detail Biaya - Platform Pasar - Lembar Harga Konsumsi - Unduh Daftar Harga Manajemen Biaya - Buat Laporan Detail Reservasi - Ringkasan Reservasi - Rekomendasi untuk Reservasi - Transaksi Reservasi	4f6144c0-a809-4c55-b3c8-7f9b7b15a1bf

Peran pengguna berikut ini diperlukan untuk menetapkan setiap peran prinsipal layanan:

EnrollmentReader: pengguna yang melakukan penetapan harus memiliki peran penulis pendaftaran.
DepartmentReader: pengguna yang ditetapkan harus memiliki peran penulis pendaftaran atau penulis departemen.
SubscriptionCreator: pengguna yang ditugaskan harus sebagai pemilik akun (administrator EA).
Pembeli EA: pengguna yang ditugaskan harus memiliki peran penulis pendaftaran.
Pembaca Admin Mitra: pengguna yang ditugaskan harus memiliki peran administrator mitra.

Semua peran ini dibuat dengan cara terprogram, tidak ditampilkan di portal Microsoft Azure, dan hanya untuk penggunaan terprogram.

Saat Anda memberikan peran EA kepada prinsipal layanan, Anda harus menggunakan property yang diperlukan billingRoleAssignmentName. Parameter ini adalah GUID unik yang harus Anda berikan. Anda dapat membuat GUID menggunakan perintah PowerShell New-Guid. Anda juga dapat menggunakan situs web Pembuat GUID/UUID Online untuk membuat GUID unik.

Perwakilan layanan hanya dapat memiliki satu peran.

Menetapkan peran ke perwakilan layanan

Ikuti langkah-langkah ini untuk menetapkan salah satu peran yang didukung ke prinsipal layanan:

Gunakan Penetapan Peran yang sesuai Letakkan REST API dan pilih Coba. Temukan API yang benar untuk digunakan dalam tabel di bawah ini.
Masuk ke tenant dengan akses yang sesuai.
Berikan parameter berikut dalam permintaan API Anda:
- billingAccountName: ID akun Penagihan. Untuk peran Pembaca Admin Mitra, gunakan format pcn.{PCN} (di mana {PCN} adalah Nomor Pelanggan Mitra Anda). Untuk semua peran lainnya, gunakan ID akun penagihan standar dari portal Microsoft Azure.
- billingRoleAssignmentName: GUID unik yang Anda hasilkan (lihat New-Guid).
- api-version: Gunakan 2019-10-01-preview kecuali dinyatakan lain.
- Parameter isi permintaan:
  - properties.principalId: ID Objek dari perwakilan layanan.
  - properties.principalTenantId: ID penyewa.
  - properties.roleDefinitionId: Gunakan nilai dari tabel di bawah ini.

Peranan	Peran pengguna yang diperlukan untuk ditetapkan	ID peran definisi	Referensi API	Catatan
EnrollmentReader	Penulis materi pendaftaran	24f8edb6-1668-4659-b5e2-40bb5f3a7d7e	Penetapan Peran - Put
Pembeli EA	Penulis materi pendaftaran	da6647fb-7651-49ee-be91-c43c4877f0c4	Penetapan Peran - Put
DepartmentReader	Penulis pendaftaran atau penulis departemen	db609904-a47f-4794-9be8-9bd86fbffd8a	Penetapan Peran Departemen Pendaftaran - Put	Gunakan parameter departmentName.
Pembuat Langganan	Pemilik akun pendaftaran (admin EA)	a0bcee42-bf30-4d1b-926a-48d21664ef71	Penetapan Peran Akun Pendaftaran - Put	Gunakan parameter enrollmentAccountName.
Pembaca Admin Kemitraan	Mitra Administrator	4f6144c0-a809-4c55-b3c8-7f9b7b15a1bf	Penetapan Peran - Put	Gunakan `pcn.{PCN}` untuk namaAkunPenagihan.

Pilih Jalankan untuk menjalankan perintah.

Sebuah respon 200 OK berarti bahwa perwakilan layanan berhasil diberi peran.

Verifikasi penugasan peran prinsipal layanan

Penetapan peran prinsipal layanan tidak terlihat di portal Azure. Anda dapat melihat penetapan peran akun pendaftaran, termasuk peran pembuat langganan, dengan API Billing Role Assignments - List By Enrollment Account - REST (Penagihan Azure). Gunakan API untuk memverifikasi bahwa penetapan peran berhasil.

Pecahkan masalah

Anda harus mengidentifikasi dan menggunakan ID objek aplikasi Perusahaan di mana Anda memberikan peran EA. Jika Anda menggunakan ID Objek dari beberapa aplikasi lain, panggilan API gagal. Verifikasi bahwa Anda menggunakan ID objek aplikasi Enterprise yang benar.

Jika Anda menerima kesalahan berikut saat melakukan panggilan API, maka Anda mungkin salah menggunakan nilai ID objek perwakilan layanan yang terletak di Pendaftaran Aplikasi. Untuk mengatasi kesalahan ini, pastikan Anda menggunakan ID objek principal layanan dari Aplikasi Bisnis, bukan Pendaftaran Aplikasi.

The provided principal Tenant Id = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and principal Object Id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx are not valid

Langkah berikutnya

Mulai menggunakan akun penagihan Perjanjian Perusahaan Anda.