Menghost sendiri portal pengembang API Management

Artikel
03/29/2024

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 bawah googleFonts, secara opsional diatur apiKey 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:
1. Buka konsol Google Cloud.
2. Periksa apakah API Pengembang Font Web diaktifkan. Jika tidak, aktifkan.
3. Pilih Buat kunci API kredensial>.
4. Dalam dialog terbuka, salin kunci yang dihasilkan dan tempelkan sebagai nilai apiKey dalam config.design.json file.
5. Pilih Edit kunci API untuk membuka editor kunci.
6. Di editor, di bawah Pembatasan API, pilih Batasi kunci. Di menu dropdown, pilih API Pengembang Font Web.
7. 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 dan managementApiAccessToken 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.

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

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), seperti http://localhost:8080 atau https://localhost:8080
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

Menghost sendiri portal pengembang API Management

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 untuk akun penyimpanan

Mengonfigurasi pengaturan CORS untuk backend portal pengembang

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

Langkah berikutnya

Sumber Daya Tambahan: