Portale per sviluppatori di Gestione API - Domande frequenti

SI APPLICA A: Sviluppatore | Basic | Basic v2 | Standard | Standard v2 | Premium

Cosa accade se sono necessarie funzionalità non supportate nel portale?

Sono disponibili le seguenti opzioni:

• Per le piccole personalizzazioni, usare un widget predefinito per aggiungere codice HTML personalizzato. Attualmente, il widget di codice HTML personalizzato non è disponibile nei livelli v2 di Gestione API.

• Per le personalizzazioni più ampie, creare e caricare un widget personalizzato nel portale per sviluppatori gestito. Attualmente, i widget personalizzati non sono disponibili nei livelli v2 di Gestione API.

• Ospitare automaticamente il portale per sviluppatori, solo se è necessario apportare modifiche al core della codebase del portale per sviluppatori.

• Aprire una richiesta di funzionalità nel repository GitHub.

Altre informazioni su personalizzazione ed estensione delle funzionalità del portale per sviluppatori.

È possibile avere più portali per sviluppatori in un unico servizio Gestione API?

È possibile avere un portale gestito e più portali self-hosted. Il contenuto di tutti i portali viene archiviato nello stesso servizio Gestione API, quindi saranno identici. Se si desidera distinguere l'aspetto e le funzionalità dei portali, è possibile optare per il self-hosting con widget personalizzati che personalizzano dinamicamente le pagine in fase di esecuzione, ad esempio in base all'URL.

Il portale supporta i modelli di Azure Resource Manager e/o è compatibile con il kit risorse DevOps di Gestione API?

No.

Il contenuto del portale viene salvato con la funzionalità di backup/ripristino in Gestione API?

No.

È necessario abilitare una connettività di rete virtuale aggiuntiva per le dipendenze del portale gestito?

Nella maggior parte dei casi, no.

Se il servizio Gestione API si trova in una rete virtuale interna, il portale per sviluppatori è accessibile solo dall'interno della rete. Il nome host dell'endpoint di gestione deve essere risolto nell'indirizzo VIP interno del servizio dal computer usato per accedere all'interfaccia amministrativa del portale. Assicurarsi che l'endpoint di gestione sia registrato nel DNS. In caso di configurazione errata, verrà visualizzato un errore: Unable to start the portal. See if settings are specified correctly in the configuration (...).

Se il servizio Gestione API si trova in una rete virtuale interna e vi si accede tramite il gateway applicazione da Internet, assicurarsi di abilitare la connettività al portale per sviluppatori e agli endpoint di gestione di Gestione API. Potrebbe essere necessario disabilitare le regole di Web application firewall. Per altri dettagli, vedere questo articolo della documentazione.

È stato assegnato un dominio di Gestione API personalizzato e il portale pubblicato non funziona

Dopo aver aggiornato il dominio, è necessario ripubblicare il portale per rendere effettive le modifiche.

È stato aggiunto un provider di identità e non è possibile visualizzarlo nel portale

Dopo aver configurato un provider di identità (ad esempio, Azure AD, Azure AD B2C), è necessario ripubblicare il portale per rendere effettive le modifiche. Assicurarsi che le pagine del portale per sviluppatori includano il widget pulsanti OAuth.

La delega è stata configurata e il portale non la usa

Dopo aver configurato la delega, è necessario ripubblicare il portale per rendere effettive le modifiche.

Le altre modifiche alla configurazione di Gestione API non sono state propagate nel portale per sviluppatori

La maggior parte delle modifiche alla configurazione (ad esempio, rete virtuale, accesso, termini del prodotto) richiede la ripubblicazione del portale.

Viene visualizzato un errore CORS quando si usa la console interattiva

La console interattiva effettua una richiesta API sul lato client dal browser. Risolvere il problema CORS aggiungendo un criterio CORS nelle API o configurando il portale per l'uso di un proxy CORS. Per altre informazioni, vedere Abilitare CORS per la console interattiva nel portale per sviluppatori di Gestione API.

Viene visualizzato un errore CORS quando si usa il widget di codice HTML personalizzato

Quando si usa il widget di codice HTML personalizzato nell'ambiente, è possibile che venga visualizzato un errore CORS durante l'interazione con l'IFrame caricato dal widget. Questo problema si verifica perché il contenuto IFrame viene fornito da un'origine diversa rispetto al portale per sviluppatori. Per evitare questo problema, è invece possibile usare un widget personalizzato.

Quali autorizzazioni sono necessarie per modificare il portale per sviluppatori?

Se viene visualizzato l'errore Oops. Something went wrong. Please try again later. quando si apre il portale in modalità amministrativa, è possibile che non siano presenti le autorizzazioni necessarie (Controllo degli accessi in base al ruolo di Azure).

Il portale richiede l'autorizzazione Microsoft.ApiManagement/service/users/token/action nell'ambito /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.

È possibile usare lo script di PowerShell seguente per creare un ruolo con l'autorizzazione necessaria. Ricordarsi di modificare il parametro <subscription-id>.

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
New-AzRoleDefinition -Role $customRole 

Dopo aver creato il ruolo, questo può essere concesso a qualsiasi utente dalla sezione Controllo di accesso (IAM) nel portale di Azure. L'assegnazione di questo ruolo a un utente assegnerà l'autorizzazione nell'ambito del servizio. L'utente sarà in grado di generare token di firma di accesso condiviso per conto di qualsiasi utente del servizio. Come minimo, questo ruolo deve essere assegnato all'amministratore del servizio. Il comando di PowerShell seguente illustra come assegnare il ruolo a un utente user1 nell'ambito più basso per evitare di concedere autorizzazioni non necessarie all'utente:

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1" 

Una volta concesse le autorizzazioni all’utente, questo deve disconnettersi e accedere di nuovo al portale di Azure per rendere effettive le nuove autorizzazioni.

Viene visualizzato l'errore Unable to start the portal. See if settings are specified correctly (...)

Questo errore viene visualizzato quando una chiamata GET a https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview non riesce. La chiamata viene eseguita dal browser da parte dell'interfaccia amministrativa del portale.

Se il servizio Gestione API si trova in una rete virtuale, vedere la domanda sulla connettività della rete virtuale.

L'errore di chiamata può anche essere causato da un certificato TLS/SSL, assegnato a un dominio personalizzato e non considerato attendibile dal browser. Come mitigazione, è possibile rimuovere il dominio personalizzato dell'endpoint di gestione. Gestione API eseguirà il fallback all'endpoint predefinito con un certificato attendibile.

Qual è il supporto del browser per il portale?

¹ Supportato nelle due versioni di produzione più recenti.

Lo sviluppo locale del portale self-hosted non funziona più

Se la versione locale del portale per sviluppatori non riesce a salvare o recuperare informazioni dall'account di archiviazione o dall'istanza di Gestione API, è possibile che i token di firma di accesso condiviso siano scaduti. È possibile risolvere questo problema generando nuovi token. Per ricevere istruzioni, vedere l'esercitazione per il self-hosting del portale per sviluppatori.

Come si disabilita l'iscrizione al portale per sviluppatori?

Se non è necessaria la funzionalità di iscrizione abilitata per impostazione predefinita nel portale per sviluppatori, è possibile disabilitarla con questi passaggi:

1. Nel portale di Azure accedere all'istanza di Gestione API.

2. Nel menu del portale per sviluppatori selezionare Identità.

3. Eliminare ogni provider di identità visualizzato nell'elenco. Selezionare ogni provider, selezionare il menu di scelta rapida (...) e selezionare Elimina.

   

4. Passare all'interfaccia amministrativa del portale per sviluppatori.

5. Rimuovere i collegamenti per l’iscrizione e gli elementi di navigazione nel contenuto del portale. Per informazioni sulla personalizzazione del contenuto del portale, vedere Esercitazione: Accedere al portale per sviluppatori e personalizzarlo.

6. Modificare il contenuto della pagina di iscrizione per rimuovere i campi usati per immettere i dati di identità, nel caso in cui gli utenti passino direttamente a essa.

   Facoltativamente, eliminare la pagina di iscrizione. Attualmente si usano le API REST contentItem per elencare ed eliminare questa pagina.

7. Salvare le modifiche e ripubblicare il portale.

Come è possibile rimuovere il contenuto del portale per sviluppatori di cui è stato effettuato il provisioning nel servizio Gestione API?

Specificare i parametri necessari dello script scripts.v3/cleanup.bat nel repository GitHub del portale per sviluppatori ed eseguire lo script

cd scripts.v3
.\cleanup.bat
cd ..

Come si abilita l'autenticazione Single Sign-On (SSO) al portale per sviluppatori self-hosted?

Tra gli altri metodi di autenticazione, il portale per sviluppatori supporta l'accesso Single Sign-On (SSO). Per eseguire l'autenticazione con questo metodo, è necessario effettuare una chiamata a /signin-sso con il token nel parametro di query:

https://contoso.com/signin-sso?token=[user-specific token]

Generare token utente

È possibile generare token specifici dell'utente (inclusi i token di amministratore) usando l'operazione Ottieni token di accesso condiviso dell'API REST di Gestione API.

Contenuto correlato

Altre informazioni sul portale per sviluppatori:

• Accedere al portale per sviluppatori gestito e personalizzarlo
• Estendere la funzionalità del portale per sviluppatori.
• Configurare la versione self-hosted del portale

Esplorare altre risorse:

• Repository GitHub con il codice sorgente