Bagikan melalui

Memperluas portal pengembang dengan widget kustom

BERLAKU UNTUK: Pengembang | Dasar | Standar | Premi

Portal pengembang API Management memiliki editor visual dan widget bawaan sehingga Anda dapat menyesuaikan dan menata tampilan portal. Namun, Anda mungkin perlu menyesuaikan portal pengembang lebih lanjut dengan fungsionalitas kustom. Misalnya, Anda mungkin ingin mengintegrasikan portal pengembang dengan sistem dukungan yang melibatkan penambahan antarmuka kustom. Artikel ini menjelaskan cara menambahkan fungsionalitas kustom seperti widget kustom ke portal pengembang API Management Anda.

Tabel berikut ini meringkas dua opsi, dengan tautan ke detail selengkapnya.

Metode Deskripsi
Widget kode HTML kustom - Solusi ringan bagi penerbit API guna menambahkan logika kustom untuk kasus penggunaan dasar

- Salin dan tempel kode HTML kustom ke dalam formulir, lalu portal pengembang merendernya dalam iframe
Membuat dan mengunggah widget kustom - Solusi pengembang untuk kasus penggunaan widget yang lebih canggih

- Memerlukan implementasi lokal dalam React, Vue, atau TypeScript biasa

- Perancah widget dan alat yang disediakan untuk membantu pengembang membuat widget dan mengunggah ke portal pengembang

- Pembuatan, pengujian, dan penyebaran widget dapat diskrip melalui sumber terbuka React Component Toolkit

- Mendukung alur kerja untuk kontrol sumber, penerapan versi, dan penggunaan kembali kode

Catatan

Hosting mandiri portal pengembang adalah opsi ekstensibilitas bagi pelanggan yang perlu menyesuaikan kode sumber dari seluruh inti portal. Ini memberikan fleksibilitas lengkap untuk menyesuaikan pengalaman portal, tetapi memerlukan konfigurasi tingkat lanjut. Dengan hosting mandiri, Anda bertanggung jawab untuk mengelola siklus hidup kode lengkap: basis kode fork, pengembangan, penyebaran, host, patch, dan peningkatan.

Tip

Opsi lain untuk menyesuaikan portal pengembang adalah menggunakan plugin portal pengembang sumber terbuka untuk WordPress. Manfaatkan kemampuan situs di WordPress untuk melokalisasi konten, menyesuaikan menu, menerapkan lembar gaya kustom, dan banyak lagi di portal pengembang Anda.

Menggunakan widget kode HTML Kustom

Portal pengembang terkelola menyertakan widget kode HTML Kustom yang memungkinkan Anda menyisipkan kode HTML untuk kustomisasi portal sederhana. Misalnya, Anda dapat menggunakan 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.

    Cuplikan layar yang menunjukkan cara menambahkan widget untuk kode HTML kustom di portal pengembang.

  4. Pilih widget baru, lalu pilih tombol Edit 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.

    Cuplikan layar yang menunjukkan cara mengonfigurasi kode kustom HTML di portal pengembang.

  7. Ganti contoh kode HTML dengan konten kustom Anda.

  8. Jika konfigurasi selesai, tutup jendela.

  9. Pilih tombol Simpan untuk menyimpan perubahan Anda, lalu terbitkan ulang portal.

Catatan

Microsoft tidak mendukung kode HTML yang Anda tambahkan di widget Kode HTML Kustom.

Membuat dan mengunggah widget kustom

Untuk kasus penggunaan yang lebih canggih, Anda dapat membuat dan mengunggah widget kustom ke portal pengembang. API Management menyediakan perancah kode bagi pengembang untuk membuat widget kustom di React, Vue, atau TypeScript biasa. Perancah mencakup alat untuk membantu Anda mengembangkan dan menyebarkan widget Anda ke portal pengembang.

Prasyarat

  • Menginstal runtime Node.js secara lokal
  • Pengetahuan dasar tentang pemrograman dan pengembangan web

Membuat widget

Peringatan

Kode widget kustom Anda disimpan di penyimpanan blob Azure global yang terkait dengan instans API Management Anda. Saat Anda menambahkan widget kustom ke portal pengembang, kode dibaca dari penyimpanan ini melalui titik akhir yang tidak memerlukan autentikasi, meskipun portal pengembang atau halaman dengan widget kustom hanya dapat diakses oleh pengguna yang diautentikasi. Jangan sertakan informasi atau rahasia sensitif dalam kode widget kustom.

  1. Di antarmuka administratif untuk portal pengembang, pilih Widget> kustomTambahkan widget kustom baru.

  2. Masukkan nama widget dan pilih Teknologi. Untuk informasi selengkapnya, lihat Templat widget, nanti di artikel ini.

  3. Pilih Simpan.

  4. Buka terminal, buka lokasi tempat Anda ingin menyimpan kode widget, dan jalankan perintah berikut untuk mengunduh perancah kode:

    npx @azure/api-management-custom-widgets-scaffolder

  5. Buka folder yang baru dibuat yang berisi perancah kode widget.

    cd <name-of-widget>

  6. Buka folder di editor kode pilihan Anda, seperti Visual Studio Code.

  7. Instal dependensi dan mulai proyek:

    npm install 
npm start

    Browser Anda seharusnya membuka tab baru dengan portal pengembang yang terhubung ke widget Anda dalam mode pengembangan.

    Catatan

    Jika tab tidak terbuka, lakukan hal berikut:

    1. Pastikan server pengembangan dimulai dengan memeriksa output di konsol tempat Anda memulai server di langkah sebelumnya. Ini harus menampilkan port tempat server berjalan (misalnya, http://127.0.0.1:3001).
    2. Buka layanan API Management Anda di portal Azure dan buka portal pengembang Anda dengan antarmuka administratif.
    3. Tambahkan /?MS_APIM_CW_localhost_port=3001 ke URL. Ubah nomor port jika server Anda berjalan pada port yang berbeda.

  8. Terapkan kode widget dan uji secara lokal. Kode widget terletak di folder src, di subfolder berikut:

    • app - Kode untuk komponen widget yang dilihat dan berinteraksi dengan pengunjung portal pengembang yang diterbitkan
    • editor - Kode untuk komponen widget yang Anda gunakan di antarmuka administratif portal pengembang untuk mengedit pengaturan widget

    File values.ts berisi nilai default dan jenis properti kustom widget yang dapat Anda aktifkan untuk pengeditan.

    Cuplikan layar dari halaman properti kustom di potal pengembang.

    Properti kustom memungkinkan Anda menyesuaikan nilai dalam instans widget kustom dari antarmuka pengguna administratif portal pengembang, tanpa mengubah kode atau menyebarkan ulang widget kustom. Objek ini perlu diteruskan ke beberapa fungsi pembantu widget.

Menyebarkan widget kustom ke portal pengembang

  1. Tentukan nilai berikut dalam file deploy.js yang terletak di akar proyek Anda:

    • resourceId - ID sumber daya layanan API Management Anda, dalam format berikut: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - Titik akhir API Management Azure (bergantung pada lingkungan Anda, biasanya management.azure.com)

    • apiVersion - Opsional, gunakan untuk mengambil alih versi API manajemen default

  2. Jalankan perintah berikut:

    npm run deploy

    Jika diminta, masuk ke akun Azure Anda.

    Catatan

    Saat diminta untuk masuk, Anda harus menggunakan akun anggota dari penyewa ID Microsoft Entra yang terkait dengan langganan Azure tempat layanan API Management Anda berada. Akun tidak boleh menjadi tamu atau akun federasi dan harus memiliki izin yang sesuai untuk mengakses antarmuka administratif portal.

Widget kustom sekarang disebarkan ke portal pengembang Anda. Dengan menggunakan antarmuka administratif portal, Anda dapat menambahkannya ke halaman di portal pengembang dan mengatur nilai untuk properti kustom apa pun yang dikonfigurasi di widget.

Menerbitkan portal pengembang

Setelah mengonfigurasi widget di antarmuka administratif, terbitkan ulang portal untuk membuat widget tersedia dalam produksi.

Catatan

  • Jika menyebarkan kode widget yang diperbarui di kemudian hari, widget yang digunakan dalam produksi tidak diperbarui hingga Anda menerbitkan ulang portal pengembang.
  • Kode widget yang dikompilasi dikaitkan dengan revisi portal tertentu. Jika menggunakan revisi portal sebelumnya, widget kustom yang terkait dengan revisi tersebut digunakan.

Templat widget

Kami menyediakan templat untuk teknologi berikut yang dapat Anda gunakan untuk widget:

  • TypeScript (implementasi murni tanpa kerangka kerja apa pun)
  • React
  • Vue

Semua templat didasarkan pada bahasa pemrograman TypeScript.

Templat React berisi hook kustom yang disiapkan dalam file hooks.ts dan penyedia yang mapan untuk berbagi konteks melalui pohon komponen dengan hook useSecrets, useValues, dan useEditorValues khusus.

Gunakan paket @azure/api-management-custom-widgets-tools

Paket npm ini berisi fungsi-fungsi berikut untuk membantu mengembangkan widget kustom Anda serta menyediakan fitur termasuk komunikasi antara portal pengembang dan widget Anda:

Fungsi Deskripsi
getValues Menampilkan objek JSON yang berisi nilai yang diatur dalam editor widget yang dikombinasikan dengan nilai default
getEditorValues Menampilkan objek JSON yang hanya berisi nilai yang diatur di editor widget
buildOnChange Menerima jenis TypeScript dan menampilkan fungsi untuk memperbarui nilai widget. Fungsi yang ditampilkan mengambil sebagai parameter objek JSON dengan nilai yang diperbarui dan tidak menampilkan apa pun.

Digunakan secara internal di editor widget
askForSecrets Menampilkan janji JavaScript, yang mana setelah resolusi menampilkan objek data JSON yang diperlukan untuk berkomunikasi dengan backend
deployNodeJs Menyebarkan widget ke penyimpanan blob
getWidgetData Menampilkan semua data yang diteruskan ke widget kustom Anda dari portal pengembang

Digunakan secara internal dalam templat

@azure/api-management-custom-widgets-tools/getValues

Ini adalah fungsi yang mengembalikan objek JSON yang berisi nilai yang telah Anda tetapkan di editor widget yang dikombinasikan dengan nilai default, diteruskan sebagai argumen.

Import {getValues} from "@azure/api-management-custom-widgets-tools/getValues" 
import {valuesDefault} from "./values" 
const values = getValues(valuesDefault)

Ia dimaksudkan untuk digunakan di bagian runtime (app) widget Anda.

@azure/api-management-custom-widgets-tools/getEditorValues

Ini adalah fungsi yang bekerja dengan cara yang sama seperti getValues, tetapi hanya mengembalikan nilai yang telah Anda tetapkan di editor.

Ia dimaksudkan untuk digunakan di editor widget Anda tetapi juga berfungsi dalam runtime.

@azure/api-management-custom-widgets-tools/buildOnChange

Catatan

Fungsi ini dimaksudkan untuk digunakan hanya di editor widget.

Fungsi ini menerima jenis TypeScript dan mengembalikan fungsi untuk memperbarui nilai widget. Fungsi yang ditampilkan mengambil sebagai parameter objek JSON dengan nilai yang diperbarui dan tidak menampilkan apa pun.

import {Values} from "./values"
const onChange = buildOnChange<Values>()
onChange({fieldKey: 'newValue'})

@azure/api-management-custom-widgets-tools/askForSecrets

Fungsi ini menampilkan janji JavaScript, yang mana setelah resolusi menampilkan objek data JSON yang diperlukan untuk berkomunikasi dengan backend. token diperlukan untuk autentikasi. userId diperlukan untuk mengkueri sumber daya khusus pengguna. Nilai-nilai tersebut mungkin tidak terdefinisi saat pengguna anonim melihat portal. Objek Secrets juga berisi managementApiUrl, yang merupakan URL backend portal Anda, dan apiVersion, yang merupakan "apiVersion" yang saat ini digunakan portal pengembang.

Perhatian

Kelola dan gunakan token dengan hati-hati. Siapa pun yang memilikinya dapat mengakses data di layanan API Management Anda.

@azure/api-management-custom-widgets-tools/deployNodeJs

Fungsi ini menyebarkan widget Anda ke penyimpanan blob. Di semua templat, ia telah dikonfigurasi sebelumnya dalam file deploy.js.

Ia menerima tiga argumen secara default:

  • serviceInformation: Informasi tentang layanan Azure Anda:

    • resourceId: ID sumber daya layanan API Management Anda, dalam format berikut: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint: Titik akhir API manajemen Azure (tergantung pada lingkungan Anda, biasanya management.azure.com)

  • ID widget Anda: Nama widget Anda dalam format "RAMAH PC" (karakter huruf kecil alfanumerik Latin dan tanda hubung; Contoso widget menjadi contoso-widget). Anda dapat menemukannya di package.json pada bagian kunci name.

  • fallbackConfigPath: Jalur untuk file lokal config.msapim.json, misalnya ./static/config.msapim.json

@azure/api-management-custom-widgets-tools/getWidgetData

Catatan

Fungsi ini digunakan secara internal dalam templat. Dalam sebagian besar implementasi, Anda tidak membutuhkannya.

Fungsi ini menampilkan semua data yang diteruskan ke widget kustom Anda dari portal pengembang. Ia berisi data lain yang mungkin berguna dalam penelusuran kesalahan atau dalam skenario yang lebih canggih. API ini kemungkinan berubah dengan potensi perubahan yang melanggar. Ia menampilkan objek JSON yang berisi kunci berikut:

  • values: Semua nilai yang telah Anda tetapkan di editor, objek yang sama yang dikembalikan oleh getEditorData
  • instanceId: ID instance widget ini

Menambahkan atau menghapus properti kustom

Properti kustom memungkinkan Anda menyesuaikan nilai dalam kode widget kustom dari antarmuka pengguna administratif portal pengembang, tanpa mengubah kode atau menyebarkan ulang widget kustom. Secara default, bidang input untuk empat properti kustom ditentukan. Anda dapat menambahkan atau menghapus properti kustom lainnya sesuai kebutuhan.

Peringatan

Jangan simpan nilai rahasia atau sensitif di properti kustom.

Menambahkan properti kustom:

  1. Dalam file src/values.ts, tambahkan nama properti dan jenis data yang akan disimpannya ke Values jenis .
  2. Dalam file yang sama, tambahkan nilai default untuk file tersebut.
  3. Navigasi ke editor.html file atau editor/index (lokasi yang tepat tergantung pada kerangka kerja yang Anda pilih) dan duplikat input yang ada atau tambahkan sendiri.
  4. Pastikan bidang input melaporkan nilai yang diubah ke onChange fungsi, yang bisa Anda dapatkan dari buildOnChange.

(Opsional) Menggunakan kerangka kerja lain

Untuk mengimplementasikan widget menggunakan kerangka kerja dan pustaka antarmuka pengguna JavaScript lain, Anda perlu menyiapkan proyek sendiri dengan panduan berikut:

  • Dalam kebanyakan kasus, kami sarankan Anda memulai dari templat TypeScript.
  • Instal dependensi seperti dalam proyek npm lainnya.
  • Jika kerangka kerja pilihan Anda tidak kompatibel dengan alat build Vite, konfigurasikan sehingga menghasilkan file yang dikompilasi ke folder ./dist. Secara opsional, tentukan ulang tempat file yang dikompilasi berada dengan menyediakan jalur relatif sebagai argumen keempat untuk fungsi deployNodeJs.
  • Untuk pengembangan lokal, file config.msapim.json harus dapat diakses di URL localhost:<port>/config.msapim.json saat server berjalan.

Membuat widget kustom menggunakan sumber terbuka React Component Toolkit

Sumber terbuka React Component Toolkit menyediakan serangkaian skrip paket npm untuk membantu Anda mengonversi aplikasi React ke kerangka kerja widget kustom, mengujinya, dan menyebarkan widget kustom ke portal pengembang. Jika Anda memiliki akses ke layanan Azure OpenAI, toolkit juga dapat membuat widget dari deskripsi teks yang Anda berikan.

Saat ini, Anda dapat menggunakan toolkit dengan dua cara untuk menyebarkan widget kustom:

  • Secara manual, dengan menginstal toolkit dan menjalankan skrip paket npm secara lokal. Anda menjalankan skrip secara berurutan untuk membuat, menguji, dan menyebarkan komponen React sebagai widget kustom ke portal pengembang.
  • Menggunakan templat Azure Developer CLI (azd) untuk penyebaran end-to-end. Templat menyebarkan azd instans Azure API Management dan instans Azure OpenAI. Setelah sumber daya disediakan, skrip interaktif membantu Anda membuat, menguji, dan menyebarkan widget kustom ke portal pengembang dari deskripsi yang Anda berikan.

Catatan

Templat sampel React Component Toolkit dan Azure Developer CLI sumber terbuka proyek. Dukungan hanya diberikan melalui masalah GitHub di repositori masing-masing.

Konten terkait

Pelajari selengkapnya tentang portal pengembang:

  • Last updated on