Memperluas portal pengembang dengan widget kustom

  • Artikel

BERLAKU UNTUK: Pengembang | Dasar | Standar | Premium

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.

Menggunakan widget kode HTML Kustom

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

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

  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.

    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. Simpan perubahan Anda, dan terbitkan ulang portal.

Catatan

Microsoft tidak mendukung kode HTML yang Anda tambahkan di sidget 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 runtimeNode.JS secara lokal
  • Pengetahuan dasar tentang pemrograman dan pengembangan web

Membuat widget

Peringatan

Kode widget kustom Anda disimpan di penyimpanan blob Azure publik 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 kustom>Buat widget kustom baru.

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

  3. Pilih Buat widget.

  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. Untuk melakukannya, periksa output di konsol tempat Anda memulai server di langkah sebelumnya. Ia 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

Fungsi yang menampilkan 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

Fungsi yang memiliki cara kerja yang sama seperti getValues, tetapi hanya menampilkan 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.

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.

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 tersebut mungkin tidak terdefinisi saat portal dilihat oleh pengguna anonim. Objek Secrets juga berisi managementApiUrl, yang merupakan URL backend portal Anda, dan apiVersion, yang merupakan apiVersion yang saat ini digunakan oleh 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 terkait 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 (bergantung 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 config.msapim.json lokal, 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 ditampilkan oleh getEditorData
  • instanceId - ID instans 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 ke jenis Values nama properti dan jenis data yang akan disimpannya.
  2. Dalam file yang sama, tambahkan nilai default untuk file tersebut.
  3. Buka file editor.html atau editor/index (lokasi yang tepat bergantung 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: