Menghost sendiri portal pengembang API Management
BERLAKU UNTUK: Pengembang | Dasar | Standar | Premium
Tutorial ini menjelaskan cara menghost sendiri portal pengembang API Management. Hosting mandiri adalah salah satu dari beberapa opsi untuk memperluas fungsionalitas portal pengembang. Misalnya, Anda dapat menghosting sendiri beberapa portal untuk instans API Management Anda, dengan fitur yang berbeda. Ketika Anda menghost sendiri sebuah portal, Anda menjadi pengelola portal tersebut dan Anda bertanggung jawab atas peningkatannya.
Penting
Pertimbangkan untuk menghosting sendiri portal pengembang hanya ketika Anda perlu memodifikasi inti basis kode portal pengembang. Opsi ini memerlukan konfigurasi tingkat lanjut, termasuk:
- Penyebaran ke platform hosting, secara opsional dihadapkan pada solusi seperti CDN untuk peningkatan ketersediaan dan performa
- Memelihara dan mengelola infrastruktur hosting
- Pembaruan manual, termasuk untuk patch keamanan, yang mungkin mengharuskan Anda untuk mengatasi konflik kode saat meningkatkan basis kode
Catatan
Portal yang dihost sendiri tidak mendukung visibilitas dan kontrol akses yang tersedia di portal pengembang terkelola.
Jika Anda telah mengunggah atau memodifikasi file media di portal terkelola, lihat Berpindah dari dikelola ke yang dihost sendiri, nanti di artikel ini.
Prasyarat
Untuk menyiapkan lingkungan pengembangan lokal, Anda harus memiliki:
- Sebuah instans layanan API Management. Jika Anda tidak memilikinya, lihat Mulai Cepat - Membuat instans API Management Azure.
- Sebuah akun penyimpanan Azure dengan fitur situs web statik akan diaktifkan. Lihat Membuat akun penyimpanan.
- Git pada mesin Anda. Instal dengan mengikuti tutorial Git ini.
- Node.js (versi LTS,
v10.15.0
atau yang lebih baru) dan npm pada mesin Anda. Lihat Mengunduh dan menginstal Node.js dan npm. - Azure CLI. Ikuti langkah-langkah penginstalan Azure CLI.
Langkah 1: Menyiapkan lingkungan lokal
Untuk mengatur lingkungan lokal, Anda harus mengkloning repositori, beralih ke rilis terbaru portal pengembang, dan menginstal paket npm.
Kloning repo api-management-developer-portal dari GitHub:
git clone https://github.com/Azure/api-management-developer-portal.git
Buka salinan repo lokal Anda:
cd api-management-developer-portal
Lihat rilis terbaru dari portal.
Sebelum Anda menjalankan kode berikut, periksa tag rilis saat ini di bagian Rilis repositori dan ganti nilai
<current-release-tag>
dengan tag rilis terbaru.git checkout <current-release-tag>
Instal paket npm yang tersedia:
npm install
Tip
Selalu gunakan rilis portal terbaru dan selalu pertahankan portal bercabang Anda tetap terbarui. Insinyur Perangkat Lunak menggunakan cabang master
dari repositori ini untuk tujuan pengembangan sehari-hari. Ini memiliki versi perangkat lunak yang tidak stabil.
Langkah 2: Mengonfigurasi file JSON, situs web statik, dan pengaturan CORS
Portal pengembang memerlukan API Management REST API untuk mengelola konten.
File config.design.json
Masuk ke folder src
dan buka file config.design.json
.
{
"environment": "development",
"managementApiUrl": "https://<service-name>.management.azure-api.net",
"managementApiAccessToken": "SharedAccessSignature ...",
"backendUrl": "https://<service-name>.developer.azure-api.net",
"useHipCaptcha": false,
"integration": {
"googleFonts": {
"apiKey": "..."
}
}
}
Mengonfigurasi file:
Dalam nilai
managementApiUrl
, ganti<service-name>
dengan nama instans API Management Anda. Jika Anda mengonfigurasi sebuah domain kustom, gunakan sebagai gantinya (misalnya,https://management.contoso.com
).{ ... "managementApiUrl": "https://contoso-api.management.azure-api.net" ...
Buat token SAS secara manual untuk mengaktifkan akses REST API langsung ke instans API Management Anda.
Salin token yang dihasilkan dan tempelkan sebagai nilai
managementApiAccessToken
.Dalam nilai
backendUrl
, ganti<service-name>
dengan nama instans API Management Anda. Jika Anda mengonfigurasi sebuah domain kustom, gunakan sebagai gantinya (misalnya,https://portal.contoso.com
).{ ... "backendUrl": "https://contoso-api.developer.azure-api.net" ...
Jika Anda ingin mengaktifkan CAPTCHA di portal pengembang Anda, atur
"useHipCaptcha": true
. Pastikan untuk mengonfigurasi pengaturan CORS untuk backend portal pengembang.Di
integration
, di bawahgoogleFonts
, secara opsional diaturapiKey
ke kunci Google API yang memungkinkan akses ke API Pengembang Font Web. Kunci ini hanya diperlukan jika Anda ingin menambahkan font Google di bagian Gaya editor portal pengembang.Jika belum memiliki kunci, Anda dapat mengonfigurasinya menggunakan konsol Google Cloud. Ikuti langkah-langkah ini:
- Buka konsol Google Cloud.
- Periksa apakah API Pengembang Font Web diaktifkan. Jika tidak, aktifkan.
- Pilih Buat kunci API kredensial>.
- Dalam dialog terbuka, salin kunci yang dihasilkan dan tempelkan sebagai nilai
apiKey
dalamconfig.design.json
file. - Pilih Edit kunci API untuk membuka editor kunci.
- Di editor, di bawah Pembatasan API, pilih Batasi kunci. Di menu dropdown, pilih API Pengembang Font Web.
- Pilih Simpan.
File config.publish.json
Masuk ke folder src
dan buka file config.publish.json
.
{
"environment": "publishing",
"managementApiUrl": "https://<service-name>.management.azure-api.net",
"managementApiAccessToken": "SharedAccessSignature...",
"useHipCaptcha": false
}
Mengonfigurasi file:
Salin dan tempel nilai
managementApiUrl
danmanagementApiAccessToken
dari file konfigurasi sebelumnya.Jika Anda ingin mengaktifkan CAPTCHA di portal pengembang Anda, atur
"useHipCaptcha": true
. Pastikan untuk mengonfigurasi pengaturan CORS untuk backend portal pengembang.
File config.runtime.json
Masuk ke folder src
dan buka file config.runtime.json
.
{
"environment": "runtime",
"managementApiUrl": "https://<service-name>.management.azure-api.net",
"backendUrl": "https://<service-name>.developer.azure-api.net"
}
Mengonfigurasi file:
Salin dan tempel nilai
managementApiUrl
dari file konfigurasi sebelumnya.Dalam nilai
backendUrl
, ganti<service-name>
dengan nama instans API Management Anda. Jika Anda mengonfigurasi domain kustom, gunakan domain tersebut sebagai gantinya (misalnya,https://portal.contoso.com
).{ ... "backendUrl": "https://contoso-api.developer.azure-api.net" ...
Mengonfigurasi situs web statik
Konfigurasikan fitur Situs web statik di akun penyimpanan Anda dengan menyediakan rute ke halaman indeks dan kesalahan:
Buka akun penyimpanan Anda di portal Microsoft Azure dan pilih Situs web statik dari menu di sebelah kiri.
Pada halaman Situs web statik, pilih Diaktifkan.
Di bidang Nama dokumen indeks, masukkan index.html.
Di bidang Jalur dokumen kesalahan, masukkan 404/index.html.
Pilih Simpan.
Mengonfigurasi pengaturan CORS untuk akun penyimpanan
Konfigurasikan pengaturan Berbagi Sumber Daya Lintas Asal (CORS) untuk akun penyimpanan:
Buka akun penyimpanan Anda di portal Microsoft Azure dan pilih CORS dari menu di sebelah kiri.
Di tab Blob service, konfigurasikan aturan berikut:
Aturan Nilai Asal yang dibolehkan * Metode yang dibolehkan Pilih semua kata kerja HTTP. Header yang dibolehkan * Header yang diekspos * Usia maks 0 Pilih Simpan.
Mengonfigurasi pengaturan CORS untuk backend portal pengembang
Konfigurasikan pengaturan CORS untuk backend portal pengembang guna mengizinkan permintaan yang berasal dari portal pengembang yang dihost sendiri. Portal pengembang yang dihost sendiri bergantung pada titik akhir backend portal pengembang (diatur dalam backendUrl
di file konfigurasi portal) untuk mengaktifkan beberapa fitur, termasuk:
- Verifikasi CAPTCHA
- Otorisasi OAuth 2.0 dalam konsol pengujian
- Delegasi autentikasi pengguna dan langganan produk
Untuk menambahkan pengaturan CORS:
- Buka instans API Management Anda di portal Azure dan pilih Portal pengembang>Pengaturan portal dari menu di sebelah kiri.
- Pada tab Konfigurasi portal yang dihost sendiri, tambahkan satu atau beberapa nilai domain Asal. Misalnya:
- Domain tempat portal yang dihost sendiri dihosting, seperti
https://www.contoso.com
localhost
untuk pengembangan lokal (jika ada), sepertihttp://localhost:8080
atauhttps://localhost:8080
- Domain tempat portal yang dihost sendiri dihosting, seperti
- Pilih Simpan.
Langkah 3: Jalankan portal
Sekarang Anda dapat membangun dan menjalankan instans portal lokal dalam mode pengembangan. Di mode pengembangan, semua pengoptimalan dimatikan dan peta sumber diaktifkan.
Jalankan perintah berikut:
npm start
Setelah beberapa saat, browser default secara otomatis terbuka dengan instans portal pengembang lokal Anda. Alamat defaultnya adalah http://localhost:8080
, tetapi port dapat berubah jika 8080
sudah ditempati. Setiap perubahan pada basis kode proyek memicu pembangunan kembali dan merefresh jendela browser Anda.
Langkah 4: Mengedit melalui editor visual
Gunakan editor visual untuk melaksanakan tugas-tugas ini:
- Mengustomisasi portal Anda
- Konten penulis
- Mengatur struktur situs web
- Bergayakan penampilannya
Lihat Tutorial: Mengakses dan menyesuaikan portal pengembang. Ini mencakup dasar-dasar antarmuka pengguna administratif dan daftar perubahan yang direkomendasikan pada konten default. Simpan semua perubahan di lingkungan lokal, lalu tekan Ctrl+C untuk menutupnya.
Langkah 5: Terbitkan secara lokal
Data portal berasal dari bentuk objek yang berjenis kuat. Perintah berikut menerjemahkannya ke dalam file statik dan menempatkan output dalam direktori ./dist/website
:
npm run publish
Langkah 6: Unggah file statik ke blob
Gunakan Azure CLI untuk mengunggah file statik yang dihasilkan secara lokal ke blob, dan pastikan pengunjung Anda bisa mendapatkannya:
Buka Prompt Perintah Windows, PowerShell, atau shell perintah lainnya.
Jalankan perintah Azure CLI berikut ini.
Ganti
<account-connection-string>
dengan string koneksi dari akun penyimpanan Anda. Anda bisa mendapatkannya dari bagian Kunci akses di akun penyimpanan Anda.az storage blob upload-batch --source dist/website \ --destination '$web' \ --connection-string <account-connection-string>
Langkah 7: Buka situs web Anda
Situs web Anda sekarang aktif di bawah nama host yang ditentukan di properti Azure Storage Anda (Titik akhir utama di Situs web statik).
Langkah 8: Mengubah templat pemberitahuan API Management
Ganti URL portal pengembang di templat pemberitahuan API Management untuk mengarahkan ke portal yang dihost sendiri milik Anda. Lihat Cara mengonfigurasi pemberitahuan dan templat surel di Azure API Management.
Secara khusus, lakukan perubahan berikut ini pada templat default:
Catatan
Nilai di bagian Diperbarui berikut mengasumsikan bahwa Anda menghost portal di https://portal.contoso.com/.
Konfirmasi perubahan email
Perbarui URL portal pengembang di templat pemberitahuan Konfirmasi perubahan email:
Konten asli
<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
<strong>$ConfirmUrl</strong></a>
Diperbarui
<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
<strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>
Konfirmasi akun pengembang baru
Perbarui URL portal pengembang di templat pemberitahuan Konfirmasi akun pengembang baru:
Konten asli
<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
<strong>$ConfirmUrl</strong></a>
Diperbarui
<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
<strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>
Mengundang pengguna
Perbarui URL portal pengembang di templat pemberitahuan Mengundang pengguna:
Konten asli
<a href="$ConfirmUrl">$ConfirmUrl</a>
Diperbarui
<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>
Langganan baru diaktifkan
Perbarui URL portal pengembang di templat pemberitahuan Langganan baru diaktifkan:
Konten asli
Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!
Diperbarui
Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!
Konten asli
Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys
Diperbarui
Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys
Konten asli
<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>
Diperbarui
<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>
Konten asli
<p style="font-size:12pt;font-family:'Segoe UI'">
<strong>
<a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
</strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
<strong>
<a href="http://$DevPortalUrl/issues">Stay in touch</a>
</strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>
Diperbarui
<!--Remove the entire block of HTML code above.-->
Konfirmasi perubahan kata sandi
Perbarui URL portal pengembang di templat pemberitahuan Konfirmasi perubahan kata sandi:
Konten asli
<a href="$DevPortalUrl">$DevPortalUrl</a>
Diperbarui
<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>
Semua templat
Perbarui URL portal pengembang di templat mana pun yang memiliki link di footer:
Konten asli
<a href="$DevPortalUrl">$DevPortalUrl</a>
Diperbarui
<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>
Berpindah dari portal pengembang yang dikelola ke portal yang dihost sendiri
Seiring waktu, persyaratan bisnis Anda mungkin berubah. Anda dapat berakhir dalam situasi di mana versi terkelola portal pengembang API Management tidak lagi memenuhi kebutuhan Anda. Misalnya, persyaratan baru dapat memaksa Anda untuk membuat widget khusus yang terintegrasi dengan penyedia data pihak ketiga. Tidak seperti versi terkelola, versi portal yang dihost sendiri menawarkan fleksibilitas dan ekstensibilitas penuh.
Proses transisi
Anda dapat beralih dari versi terkelola ke versi yang dihost sendiri dalam instans layanan API Management yang sama. Proses ini mempertahankan modifikasi yang telah Anda lakukan di versi portal yang terkelola. Pastikan Anda mencadangkan konten portal sebelumnya. Anda dapat menemukan skrip cadangan di folder scripts
pada portal pengembang API Management GitHub repo.
Proses konversi hampir identik dengan menyiapkan portal yang dihost sendiri generik, seperti yang ditunjukkan pada langkah-langkah sebelumnya dalam artikel ini. Ada satu pengecualian di dalam langkah konfigurasi. Akun penyimpanan di file config.design.json
harus sama dengan akun penyimpanan versi portal yang terkelola. Lihat Tutorial: Menggunakan identitas yang ditetapkan sistem Linux VM untuk mengakses Azure Storage melalui kredensial SAS untuk mendapatkan petunjuk tentang cara mengambil URL SAS.
Tip
Kami merekomendasikan menggunakan akun penyimpanan terpisah di file config.publish.json
. Pendekatan ini memberi Anda lebih banyak kontrol dan menyederhanakan manajemen layanan hosting untuk portal Anda.
Langkah berikutnya
- Pelajari tentang Pendekatan alternatif untuk host mandiri