Condividi tramite

Estendere il portale per sviluppatori con widget personalizzati

  • Articolo

SI APPLICA A: Sviluppatore | Basic | Standard | Premium

Il portale per sviluppatori di Gestione API include un editor visivo e widget predefiniti, in modo da poter personalizzare e definire lo stile dell'aspetto del portale. Tuttavia, potrebbe essere necessario personalizzare ulteriormente il portale per sviluppatori con funzionalità personalizzate. Ad esempio, è possibile integrare il portale per sviluppatori con un sistema di supporto che prevede l'aggiunta di un'interfaccia personalizzata. Questo articolo illustra i modi in cui aggiungere funzionalità personalizzate, ad esempio widget personalizzati, al portale per sviluppatori di Gestione API.

Nella tabella seguente, sono riepilogate due opzioni, con collegamenti ad altri dettagli.

metodo Descrizione
Widget di codice HTML personalizzato - Soluzione leggera per gli editori di API per aggiungere logica personalizzata per i casi d'uso di base

- Copiando e incollando il codice HTML personalizzato in un modulo, il portale per sviluppatori ne esegue il rendering in un iframe
Creare e caricare un widget personalizzato - Soluzione per sviluppatori per casi d'uso di widget più avanzati

- Richiede l'implementazione locale in React, Vue o TypeScript normale

- Scaffolding di widget e strumenti forniti per aiutare gli sviluppatori a creare widget ed eseguire il caricamento nel portale per sviluppatori

- La creazione, il test e la distribuzione dei widget possono essere inseriti nello script tramite il React Component Toolkit open source

- Supporta i flussi di lavoro per il controllo del codice sorgente, il controllo delle versioni e il riutilizzo del codice

Nota

L'hosting automatico del portale per sviluppatori è un'opzione di estendibilità per i clienti che devono personalizzare il codice sorgente dell'intero core del portale. Offre una flessibilità completa per personalizzare l'esperienza del portale, ma richiede una configurazione avanzata. Con l’hosting automatico, il cliente è responsabile della gestione del ciclo di vita completo del codice: codebase fork, sviluppo, distribuzione, hosting, patch e aggiornamento.

Suggerimento

Un'altra opzione per personalizzare il portale per sviluppatori consiste nell'usare un plug-in del portale per sviluppatori open source per Wordpress. Sfruttare le funzionalità del sito in WordPress per localizzare il contenuto, personalizzare i menù, applicare fogli di stile personalizzati e altro ancora nel portale per sviluppatori.

Usare il widget di codice HTML personalizzato

Il portale per sviluppatori gestito include un widget di codice HTML personalizzato in cui è possibile inserire codice HTML per piccole personalizzazioni del portale. Ad esempio, è possibile usare codice HTML personalizzato per incorporare un video o per aggiungere un modulo. Il portale esegue il rendering del widget personalizzato in un frame inline (iframe).

  1. Nell'interfaccia amministrativa del portale per sviluppatori, passare alla pagina o alla sezione in cui si vuole inserire il widget.

  2. Selezionare l'icona grigia "più" (+) che viene visualizzata quando si passa il puntatore del mouse sulla pagina.

  3. Nella finestra Aggiungi widget, selezionare Codice HTML personalizzato.

    Screenshot che mostra come aggiungere un widget per il codice HTML personalizzato nel portale per sviluppatori.

  4. Selezionare l'icona "matita" per personalizzare il widget.

  5. Immettere Larghezza e Altezza (in pixel) per il widget.

  6. Per ereditare gli stili dal portale per sviluppatori (scelta consigliata), selezionare Applica stili del portale per sviluppatori.

    Nota

    Se questa impostazione non è selezionata, gli elementi incorporati saranno controlli HTML semplici, senza gli stili del portale per sviluppatori.

    Screenshot che mostra come configurare codice personalizzato HTML nel portale per sviluppatori.

  7. Sostituire il codice HTML di esempio con il contenuto personalizzato.

  8. Al termine della configurazione, chiudere la finestra.

  9. Salvare le modifiche e ripubblicare il portale.

Nota

Microsoft non supporta il codice HTML aggiunto nel widget di codice HTML personalizzato.

Creare e caricare un widget personalizzato

Per casi d'uso più avanzati, è possibile creare e caricare un widget personalizzato nel portale per sviluppatori. Gestione API fornisce uno scaffolding del codice che consente agli sviluppatori di creare widget personalizzati in React, Vue o TypeScript normale. Lo scaffolding include strumenti che consentono di sviluppare e distribuire il widget nel portale per sviluppatori.

Prerequisiti

  • Installare il runtime Node.JS in locale
  • Conoscenza di base della programmazione e dello sviluppo Web

Creare il widget

Avviso

Il codice del widget personalizzato viene archiviato nell'archivio BLOB pubblico di Azure associato all'istanza di Gestione API. Quando si aggiunge un widget personalizzato al portale per sviluppatori, il codice viene letto da questa risorsa di archiviazione tramite un endpoint che non richiede l'autenticazione, anche se il portale per sviluppatori o una pagina con il widget personalizzato sono accessibili solo agli utenti autenticati. Non includere informazioni sensibili o segreti nel codice del widget personalizzato.

  1. Nell'interfaccia amministrativa del portale per sviluppatori, selezionare Widget personalizzati>Crea nuovo widget personalizzato.

  2. Immettere un nome di widget e scegliere una Tecnologia. Per altre informazioni, vedere Modelli di widget più avanti in questo articolo.

  3. Selezionare Crea widget.

  4. Aprire un terminale, passare al percorso in cui si vuole salvare il codice del widget ed eseguire il comando seguente per scaricare lo scaffold del codice:

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

  5. Passare alla cartella appena creata contenente lo scaffold del codice del widget.

    cd <name-of-widget>

  6. Aprire la cartella nell'editor di codice preferito, ad esempio Visual Studio Code.

  7. Installare le dipendenze e avviare il progetto:

    npm install 
npm start

    Il browser dovrebbe aprire una nuova scheda con il portale per sviluppatori connesso al widget in modalità di sviluppo.

    Nota

    Se la scheda non si apre, eseguire le operazioni seguenti:

    1. Assicurarsi che il server di sviluppo sia stato avviato. A tale scopo, verificare l'output nella console in cui è stato avviato il server nel passaggio precedente. Questo dovrebbe mostrare la porta in cui è in esecuzione il server (ad esempio, http://127.0.0.1:3001).
    2. Passare al servizio Gestione API nel portale di Azure e aprire il portale per sviluppatori con l'interfaccia amministrativa.
    3. Aggiungi /?MS_APIM_CW_localhost_port=3001 all'URL. Modificare il numero di porta se il server viene eseguito su una porta diversa.

  8. Implementare il codice del widget e testarlo in locale. Il codice del widget si trova nella cartella src, nelle sottocartelle seguenti:

    • app - Codice per il componente widget che i visitatori del portale per sviluppatori pubblicato vedono e con cui interagiscono
    • editor - Codice per il componente widget usato nell'interfaccia amministrativa del portale per sviluppatori per modificare le impostazioni del widget

    Il file values.ts contiene i valori predefiniti e i tipi di proprietà personalizzate del widget che è possibile abilitare alla modifica.

    Screenshot della pagina delle proprietà personalizzate nel portale per sviluppatori.

    Le proprietà personalizzate consentono di modificare i valori nell'istanza del widget personalizzato dall'interfaccia utente amministrativa del portale per sviluppatori, senza modificare il codice o ridistribuire il widget personalizzato. Questo oggetto deve essere passato ad alcune delle funzioni di supporto dei widget.

Distribuire il widget personalizzato nel portale per sviluppatori

  1. Specificare i valori seguenti nel file deploy.js che si trova nella radice del progetto:

    • resourceId - ID risorsa del servizio Gestione API, nel formato seguente: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - Endpoint dell'API di gestione di Azure (dipende dall'ambiente in uso, in genere management.azure.com)

    • apiVersion - (Facoltativo) da usare per eseguire l'override della versione predefinita dell'API di gestione

  2. Esegui questo comando:

    npm run deploy

    Se richiesto, accedere all'account di Azure.

    Nota

    Quando viene richiesto di eseguire l'accesso, è necessario usare un account membro dal tenant Microsoft Entra ID associato alla sottoscrizione di Azure in cui risiede il servizio Gestione API. L'account non deve essere un account guest o federato e deve disporre dell'autorizzazione appropriata per accedere all'interfaccia amministrativa del portale.

Il widget personalizzato viene ora distribuito nel portale per sviluppatori. Usando l'interfaccia amministrativa del portale, è possibile aggiungerlo nelle pagine del portale per sviluppatori e impostare i valori per le proprietà personalizzate configurate nel widget.

Pubblicare il portale per sviluppatori

Dopo aver configurato il widget nell'interfaccia amministrativa, ripubblicare il portale per rendere il widget disponibile nell'ambiente di produzione.

Nota

  • Se si distribuisce il codice del widget aggiornato in un secondo momento, il widget usato nell'ambiente di produzione non viene aggiornato fino a quando non viene ripubblicato il portale per sviluppatori.
  • Il codice compilato del widget è associato a una revisione specifica del portale. Se si imposta una revisione precedente del portale come corrente, viene usato il widget personalizzato associato a tale revisione.

Modelli di widget

Sono disponibili modelli per le tecnologie seguenti da poter usare per il widget:

  • TypeScript (implementazione pura senza framework)
  • React
  • Vue

Tutti i modelli sono basati sul linguaggio di programmazione TypeScript.

Il modello React contiene hook personalizzati preparati nel file hooks.ts e provider stabiliti per la condivisione del contesto tramite l'albero dei componenti con hook useSecrets, useValues e useEditorValues dedicati.

Usare il pacchetto @azure/api-management-custom-widgets-tools

Questo pacchetto npm contiene le funzioni seguenti per sviluppare il widget personalizzato e offre funzionalità tra cui la comunicazione tra il portale per sviluppatori e il widget:

Funzione Descrizione
getValues Restituisce un oggetto JSON contenente i valori impostati nell'editor del widget in combinazione con i valori predefiniti
getEditorValues Restituisce un oggetto JSON contenente solo i valori impostati nell'editor del widget
buildOnChange Accetta un tipo TypeScript e restituisce una funzione per aggiornare i valori del widget. La funzione restituita accetta come parametro un oggetto JSON con valori aggiornati e non restituisce nulla.

Usato internamente nell'editor del widget
askForSecrets Restituisce una promessa JavaScript, che dopo la risoluzione restituisce un oggetto JSON dei dati necessari per comunicare con il back-end
deployNodeJs Distribuisce il widget nell'archivio BLOB
getWidgetData Restituisce tutti i dati passati al widget personalizzato dal portale per sviluppatori

Usato internamente nei modelli

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

Funzione che restituisce un oggetto JSON contenente i valori impostati nell'editor del widget in combinazione con i valori predefiniti, passati come argomento.

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

È progettata per essere usata nella parte di runtime (app) del widget.

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

Funzione che agisce allo stesso modo di getValues, ma restituisce solo i valori impostati nell'editor.

È progettata per essere usata nell'editor del widget, ma funziona anche in fase di runtime.

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

Nota

Questa funzione deve essere usata solo nell'editor del widget.

Accetta un tipo TypeScript e restituisce una funzione per aggiornare i valori del widget. La funzione restituita accetta come parametro un oggetto JSON con valori aggiornati e non restituisce nulla.

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

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

Questa funzione restituisce una promessa JavaScript, che dopo la risoluzione restituisce un oggetto JSON dei dati necessari per comunicare con il back-end. token è necessario per l'autenticazione. userId è necessario per eseguire query su risorse specifiche dell'utente. Questi valori potrebbero non essere definiti quando il portale viene visualizzato da un utente anonimo. L'oggetto Secrets contiene anche managementApiUrl, ovvero l'URL del back-end del portale, e apiVersion, che è l'apiVersion attualmente usata dal portale per sviluppatori.

Attenzione

Gestire e usare attentamente il token. Chiunque lo detenga può accedere ai dati nel servizio Gestione API.

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

Questa funzione distribuisce il widget nell'archivio BLOB. In tutti i modelli, è preconfigurata nel file deploy.js.

Accetta tre argomenti per impostazione predefinita:

  • serviceInformation - Informazioni sul servizio di Azure:

    • resourceId - ID risorsa del servizio Gestione API, nel formato seguente: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint - Endpoint dell'API di gestione di Azure (dipende dall'ambiente in uso, in genere management.azure.com)

  • ID del widget: nome del widget in formato "PC-friendly" (caratteri alfanumerici latini in minuscolo e trattini; Contoso widget diventa contoso-widget). È possibile trovarlo in package.json sotto la chiave name.

  • fallbackConfigPath - Percorso del file locale config.msapim.json, ad esempio ./static/config.msapim.json

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

Nota

Questa funzione viene usata internamente nei modelli. Nella maggior parte delle implementazioni non è necessaria in altri casi.

Questa funzione restituisce tutti i dati passati al widget personalizzato dal portale per sviluppatori. Contiene altri dati che potrebbero essere utili per il debug o in scenari più avanzati. Questa API dovrebbe subire potenziali modifiche di rilievo. Restituisce un oggetto JSON che contiene le chiavi seguenti:

  • values - Tutti i valori impostati nell'editor, lo stesso oggetto restituito da getEditorData
  • instanceId - ID di questa istanza del widget

Aggiungere o rimuovere proprietà personalizzate

Le proprietà personalizzate consentono di modificare i valori nel codice del widget personalizzato dall'interfaccia utente amministrativa del portale per sviluppatori, senza modificare il codice o ridistribuire il widget personalizzato. Per impostazione predefinita, vengono definiti i campi di input per quattro proprietà personalizzate. È possibile aggiungere o rimuovere altre proprietà personalizzate in base alle esigenze.

Avviso

Non archiviare valori segreti o sensibili nelle proprietà personalizzate.

Per aggiungere una proprietà personalizzata:

  1. Nel file src/values.ts, aggiungere al tipo Values il nome della proprietà e il tipo di dati che verranno salvati.
  2. Nello stesso file, aggiungere un valore predefinito per lo stesso.
  3. Passare al file editor.html o editor/index (il percorso esatto dipende dal framework scelto) e duplicare un input esistente o aggiungerne uno manualmente.
  4. Assicurarsi che il campo di input restituisca il valore modificato alla funzione onChange, che è possibile ottenere da buildOnChange.

(Facoltativo) Usare un altro framework

Per implementare il widget usando altri framework e librerie dell'interfaccia utente JavaScript, è necessario configurare il progetto manualmente attenendosi alle linee guida seguenti:

  • Nella maggior parte dei casi, è consigliabile iniziare dal modello TypeScript.
  • Installare le dipendenze come in qualsiasi altro progetto npm.
  • Se il framework preferito non è compatibile con lo strumento di compilazione Vite, configurarlo in modo che abbia come output i file compilati nella cartella ./dist. Facoltativamente, ridefinire la posizione dei file compilati specificando un percorso relativo come quarto argomento per la funzione deployNodeJs.
  • Per lo sviluppo locale, il file config.msapim.json deve essere accessibile all'URL localhost:<port>/config.msapim.json quando il server è in esecuzione.

Creare widget personalizzati con React Component Toolkit open source

React Component Toolkit open source offre una suite di script di pacchetti npm che consentono di convertire un'applicazione React nel framework widget personalizzato, testarla e distribuire il widget personalizzato nel portale per sviluppatori. Se si ha accesso a un servizio OpenAI di Azure, il toolkit può anche creare un widget da una descrizione di testo specificata.

Attualmente, è possibile usare il toolkit in due modi per distribuire un widget personalizzato:

  • Manualmente, installando il toolkit ed eseguendo gli script del pacchetto npm in locale. Gli script vengono eseguiti in sequenza per creare, testare e distribuire un componente React come widget personalizzato nel portale per sviluppatori.
  • Usando un modello dell'interfaccia della riga di comando per sviluppatori di Azure (azd) per una distribuzione end-to-end. Il modello azd distribuisce un'istanza di Gestione API di Azure e un'istanza OpenAI di Azure. Dopo il provisioning delle risorse, uno script interattivo consente di creare, testare e distribuire un widget personalizzato nel portale per sviluppatori da una descrizione specificata.

Nota

Il modello di esempio di React Component Toolkit e dell'interfaccia della riga di comando per sviluppatori di Azure sono progetti open source. Il supporto viene fornito solo tramite problemi GitHub nei rispettivi repository.

Contenuto correlato

Altre informazioni sul portale per sviluppatori: