Ospitare in modalità self-host il portale per sviluppatori di Gestione API

Questa esercitazione descrive come ospitare autonomamente il portale per sviluppatori di Gestione API. L'hosting autonomo è una delle diverse opzioni per estendere la funzionalità del portale degli sviluppatori. Ad esempio, è possibile ospitare automaticamente più portali per l'istanza di Gestione API, con funzionalità diverse. Quando si ospita automaticamente un portale, si diventa il responsabile della gestione e si è responsabili degli aggiornamenti. Il portale per sviluppatori richiede l'API REST di Gestione API per gestire il contenuto.

Importante

Prendere in considerazione l'auto-hosting del portale per sviluppatori solo quando è necessario modificare il nucleo della codebase del portale per sviluppatori. Questa opzione richiede una configurazione avanzata, tra cui:

Distribuzione in una piattaforma di hosting, facoltativamente anticipata da una soluzione come una rete per la distribuzione di contenuti (CDN) per una maggiore disponibilità e prestazione.
Manutenzione e gestione dell'infrastruttura di hosting.
Aggiornamenti manuali, inclusi per le patch di sicurezza, che potrebbero richiedere la risoluzione dei conflitti di codice durante l'aggiornamento della codebase.

Annotazioni

Il portale self-hosted non supporta la visibilità e i controlli di accesso disponibili nel portale per sviluppatori gestiti.

Se i file multimediali sono già stati caricati o modificati nel portale gestito, vedere Passare da file multimediali gestiti a self-hosted più avanti in questo articolo.

Prerequisiti

Per configurare un ambiente di sviluppo locale, è necessario disporre di:

Istanza del servizio Gestione API. Se non è disponibile, vedere Avvio rapido - Creare un'istanza di Gestione API di Azure.

Se l'istanza è stata creata in un livello di servizio v2, abilitare prima di tutto il portale per sviluppatori.
1. Nel menu della barra laterale, in Portale per sviluppatori selezionare Impostazioni portale.
2. Nella finestra Impostazioni portale selezionare Abilitato. Seleziona Salva. L'abilitazione del portale per sviluppatori potrebbe richiedere alcuni minuti.
Un account di archiviazione BLOB di Azure, che verrà usato per abilitare la funzionalità siti Web statici. Vedere Creare un account di archiviazione.
Git nel computer. Installarlo seguendo questa esercitazione su Git.
Node.js (versione LTS (Long Term Support) v10.15.0 o versione successiva) e npm sul tuo computer. Vedi Download e installazione di Node.js e npm.
Azure CLI (Interfaccia della riga di comando di Azure) Seguire la procedura di installazione dell'interfaccia della riga di comando di Azure.
Autorizzazioni per creare una registrazione dell'app Microsoft Entra.

Passaggio 1: Configurare l'ambiente locale

Per configurare l'ambiente locale, clonare il repository, passare alla versione più recente del portale per sviluppatori e installare i pacchetti npm.

Clonare il repository api-management-developer-portal da GitHub:

git clone https://github.com/Azure/api-management-developer-portal.git

Passare alla copia locale del repository:
```
cd api-management-developer-portal
```
Vedere la versione più recente del portale.

Prima di eseguire il codice seguente, controllare il tag di versione corrente nella sezione Versioni del repository e sostituire <current-release-tag> il valore con il tag di versione più recente.
```
git checkout <current-release-tag>
```
Installare tutti i pacchetti npm disponibili:
```
npm install
```

Suggerimento

Usare sempre la versione più recente del portale e mantenere aggiornato il portale con fork. Il team di sviluppo di Gestione API usa il master ramo di questo repository per scopi di sviluppo giornalieri. Ha versioni instabili del software.

Passaggio 2: Configurare file JSON, sito Web statico e impostazioni CORS

file config.design.json

Passare alla src cartella e aprire il config.design.json file.

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

In subscriptionId, resourceGroupNamee serviceNameimmettere i valori per la sottoscrizione, il gruppo di risorse e il nome del servizio dell'istanza di Gestione API. I

Impostazioni facoltative in config.design.json

Facoltativamente, configurare le impostazioni seguenti nel config.design.json file:

Se si vuole abilitare CAPTCHA nel portale per sviluppatori, impostare "useHipCaptcha": true. Assicurarsi di configurare le impostazioni CORS per il back-end del portale per sviluppatori.
```
{
    ...
    "useHipCaptcha": true
    ...
}
```
In integration, sotto googleFonts, impostare facoltativamente su apiKey una chiave API di Google che consente l'accesso all'API dei font Web per sviluppatori. Questa chiave è necessaria solo se vuoi aggiungere tipi di carattere Google nella sezione Stili dell'editor del portale per sviluppatori.
```
{
    ...
    "integration": {
        "googleFonts": {
            "apiKey": "< your Google API key >"
        }
    }
    ...
}
```
Se non si ha già una chiave, è possibile configurare una chiave usando la console di Google Cloud. Segui questi passaggi:
1. Aprire la console di Google Cloud.
2. Controllare se l'API per sviluppatori di tipi di carattere Web è abilitata. In caso contrario, abilitarla.
3. Selezionare Crea credenziali>chiave API.
4. Nella finestra di dialogo aperta copiare la chiave generata e incollarla come valore di apiKey nel config.design.json file.
5. Selezionare Modifica chiave API per aprire l'editor di chiavi.
6. Nell'editor, in Restrizioni API selezionare Limita chiave. Nell'elenco a discesa selezionare API per sviluppatori di tipi di carattere Web.
7. Seleziona Salva.

file config.publish.json

Passare alla src cartella e aprire il config.publish.json file.

{
    "environment": "publishing",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Copiare e incollare i subscriptionIdvalori , resourceGroupNamee serviceName dal file di configurazione precedente.

config.runtime.json file

Passare alla src cartella e aprire il config.runtime.json file.

{
    "environment": "runtime",
    "backendUrl": "https://< service name >.developer.azure-api.net"
}

Sostituire < service name > con il nome dell'istanza di Gestione API usata nei file di configurazione precedenti.

Configurare il sito Web statico

Configurare la funzionalità Sito Web statico nell'account di archiviazione fornendo percorsi alla pagina indice e alla pagina di errore.

Nel portale di Azure, accedi al tuo account di archiviazione.
Nel menu della barra laterale selezionare Gestione dati>Sito Web statico.
Nella pagina Sito Web statico selezionare Abilitato.
Nel campo Nome documento indice immettere index.html.
Nel campo Percorso documento di errore immettere 404/index.html.
Seleziona Salva.

Prendere nota dell'URL dell'endpoint primario. Configurerai più tardi per accedere al tuo portale autogestito.

Configurare le impostazioni CORS per l'account di archiviazione

Per configurare le impostazioni CORS (Cross-Origin Resource Sharing) per l'account di archiviazione:

Passare al proprio account di archiviazione nel portale di Azure.
Dal menu della barra laterale, in Impostazioni, selezionare Condivisione risorse (CORS).
Nella scheda Servizio BLOB configurare le regole seguenti:

Regola Valore

Origini consentite *

Metodi consentiti Selezionare tutti i verbi HTTP.

Intestazioni consentite *

Intestazioni esposte *

Età massima 0
Seleziona Salva.

Regola	Valore
Origini consentite	*
Metodi consentiti	Selezionare tutti i verbi HTTP.
Intestazioni consentite	*
Intestazioni esposte	*
Età massima	0

Configurare le impostazioni CORS per il back-end del portale per sviluppatori

Configurare le impostazioni CORS per il back-end del portale per sviluppatori per consentire le richieste provenienti tramite il portale per sviluppatori self-hosted. Il portale per sviluppatori self-hosted si basa sull'endpoint back-end del portale per sviluppatori (impostato in backendUrl nel file config.runtime.json del portale) per abilitare diverse funzionalità, tra cui:

Verifica CAPTCHA
Autorizzazione OAuth 2.0 nella console di test
Delega dell'autenticazione degli utenti e dell'abbonamento ai prodotti

Per aggiungere le impostazioni CORS:

Passare all'istanza di Gestione API nel portale di Azure.
Nel menu della barra laterale selezionareImpostazioni> per sviluppatori.
Nella scheda Configurazione del portale self-hosted aggiungere uno o più valori di dominio origin . Per esempio:
- Dominio in cui è ospitato il portale self-hosted, ad esempio https://contoso.developer.azure-api.net
- localhost per lo sviluppo locale (se applicabile), ad esempio http://localhost:8080 o https://localhost:8080
Seleziona Salva.

Passaggio 3: Eseguire il portale

È ora possibile compilare ed eseguire un'istanza del portale locale in modalità di sviluppo. In modalità di sviluppo, tutte le ottimizzazioni vengono disattivate e le mappe di origine sono attivate.

Eseguire il comando seguente:
```
npm run start
```
Viene richiesto di eseguire l'autenticazione tramite il browser. Selezionare le credenziali Microsoft per continuare.
Dopo qualche tempo, il browser predefinito si apre automaticamente con l'istanza del portale per sviluppatori locale. L'indirizzo predefinito è http://localhost:8080, ma la porta può cambiare se 8080 è già occupata. Quando si apportano modifiche alla codebase del progetto, viene attivata una ricompilazione e viene aggiornata la finestra del browser.

Passaggio 4: Modificare tramite l'editor visivo

Usare l'editor visivo per eseguire queste attività:

Personalizzare il portale
Contenuto dell'autore
Organizzare la struttura del sito Web
Stilizzarne l'aspetto

Vedere Esercitazione: Accedere e personalizzare il portale per sviluppatori. Vengono illustrate le nozioni di base dell'interfaccia utente amministrativa ed elenca le modifiche consigliate al contenuto predefinito. Salvare tutte le modifiche nell'ambiente locale e premere CTRL+C per chiuderlo.

Passaggio 5: Pubblicare il portale in locale

Eseguire npm run publish. Viene richiesto di eseguire l'autenticazione tramite il browser. Selezionare le credenziali Microsoft per continuare.
Dopo qualche tempo, il contenuto viene pubblicato nella dist/website cartella .

Passaggio 6: Caricare file statici in un BLOB

Usare l'interfaccia della riga di comando di Azure per caricare i file statici generati in locale in un BLOB e assicurarsi che i visitatori possano ottenerli:

Apri il prompt dei comandi di Windows, PowerShell o un'altra shell dei comandi.
Eseguire il comando seguente az storage blog upload-batch . Sostituire <connection-string> con una stringa di connessione per l'account di archiviazione. È possibile ottenerlo dalla sezione Sicurezza e> alla rete dell'account di archiviazione.
```
az storage blob upload-batch --source dist/website \
    --account-name <your-storage-account-name> \
    --destination '$web' \
    --connection-string "<connection-string>"
```

Passaggio 7: Vai al tuo sito Web

Il sito Web è ora attivo con il nome host specificato nelle proprietà di Archiviazione di Azure. Nel menu della barra laterale passare a Gestione dati>Sito web statico. Il nome host è il valore dell'endpoint primario.

Gestire l'editor del sito web

Quando si apportano modifiche al codice del sito Web, potrebbe essere necessario aggiornare il codice dell'editor del sito Web per poter supportare correttamente la modifica dei widget modificati. In questo caso, oltre a ospitare il portale, è anche possibile ospitare l'applicazione dell'editor. A questo scopo, è necessario compilarlo e configurarlo per accedere al servizio Gestione API.

Per questo motivo, è necessaria un'applicazione Microsoft Entra ID nel tenant:

Registrare un'applicazione nel tenant microsoft Entra ID. Prendere nota dei valori ID applicazione (client) e ID directory (tenant). È possibile configurarli in un passaggio successivo.
Configurare un URI di reindirizzamento Web (URL di risposta) in questa applicazione in modo che punti all'endpoint dell'app Web in cui è ospitata la finestra di progettazione. Si tratta in genere della posizione del sito Web basato su blob storage. Esempio: https://<your-storage-account-name>z13.web.core.windows.net/.
Se si vuole pubblicare il portale nelle pipeline (GitHub Actions), creare anche un segreto client per questa applicazione. Prendere nota del valore del segreto generato e archiviarlo in una posizione sicura.

Seguire quindi questa procedura per ospitare l'editor del sito Web:

Aggiungere i campi clientId e tenantId al file config.design.json.

{
    ...
    "clientId": "< Entra ID app ID >",
    "tenantId": "< Entra ID tenant ID >"
    ...
}

Eseguire il comando npm run build-designer per costruire il progettista.

Passare alla cartella generata /dist/designer , che contiene un file config.json con il contenuto seguente:

{
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >",
    "clientId": "< Entra ID client ID >",
    "tenantId": "< Entra ID tenant ID >"
}

Verificare la configurazione di subscriptionIdresourceGroupName e serviceName, necessarie per connettersi al servizio Gestione API usando le API di Azure Resource Manager.

Pubblicare il portale nelle pipeline (GitHub Actions)

È possibile pubblicare il portale self-hosted in una pipeline, ad esempio GitHub Actions.

La pipeline richiede anche le credenziali dell'applicazione Entra ID per eseguire la pubblicazione usando la pipeline. È possibile usare la stessa applicazione Entra ID descritta nei passaggi precedenti. L'oggetto tenantId, clientId e in particolare clientSecret deve essere mantenuto nella rispettiva archiviazione delle chiavi. Per altri dettagli, vedere Uso dei segreti in GitHub Actions .

Esempio di pipeline YAML di GitHub Actions:


name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

Modificare i modelli di notifica di Gestione API

Sostituire l'URL del portale per sviluppatori nei modelli di notifica di Gestione API in modo che punti al portale auto-ospitato. Vedere Come configurare le notifiche e i modelli di posta elettronica in Gestione API di Azure.

In particolare, eseguire le modifiche seguenti ai modelli predefiniti:

Annotazioni

I valori nelle sezioni aggiornate seguenti presuppongono che si stia ospitando il portale all'indirizzo https://portal.contoso.com/.

Conferma della modifica tramite posta elettronica

Aggiornare l'URL del portale per sviluppatori nel modello di notifica di conferma della modifica tramite posta elettronica :

Contenuto originale

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Aggiornato

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Conferma del nuovo account per sviluppatore

Aggiornare l'URL del portale per sviluppatori nel modello di notifica di conferma del nuovo account per sviluppatore :

Contenuto originale

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Aggiornato

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Invito utente

Aggiornare l'URL del portale per sviluppatori nel modello Invita notifica utente :

Contenuto originale

<a href="$ConfirmUrl">$ConfirmUrl</a>

Aggiornato

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Nuova sottoscrizione attivata

Aggiornare l'URL del portale per sviluppatori nel modello di notifica Nuova sottoscrizione attivata :

Contenuto originale

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!

Aggiornato

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!

Contenuto originale

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Aggiornato

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Contenuto originale

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Aggiornato

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Contenuto originale

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

Aggiornato

<!--Remove the entire block of HTML code above.-->

Conferma della modifica della password

Aggiornare l'URL del portale per sviluppatori nel modello di notifica di conferma della modifica della password :

Contenuto originale

<a href="$DevPortalUrl">$DevPortalUrl</a>

Aggiornato

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Tutti i modelli

Aggiornare l'URL del portale per sviluppatori in qualsiasi modello con un collegamento nel piè di pagina:

Contenuto originale

<a href="$DevPortalUrl">$DevPortalUrl</a>

Aggiornato

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Passare dal portale per sviluppatori gestito al portale per sviluppatori auto-ospitato

Nel corso del tempo, i requisiti aziendali potrebbero cambiare. È possibile terminare in una situazione in cui la versione gestita del portale per sviluppatori di Gestione API non soddisfa più le proprie esigenze. Ad esempio, un nuovo requisito potrebbe forzare la creazione di un widget personalizzato che si integra con un provider di dati di terze parti. A differenza della versione gestita, la versione self-hosted del portale offre flessibilità ed estendibilità complete.

Processo di transizione

È possibile passare dalla versione gestita a una versione self-hosted all'interno della stessa istanza del servizio Gestione API. Il processo mantiene le modifiche eseguite nella versione gestita del portale. Assicurarsi di eseguire il backup del contenuto del portale in anticipo. È possibile trovare lo script di backup nella scripts.v3 cartella del repository GitHub del portale per sviluppatori di Gestione API.

Il processo di conversione è quasi identico alla configurazione di un portale self-hosted generico, come illustrato nei passaggi precedenti di questo articolo. Nel passaggio di configurazione è presente un'eccezione. L'account config.design.json di archiviazione nel file deve essere uguale all'account di archiviazione della versione gestita del portale. Per istruzioni su come recuperare l'URL SAS, vedere l'esercitazione: usare un'identità assegnata dal sistema di una macchina virtuale Linux per accedere all'archiviazione di Azure tramite una credenziale SAS.

Suggerimento

È consigliabile usare un account di archiviazione separato nel config.publish.json file. Questo approccio offre un maggiore controllo e semplifica la gestione del servizio di hosting del portale.

Informazioni sugli approcci alternativi all'auto-gestione

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-30

Condividi tramite

Ospitare in modalità self-host il portale per sviluppatori di Gestione API

Prerequisiti

Passaggio 1: Configurare l'ambiente locale

Passaggio 2: Configurare file JSON, sito Web statico e impostazioni CORS

file config.design.json

Impostazioni facoltative in config.design.json

file config.publish.json

config.runtime.json file

Configurare il sito Web statico

Configurare le impostazioni CORS per l'account di archiviazione

Configurare le impostazioni CORS per il back-end del portale per sviluppatori

Passaggio 3: Eseguire il portale

Passaggio 4: Modificare tramite l'editor visivo

Passaggio 5: Pubblicare il portale in locale

Passaggio 6: Caricare file statici in un BLOB

Passaggio 7: Vai al tuo sito Web

Gestire l'editor del sito web

Pubblicare il portale nelle pipeline (GitHub Actions)

Modificare i modelli di notifica di Gestione API

Conferma della modifica tramite posta elettronica

Conferma del nuovo account per sviluppatore

Invito utente

Nuova sottoscrizione attivata

Conferma della modifica della password

Tutti i modelli

Passare dal portale per sviluppatori gestito al portale per sviluppatori auto-ospitato

Processo di transizione

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive