Portal pengembang API Management - pertanyaan yang sering diajukan

Bagaimana jika saya membutuhkan fungsionalitas yang tidak didukung di portal?

Anda memiliki opsi berikut:

Pelajari selengkapnya tentang ekstensibilitas portal pengembang.

Dapatkah saya memiliki beberapa portal pengembang dalam satu layanan API Management?

Anda dapat memiliki satu portal terkelola dan beberapa portal yang dihost sendiri. Konten semua portal disimpan dalam layanan API Management yang sama, sehingga akan identik. Jika Anda ingin membedakan tampilan dan fungsionalitas portal, Anda dapat menghost sendiri dengan widget kustom Anda sendiri yang secara dinamis menyesuaikan halaman saat runtime, misalnya berdasarkan URL.

Apakah portal mendukung templat Azure Resource Manager dan/atau kompatibel dengan API Management DevOps Resource Kit?

Nomor.

Apakah konten portal disimpan dengan fungsi pencadangan/pemulihan di API Management?

Nomor.

Apakah saya perlu mengaktifkan konektivitas VNet tambahan untuk dependensi portal terkelola?

Dalam kebanyakan kasus - tidak perlu.

Jika layanan API Management Anda berada di VNet internal, portal pengembang Anda hanya dapat diakses dari dalam jaringan. Nama host titik akhir manajemen harus diselesaikan ke VIP internal layanan dari mesin yang Anda gunakan untuk mengakses antarmuka administratif portal. Pastikan titik akhir manajemen terdaftar di DNS. Jika terjadi kesalahan konfigurasi, Anda akan melihat kesalahan: Unable to start the portal. See if settings are specified correctly in the configuration (...).

Jika layanan API Management Anda berada di VNet internal dan Anda mengaksesnya melalui Application Gateway dari internet, pastikan untuk mengaktifkan konektivitas ke portal pengembang dan titik akhir manajemen API Management. Anda mungkin perlu menonaktifkan aturan Firewall Aplikasi Web. Lihat artikel dokumentasi ini untuk detail lebih lanjut.

Saya menetapkan domain API Management kustom dan portal yang dipublikasikan tidak berfungsi

Setelah memperbarui domain, Anda perlu menerbitkan ulang portal agar perubahan diterapkan.

Saya telah menambahkan penyedia identitas dan saya tidak bisa melihatnya di portal

Setelah mengonfigurasi penyedia identitas (misalnya, Azure AD, Azure AD B2C), Anda perlu menerbitkan ulang portal agar perubahan diterapkan. Pastikan halaman portal pengembang Anda menyertakan widget tombol OAuth.

Saya menyiapkan delegasi dan portal tidak menggunakannya

Setelah menyiapkan delegasi, Anda perlu menerbitkan ulang portal agar perubahan diterapkan.

Perubahan konfigurasi API Management saya yang lain belum disebarluaskan di portal pengembang

Sebagian besar perubahan konfigurasi (misalnya, VNet, rincian masuk, istilah produk) mengharuskan penerbitan ulang portal.

Saya mendapatkan kesalahan CORS saat menggunakan konsol interaktif

Konsol interaktif membuat permintaan API pihak klien dari browser. Atasi masalah CORS dengan menambahkan kebijakan CORS pada API Anda.

Anda dapat memeriksa status kebijakan CORS di bagian Gambaran umum portal dari layanan API Management Anda di portal Microsoft Azure. Kotak peringatan menunjukkan kebijakan yang tidak ada atau salah dikonfigurasi.

Catatan

Hanya satu kebijakan CORS yang dijalankan. Jika Anda menentukan beberapa kebijakan CORS (misalnya, pada level API dan pada level semua API), konsol interaktif Anda mungkin tidak berfungsi seperti yang diharapkan.

Screenshot that shows where you can check the status of your CORS policy.

Terapkan kebijakan CORS secara otomatis dengan mengeklik tombol Aktifkan CORS.

Anda juga dapat mengaktifkan CORS secara manual.

  1. Pilih tautan Terapkan secara manual di tingkat global untuk melihat kode kebijakan yang dihasilkan.
  2. Navigasikan ke Semua API di bagian API di layanan API Management Anda di portal Microsoft Azure.
  3. Pilih ikon </> di bagian Pemrosesan masuk.
  4. Sisipkan kebijakan di bagian <masuk> dari file XML. Pastikan nilai <asal> cocok dengan domain portal pengembang Anda.

Catatan

Jika Anda menerapkan kebijakan CORS di lingkup Produk, bukan cakupan API, dan API Anda menggunakan autentikasi kunci langganan melalui header, konsol Anda tidak akan berfungsi.

Browser secara otomatis mengeluarkan sebuah permintaan HTTP OPTIONS, yang tidak berisi header dengan kunci langganan. Karena kunci langganan tidak ada, API Management tidak dapat mengaitkan panggilan OPTIONS dengan Produk, sehingga tidak dapat menerapkan kebijakan CORS.

Sebagai solusinya, Anda bisa meneruskan kunci langganan dalam parameter kueri.

Apa itu fitur proksi CORS dan kapan saya harus menggunakannya?

Pilih opsi Gunakan proksi CORS dalam konfigurasi widget detail operasi API untuk merutekan panggilan API konsol interaktif melalui backend portal di layanan API Management Anda. Dalam konfigurasi ini, Anda tidak perlu lagi menerapkan kebijakan CORS untuk API Anda, dan konektivitas ke titik akhir gateway dari komputer lokal tidak diperlukan. Jika API diekspos melalui gateway yang dihost sendiri atau layanan Anda berada dalam jaringan virtual, konektivitas dari layanan backend API Management ke gateway diperlukan. Jika Anda menggunakan portal yang dihost sendiri, tentukan titik akhir backend portal menggunakan opsi backendUrl di dalam file konfigurasi. Jika tidak, portal yang dihost sendiri tidak akan mengetahui lokasi layanan backend.

Izin apa yang saya perlukan untuk mengedit portal pengembang?

Jika Anda melihat kesalahan Oops. Something went wrong. Please try again later. saat membuka portal dalam mode administratif, Anda mungkin tidak memiliki izin yang diperlukan (Azure RBAC).

Portal warisan memerlukan izin Microsoft.ApiManagement/service/getssotoken/action di lingkup layanan (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) untuk memungkinkan akses administrator pengguna ke portal. Portal baru memerlukan izin Microsoft.ApiManagement/service/users/token/action di lingkup /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.

Anda bisa menggunakan skrip PowerShell berikut ini untuk membuat peran dengan izin yang diperlukan. Pastikan untuk mengganti parameter <subscription-id>.

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
New-AzRoleDefinition -Role $customRole 

Setelah peran dibuat, peran tersebut dapat diberikan kepada pengguna mana pun dari bagian Access Control (IAM) di portal Microsoft Azure. Menetapkan peran ini untuk pengguna akan menetapkan izin di lingkup layanan. Pengguna akan dapat menghasilkan token SAS atas nama pengguna mana pun di dalam layanan. Minimal, peran ini perlu ditetapkan kepada administrator layanan. Perintah PowerShell berikut ini menunjukkan cara menetapkan peran kepada pengguna user1 pada lingkup terendah untuk menghindari pemberian izin yang tidak perlu kepada pengguna:

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1" 

Setelah izin diberikan kepada pengguna, pengguna harus keluar dan masuk lagi ke portal Microsoft Azure agar izin baru dapat berlaku.

Saya melihat kesalahan Unable to start the portal. See if settings are specified correctly (...)

Kesalahan ini diperlihatkan ketika panggilan GET ke https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview gagal. Panggilan dikeluarkan dari browser oleh antarmuka administratif portal.

Jika layanan API Management Anda berada di VNet, lihat pertanyaan konektivitas VNet.

Kegagalan panggilan juga dapat disebabkan oleh sertifikat TLS/SSL, yang ditetapkan ke domain kustom dan tidak dipercaya oleh browser. Sebagai mitigasi, Anda dapat menghapus domain kustom titik akhir manajemen. API Management akan kembali ke titik akhir default dengan sertifikat terpercaya.

Apa saja dukungan browser untuk portal?

Browser Didukung
Apple Safari Ya1
Google Chrome Ya1
Microsoft Edge Ya1
Microsoft Internet Explorer Tidak
Mozilla Firefox Ya1

1 Didukung di dua versi produksi terbaru.

Pengembangan lokal dari portal yang dihost sendiri tidak lagi berjalan

Jika versi lokal portal pengembang Anda tidak dapat menyimpan atau mengambil informasi dari akun penyimpanan atau instans API Management, token SAS mungkin telah kedaluwarsa. Anda dapat memperbaikinya dengan membuat token baru. Untuk panduan, lihat tutorial untuk menghost sendiri portal pengembang.

Bagaimana cara menonaktifkan pendaftaran di portal pengembang?

Jika Anda tidak memerlukan fungsi pendaftaran yang diaktifkan secara default di portal pengembang, Anda dapat menonaktifkannya dengan langkah-langkah ini:

  1. Di portal Microsoft Azure, navigasikan ke instans API Management Anda.

  2. Pada Portal pengembang di menu, pilih Identitas.

  3. Hapus setiap penyedia identitas yang muncul dalam daftar. Pilih setiap penyedia, pilih menu konteks ( ... ), dan pilih Hapus.

    Delete identity providers

  4. Buka antarmuka administratif portal pengembang.

  5. Hapus tautan Daftar dan item navigasi di konten portal. Untuk informasi tentang cara menyesuaikan konten portal, lihat Tutorial: Mengakses dan menyesuaikan portal pengembang.

    Delete navigation item

  6. Ubah konten halaman Daftar untuk menghapus bidang yang digunakan untuk memasukkan data identitas, jika pengguna mengarahkan langsung ke sana.

    Secara opsional, hapus halaman Daftar. Saat ini, Anda menggunakan contentItem REST API untuk mencantumkan dan menghapus halaman ini.

  7. Simpan perubahan Anda, dan terbitkan ulang portal.

Bagaimana cara menghapus konten portal pengembang yang disediakan untuk layanan API Management saya?

Berikan parameter yang diperlukan dalam skrip scripts.v3/cleanup.bat di Repositori GitHub portal pengembang, dan jalankan skrip

cd scripts.v3
.\cleanup.bat
cd ..

Bagaimana cara mengaktifkan autentikasi single sign-on (SSO) ke portal pengembang yang dihost sendiri?

Di antara metode autentikasi lainnya, portal pengembang mendukung single sign-on (SSO). Untuk mengautentikasi dengan metode ini, Anda perlu melakukan panggilan ke /signin-sso dengan token di parameter kueri:

https://contoso.com/signin-sso?token=[user-specific token]

Membuat token pengguna

Anda dapat membuat token khusus pengguna (termasuk token admin) menggunakan operasi Dapatkan Token Akses Bersama dari API Management REST API.

Catatan

Token harus dikodekan dengan URL.

Bagaimana cara menambahkan HTML kustom ke portal pengembang saya?

Portal pengembang terkelola menyertakan widget kode HTML Kustom yang memungkinkan Anda menyisipkan kode HTML untuk kustomisasi portal kecil. Misalnya, gunakan HTML kustom untuk menyematkan video atau untuk menambahkan formulir. Portal merender widget kustom dalam bingkai sebaris (iframe).

  1. Di antarmuka administratif untuk portal pengembang, buka halaman atau bagian tempat Anda ingin menyisipkan widget.

  2. Pilih ikon "plus" (+) berwarna abu-abu yang muncul saat Anda mengarahkan penunjuk ke halaman.

  3. Di jendela Tambahkan widget, pilih Kode HTML kustom.

    Add widget for custom HTML code

  4. Pilih ikon "pensil" untuk menyesuaikan widget.

  5. Masukkan Lebar dan Tinggi (dalam piksel) untuk widget.

  6. Untuk mewarisi gaya dari portal pengembang (disarankan), pilih Terapkan gaya portal pengembang.

    Catatan

    Jika pengaturan ini tidak dipilih, elemen yang disematkan akan menjadi kontrol HTML biasa, tanpa gaya portal pengembang.

    Configure HTML custom code

  7. Ganti contoh kode HTML dengan konten kustom Anda.

  8. Jika konfigurasi selesai, tutup jendela.

  9. Simpan perubahan Anda, dan terbitkan ulang portal.

Catatan

Microsoft tidak mendukung kode HTML yang Anda tambahkan di sidget kode HTML Kustom.

Langkah berikutnya

Pelajari selengkapnya tentang portal pengembang:

Jelajahi sumber daya lainnya: