Condividi tramite

Ospitare automaticamente il portale per sviluppatori di Gestione API

  • Articolo

SI APPLICA A: Sviluppatore | Basic | Standard | Premium

Questa esercitazione descrive come ospitare automaticamente il portale per sviluppatori di Gestione API. L'hosting automatico è una delle diverse opzioni per estendere la funzionalità del portale per sviluppatori. Ad esempio, è possibile ospitare 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.

Importante

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

  • Distribuzione in una piattaforma di hosting, facoltativamente front-end da una soluzione, ad esempio rete CDN per una maggiore disponibilità e prestazioni
  • Gestione 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

Nota

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

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

Prerequisiti

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

Passaggio 1: Configurare l'ambiente locale

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

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

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

  2. Passare alla copia locale del repository:

    cd api-management-developer-portal

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

  4. Installare tutti i pacchetti npm disponibili:

    npm install

Suggerimento

Usare sempre la versione più recente del portale e mantenere aggiornato il portale con fork. I software engineer usano 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

Il portale per sviluppatori richiede che l'API REST Gestione API gestisca il contenuto.

config.design.json file

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

{
  "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": "..."
      }
  }
}

Configurare il file:

  1. managementApiUrl Nel valore sostituire <service-name> con il nome dell'istanza di Gestione API. Se è stato configurato un dominio personalizzato, usarlo , ad esempio https://management.contoso.com.

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. Creare manualmente un token di firma di accesso condiviso per abilitare l'accesso diretto dell'API REST all'istanza di Gestione API.

  3. Copiare il token generato e incollarlo come managementApiAccessToken valore.

  4. backendUrl Nel valore sostituire <service-name> con il nome dell'istanza di Gestione API. Se è stato configurato un dominio personalizzato, usarlo , ad esempio https://portal.contoso.com.

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

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

  6. In integration, facoltativamente googleFonts, impostare su apiKey una chiave API Google che consente l'accesso all'API Per sviluppatori di tipi di carattere Web. Questa chiave è necessaria solo se vuoi aggiungere tipi di carattere Google nella sezione Stili dell'editor del portale per sviluppatori.

    Se non si ha già una chiave, è possibile configurare una chiave usando la console di Google Cloud. Seguire questa procedura:

    1. Aprire la console di Google Cloud.
    2. Controllare se l'API per sviluppatori di tipi di carattere Web è abilitata. In caso contrario, abilitarlo.
    3. Selezionare Crea chiave API delle credenziali>.
    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.

config.publish.json file

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

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Configurare il file:

  1. Copiare e incollare i managementApiUrl valori e managementApiAccessToken dal file di configurazione precedente.

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

config.runtime.json file

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

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

Configurare il file:

  1. Copiare e incollare il managementApiUrl valore dal file di configurazione precedente.

  2. backendUrl Nel valore sostituire <service-name> con il nome dell'istanza di Gestione API. Se è stato configurato un dominio personalizzato, usarlo, ad esempio . https://portal.contoso.com

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

Configurare il sito Web statico

Configurare la funzionalità Sito Web statico nell'account di archiviazione fornendo route alle pagine di indice e errore:

  1. Passare all'account di archiviazione nella portale di Azure e selezionare Sito Web statico dal menu a sinistra.

  2. Nella pagina Sito Web statico selezionare Abilitato.

  3. Nel campo Nome documento indice immettere index.html.

  4. Nel campo Percorso documento di errore immettere 404/index.html.

  5. Seleziona Salva.

Configurare le impostazioni CORS per l'account di archiviazione

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

  1. Passare all'account di archiviazione nella portale di Azure e selezionare CORS dal menu a sinistra.

  2. Nella scheda Servizio BLOB configurare le regole seguenti:

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

  3. Seleziona Salva.

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 nei backendUrl file di configurazione del portale) per abilitare diverse funzionalità, tra cui:

  • Verifica CAPTCHA
  • Autorizzazione OAuth 2.0 nella console di test
  • Delega dell'autenticazione utente e della sottoscrizione del prodotto

Per aggiungere le impostazioni CORS:

  1. Passare all'istanza di Gestione API nel portale di Azure e selezionare Impostazioni del portale>per sviluppatori dal menu a sinistra.
  2. Nella scheda Configurazione del portale self-hosted aggiungere uno o più valori di dominio origin. Ad esempio:
    • Dominio in cui è ospitato il portale self-hosted, ad esempio https://www.contoso.com
    • localhost per lo sviluppo locale (se applicabile), ad esempio http://localhost:8080 o https://localhost:8080
  3. 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.

Esegui questo comando:

npm start

Dopo un breve periodo di 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. Tutte le modifiche apportate alla codebase del progetto attivano una ricompilazione e aggiornano la finestra del browser.

Passaggio 4: Modificare tramite l'editor visivo

Usare l'editor visivo per eseguire queste attività:

  • Personalizzare il portale
  • Creare contenuto
  • 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 in locale

I dati del portale hanno origine sotto forma di oggetti tipizzati sicuri. Il comando seguente li converte in file statici e inserisce l'output nella ./dist/website directory :

npm run publish

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

  1. Aprire prompt dei comandi di Windows, PowerShell o un'altra shell dei comandi.

  2. Eseguire il comando dell'interfaccia della riga di comando di Azure seguente:

    Sostituire <account-connection-string> con il stringa di connessione dell'account di archiviazione. È possibile ottenerlo dalla sezione Chiavi di accesso dell'account di archiviazione.

    az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>

Passaggio 7: Vai al tuo sito Web

Il sito Web è ora attivo con il nome host specificato nelle proprietà Archiviazione di Azure (endpoint primario nei siti Web statici).

Passaggio 8: Modificare i modelli di notifica Gestione API

Sostituire l'URL del portale per sviluppatori nei modelli di notifica Gestione API per puntare al portale self-hosted. Vedere Come configurare notifiche e modelli di posta elettronica in Azure Gestione API.

In particolare, eseguire le modifiche seguenti ai modelli predefiniti:

Nota

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

Invita 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 di 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 self-hosted

Nel corso del tempo, i requisiti aziendali possono 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 può forzare la creazione di un widget personalizzato che si integra con un provider di dati di terze parti. A differenza della versione manged, 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 apportate nella versione gestita del portale. Assicurarsi di eseguire il backup del contenuto del portale in anticipo. È possibile trovare lo script di backup nella scripts cartella del repository GitHub del portale per sviluppatori 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 della firma di accesso condiviso, vedere Esercitazione: Usare un'identità assegnata dal sistema di macchine virtuali Linux per accedere alle Archiviazione di Azure tramite credenziali di firma di accesso condiviso.

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.

Passaggi successivi