Menghost sendiri portal pengembang API Management

Artikel
05/06/2022
9 menit untuk membaca

Tutorial ini menjelaskan cara menghost sendiri portal pengembang API Management. Dengan menghost sendiri akan memberi Anda fleksibilitas untuk memperluas portal pengembang dengan logika kustom dan widget yang secara dinamis menyesuaikan halaman pada runtime. Anda dapat menghost sendiri beberapa portal untuk instans API Management Anda, dengan fitur yang berbeda. Ketika Anda menghost portal sendiri, Anda menjadi pengelola portal tersebut dan Anda bertanggung jawab atas peningkatannya.

Langkah-langkah berikut menunjukkan cara menyiapkan lingkungan pengembangan lokal Anda, melakukan perubahan di portal pengembang, dan menerbitkan serta menyebarkannya ke akun penyimpanan Azure.

Jika Anda telah mengunggah atau memodifikasi file media di portal terkelola, lihat Berpindah dari dikelola ke yang dihost sendiri, nanti di artikel ini.

Ketersediaan

Penting

Fitur ini tersedia di tingkat Premium, Standar, Dasar, dan Pengembang API Management.

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 Buat 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
}

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, lihat Mengaktifkan CAPTCHA.

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 dan managementApiAccessToken dari file konfigurasi sebelumnya.
Jika Anda ingin mengaktifkan CAPTCHA di portal pengembang Anda, lihat Mengaktifkan CAPTCHA.

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

Mengonfigurasi pengaturan Berbagi Sumber Daya Lintas Asal (CORS):

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 diperbolehkan *

Metode yang diperbolehkan Pilih semua kata kerja HTTP.

Header yang diizinkan *

Header yang diekspos *

Usia maks 0
Pilih Simpan.

Aturan	Nilai
Asal yang diperbolehkan	*
Metode yang diperbolehkan	Pilih semua kata kerja HTTP.
Header yang diizinkan	*
Header yang diekspos	*
Usia maks	0

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 akan memicu pembangunan kembali dan melakukan refresh di 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.

Aktifkan CAPTCHA

Saat menyiapkan portal yang dihost sendiri, Anda mungkin telah menonaktifkan CAPTCHA melalui pengaturan useHipCaptcha. Komunikasi dengan CAPTCHA terjadi melalui titik akhir, yang memungkinkan Berbagi Sumber Daya Lintas Asal (CORS) hanya terjadi untuk nama host portal pengembang terkelola. Jika portal pengembang Anda dihost sendiri, portal ini menggunakan nama host yang berbeda dan CAPTCHA tidak akan mengizinkan komunikasi.

Memperbarui file konfigurasi JSON

Untuk mengaktifkan CAPTCHA di portal yang dihost sendiri:

Tetapkan domain kustom (misalnya, api.contoso.com) ke titik akhir Portal pengembang layanan API Management Anda.

Domain ini berlaku untuk versi terkelola portal Anda dan titik akhir CAPTCHA. Untuk langkah-langkahnya, lihat Mengonfigurasi nama domain kustom untuk instans Azure API Management Anda.
Buka folder src di lingkungan lokal untuk portal yang dihost sendiri.

Perbarui file json konfigurasi:

File	Nilai baru	Catatan
`config.design.json`	`"backendUrl": "https://<custom-domain>"`	Ganti `<custom-domain>` dengan domain kustom yang Anda siapkan di langkah pertama.
	`"useHipCaptcha": true`	Ubah nilai menjadi `true`
`config.publish.json`	`"backendUrl": "https://<custom-domain>"`	Ganti `<custom-domain>` dengan domain kustom yang Anda siapkan di langkah pertama.
	`"useHipCaptcha": true`	Ubah nilai menjadi `true`
`config.runtime.json`	`"backendUrl": "https://<custom-domain>"`	Ganti `<custom-domain>` dengan domain kustom yang Anda siapkan di langkah pertama.

Menerbitkan portal.
Unggah dan host portal yang baru dipublikasikan.
Mengekspos portal yang dihost sendiri melalui domain kustom.

Tingkat pertama dan kedua domain portal harus cocok dengan domain yang disiapkan di langkah pertama. Contohnya:portal.contoso.com Langkah-langkah yang tepat tergantung pada platform pilihan hosting Anda. Jika Anda menggunakan akun penyimpanan Azure, Anda bisa merujuk ke Petakan domain kustom ke titik akhir Azure Blob Storage untuk mendapatkan instruksi.

Langkah berikutnya

Pelajari tentang Pendekatan alternatif untuk host mandiri

Menghost sendiri portal pengembang API Management

Apakah halaman ini membantu?

Ketersediaan

Prasyarat

Langkah 1: Menyiapkan lingkungan lokal

Langkah 2: Mengonfigurasi file JSON, situs web statik, dan pengaturan CORS

File config.design.json

File config.publish.json

File config.runtime.json

Mengonfigurasi situs web statik

Mengonfigurasi pengaturan CORS

Langkah 3: Jalankan portal

Langkah 4: Mengedit melalui editor visual

Langkah 5: Terbitkan secara lokal

Langkah 6: Unggah file statik ke blob

Langkah 7: Buka situs web Anda

Langkah 8: Mengubah templat pemberitahuan API Management

Konfirmasi perubahan email

Konfirmasi akun pengembang baru

Mengundang pengguna

Langganan baru diaktifkan

Konfirmasi perubahan kata sandi

Semua templat

Berpindah dari portal pengembang yang dikelola ke portal yang dihost sendiri

Proses transisi

Aktifkan CAPTCHA

Memperbarui file konfigurasi JSON

Langkah berikutnya