Share via

Menghost sendiri portal API Center Anda

  • Artikel

Artikel ini memperkenalkan portal API Center, situs web yang dapat digunakan pengembang dan pemangku kepentingan lainnya di organisasi Anda untuk menemukan API di pusat API Anda. Sebarkan implementasi referensi portal dari repositori pemula portal API Center.

Cuplikan layar portal API Center setelah pengguna masuk.

Tentang portal API Center

Portal API Center adalah situs web yang dapat Anda bangun dan host untuk menampilkan inventaris API di pusat API Anda. Portal memungkinkan pengembang dan pemangku kepentingan lain di organisasi Anda untuk menemukan API dan melihat detail API.

Anda dapat membangun dan menyebarkan implementasi referensi portal menggunakan kode di repositori pemula portal API Center. Portal menggunakan API sarana data Azure API Center untuk mengambil data dari pusat API Anda. Akses pengguna ke informasi API didasarkan pada kontrol akses berbasis peran Azure.

Implementasi referensi portal API Center menyediakan:

  • Kerangka kerja untuk menerbitkan dan memelihara portal API yang dikelola pelanggan menggunakan GitHub Actions
  • Platform portal yang dapat dimodifikasi atau diperluas pelanggan untuk memenuhi kebutuhan mereka
  • Fleksibilitas untuk dihosting pada infrastruktur yang berbeda, termasuk penyebaran ke layanan seperti Azure Static Web Apps.

Prasyarat

  • Pusat API di langganan Azure Anda. Jika Anda belum membuatnya, lihat Mulai Cepat: Membuat pusat API Anda.

  • Izin untuk membuat pendaftaran aplikasi di penyewa Microsoft Entra yang terkait dengan langganan Azure Anda, dan izin untuk memberikan akses ke data di pusat API Anda.

  • Untuk membangun dan menyebarkan portal, Anda memerlukan akun GitHub dan alat berikut yang diinstal di komputer lokal Anda:

Membuat pendaftaran aplikasi Microsoft Entra

Pertama-tama konfigurasikan pendaftaran aplikasi di penyewa MICROSOFT Entra ID Anda. Pendaftaran aplikasi memungkinkan portal API Center mengakses data dari pusat API Anda atas nama pengguna yang masuk.

  1. Di portal Azure, navigasikan ke ID> Microsoft Entra Pendaftaran aplikasi.

  2. Pilih + Pendaftaran baru.

  3. Pada halaman Daftarkan aplikasi, atur nilai sebagai berikut:

    • Atur Nama ke nama yang bermakna seperti api-center-portal

    • Di bawah Jenis akun yang didukung, pilih Akun di direktori organisasi ini (Penyewa tunggal).

    • Di URI Pengalihan, pilih Aplikasi halaman tunggal (SPA) dan atur URI.

      • Untuk pengujian lokal, atur URI ke https://localhost:5173.
      • Untuk produksi, atur URI ke URI penyebaran portal API Center Anda.

    • Pilih Daftarkan.

  4. Pada halaman Gambaran Umum, salin ID Aplikasi (klien) dan ID Direktori (penyewa). Anda mengatur nilai-nilai ini saat membuat portal.

  5. Pada halaman izin API, pilih + Tambahkan izin.

    1. Pada halaman Minta izin API, pilih tab API yang digunakan organisasi saya. Cari dan pilih Azure API Center. Anda juga dapat mencari dan memilih ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573aplikasi .
    2. Pada halaman Minta izin , pilih user_impersonation.
    3. Pilih Tambahkan izin.

    Izin Azure API Center muncul di bawah Izin yang dikonfigurasi.

    Cuplikan layar izin yang diperlukan di pendaftaran aplikasi ID Microsoft Entra di portal.

Mengonfigurasi lingkungan lokal

Ikuti langkah-langkah ini untuk membangun dan menguji portal API Center secara lokal.

  1. Kloning repositori pemula portal API Center ke komputer lokal Anda.

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. Ubah ke direktori APICenter-Portal-Starter.

    cd APICenter-Portal-Starter

  3. Periksa cabang utama.

    git checkout main

  4. Untuk mengonfigurasi layanan, salin atau ganti nama file menjadi public/config.examplepublic/config.json.

  5. Kemudian edit public/config.json file untuk menunjuk ke layanan Anda. Perbarui nilai dalam file sebagai berikut:

    • Ganti <service name> dan <region> dengan nama pusat API Anda dan wilayah tempatnya disebarkan
    • Ganti <client ID> dan <tenant ID> dengan ID Aplikasi (klien) dan ID Direktori (penyewa) dari pendaftaran aplikasi yang Anda buat di bagian sebelumnya.
    • Perbarui nilai title ke nama yang ingin Anda munculkan di portal.
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. Pasang paket yang diperlukan.

    npm install

  7. Mulai server pengembangan. Perintah berikut akan memulai portal dalam mode pengembangan yang berjalan secara lokal:

    npm start

    Telusuri ke portal di https://localhost:5173.

Sebarkan ke Azure

Untuk langkah-langkah untuk menyebarkan portal ke Azure Static Web Apps, lihat repositori pemula portal API Center.

Mengaktifkan masuk ke portal oleh pengguna dan grup Microsoft Entra

Pengguna harus masuk untuk melihat API di pusat API Anda. Untuk mengaktifkan masuk, tetapkan peran Pembaca Data Azure API Center kepada pengguna atau grup di organisasi Anda, yang tercakup ke pusat API Anda.

Penting

Secara default, Anda dan administrator pusat API lainnya tidak memiliki akses ke API di portal API Center. Pastikan untuk menetapkan peran Pembaca Data Azure API Center untuk diri Anda sendiri dan administrator lainnya.

Untuk prasyarat dan langkah-langkah terperinci untuk menetapkan peran kepada pengguna dan grup, lihat Menetapkan peran Azure menggunakan portal Azure. Langkah-langkah singkat berikut:

  1. Di portal Azure, navigasikan ke pusat API Anda.
  2. Di menu sebelah kiri, pilih Kontrol akses (IAM)>+ Tambahkan penetapan peran.
  3. Di panel Tambahkan penetapan peran, atur nilai sebagai berikut:
    • Pada halaman Peran , cari dan pilih Pembaca Data Azure API Center. Pilih Selanjutnya.
    • Pada halaman Anggota, Di Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan> layanan+ Pilih anggota.
    • Pada halaman Pilih anggota , cari dan pilih pengguna atau grup untuk menetapkan peran. Klik Pilih lalu Berikutnya.
    • Tinjau penetapan peran, dan pilih Tinjau + tetapkan.

Catatan

Untuk menyederhanakan konfigurasi akses bagi pengguna baru, kami sarankan Anda menetapkan peran ke grup Microsoft Entra dan mengonfigurasi aturan keanggotaan grup dinamis. Untuk mempelajari selengkapnya, lihat Membuat atau memperbarui grup dinamis di ID Microsoft Entra.

Setelah Anda mengonfigurasi akses ke portal, pengguna yang dikonfigurasi dapat masuk ke portal dan melihat API di pusat API Anda.

Catatan

Pengguna pertama yang masuk ke portal diminta untuk menyetujui izin yang diminta oleh pendaftaran aplikasi portal API Center. Setelah itu, pengguna lain yang dikonfigurasi tidak diminta untuk menyetujui.

Pemecahan Masalah

Kesalahan: "Anda tidak berwenang untuk mengakses portal ini"

Dalam kondisi tertentu, pengguna mungkin mengalami pesan kesalahan berikut setelah masuk ke portal API Center dengan akun pengguna yang dikonfigurasi:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Pertama, konfirmasikan bahwa pengguna diberi peran Azure API Center Data Reader di pusat API Anda.

Jika pengguna diberi peran, mungkin ada masalah dengan pendaftaran penyedia sumber daya Microsoft.ApiCenter dalam langganan Anda, dan Anda mungkin perlu mendaftarkan ulang penyedia sumber daya. Untuk melakukan ini, jalankan perintah berikut di Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Tidak dapat masuk ke portal

Jika pengguna yang telah diberi peran Pembaca Data Azure API Center tidak dapat menyelesaikan alur masuk setelah memilih Masuk di portal API Center, mungkin ada masalah dengan konfigurasi idP ID Microsoft Entra.

Dalam pendaftaran aplikasi Microsoft Entra, tinjau dan, jika diperlukan, perbarui pengaturan URI Pengalihan untuk memastikan bahwa URI cocok dengan URI penyebaran portal API Center.

Tidak dapat memilih izin Azure API Center di pendaftaran aplikasi Microsoft Entra

Jika Anda tidak dapat meminta izin API ke Azure API Center di pendaftaran aplikasi Microsoft Entra untuk portal API Center, periksa apakah Anda mencari Azure API Center (atau ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573aplikasi ).

Jika aplikasi tidak ada, mungkin ada masalah dengan pendaftaran penyedia sumber daya Microsoft.ApiCenter di langganan Anda. Anda mungkin perlu mendaftarkan ulang penyedia sumber daya. Untuk melakukan ini, jalankan perintah berikut di Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Setelah mendaftarkan ulang penyedia sumber daya, coba lagi untuk meminta izin API.

Kebijakan dukungan

Berikan umpan balik, fitur permintaan, dan dapatkan dukungan untuk implementasi referensi portal API Center di repositori pemula portal API Center.

Konten terkait