Panoramica del portale per sviluppatori di gestione API di AzureAzure API Management developer portal overview

Il portale per sviluppatori è un sito Web completamente personalizzabile e completamente personalizzabile con la documentazione delle API.Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. Si tratta del punto in cui i consumer di API possono individuare le API, informazioni su come usarle, richiedere l'accesso e provarle.It is where API consumers can discover your APIs, learn how to use them, request access, and try them out.

Questo articolo descrive le differenze tra le versioni Self-Hosted e quelle gestite del portale per sviluppatori in gestione API.This article describes the differences between self-hosted and managed versions of the developer portal in API Management. Viene inoltre illustrata l'architettura e vengono fornite le risposte alle domande più frequenti.It also explains its architecture and provides answers to frequently asked questions.

Portale per sviluppatori di Gestione API

DisponibilitàAvailability

Importante

Questa funzionalità è disponibile nei livelli Premium, Standard, Basic e Developer di Gestione API.This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

Versioni gestite e self-hostedManaged and self-hosted versions

È possibile creare il portale per sviluppatori in due modi:You can build your developer portal in two ways:

  • Versione gestita : la modifica e la personalizzazione del portale, che è incorporata nell'istanza di gestione API ed è accessibile tramite l'URL <your-api-management-instance-name>.developer.azure-api.net.Managed version - by editing and customizing the portal, which is built into your API Management instance and is accessible through the URL <your-api-management-instance-name>.developer.azure-api.net. Per informazioni su come accedere e personalizzare il portale gestito, vedere questo articolo della documentazione .Refer to this documentation article to learn how to access and customize the managed portal.
  • Versione self-hosted : tramite la distribuzione e l'hosting automatico del portale all'esterno di un'istanza di gestione API.Self-hosted version - by deploying and self-hosting your portal outside of an API Management instance. Questo approccio consente di modificare la codebase del portale ed estendere la funzionalità di base fornita.This approach allows you to edit the portal's codebase and extend the provided core functionality. È anche necessario aggiornare il portale alla versione più recente.You also need to upgrade the portal to the latest version yourself. Per informazioni dettagliate e istruzioni, vedere il repository GitHub con il codice sorgente del portale.For details and instructions, refer to the GitHub repository with the source code of the portal. L' esercitazione per la versione gestita scorre il pannello amministrativo del portale, disponibile anche nella versione self-hosted.The tutorial for the managed version walks through the portal's administrative panel, which is also featured in the self-hosted version.

Concetti relativi all'architettura del portalePortal architectural concepts

I componenti del portale possono essere divisi logicamente in due categorie: codice e contenuto.The portal components can be logically divided into two categories: code and content.

Il codice viene mantenuto nel repository GitHub e include:Code is maintained in the GitHub repository and includes:

  • Widget, che rappresentano elementi visivi e combinano HTML, JavaScript, funzionalità di stile, impostazioni e mapping del contenuto.Widgets - which represent visual elements and combine HTML, JavaScript, styling ability, settings, and content mapping. Gli esempi sono un'immagine, un paragrafo di testo, un modulo, un elenco di API e così via.Examples are an image, a text paragraph, a form, a list of APIs etc.
  • Definizione dello stile, che specifica il modo in cui i widget possono essere con stileStyling definitions - which specify how widgets can be styled
  • Motore, che genera pagine Web statiche dal contenuto del portale ed è scritto in JavaScriptEngine - which generates static webpages from portal content and is written in JavaScript
  • Editor visivo, che consente la personalizzazione e la creazione in browserVisual editor - which allows for in-browser customization and authoring experience

Il contenuto è suddiviso in due sottocategorie: contenuto del portale e contenuto di gestione API.Content is divided into two subcategories: portal content and API Management content.

Il contenuto del portale è specifico del portale e include:Portal content is specific to the portal and includes:

  • Pagine, ad esempio pagina di destinazione, esercitazioni sulle API, post di BlogPages - for example, landing page, API tutorials, blog posts
  • Immagini multimediali, animazioni e altro contenuto basato su fileMedia - images, animations, and other file-based content
  • Layout: modelli, che corrispondono a un URL e definiscono la modalità di visualizzazione delle pagineLayouts - templates, which are matched against a URL and define how pages are displayed
  • Stili-valori per le definizioni di stile, ad esempio tipi di carattere, colori e bordiStyles - values for styling definitions, e.g. fonts, colors, borders
  • Impostazioni-configurazione, ad esempio favicon, metadati del sito WebSettings - configuration, e.g. favicon, website metadata

Il contenuto del portale, ad eccezione dei supporti, è espresso come documenti JSON.Portal content, except for media, is expressed as JSON documents.

Il contenuto di gestione API include entità quali API, operazioni, prodotti e sottoscrizioni.API Management content includes entities such as APIs, Operations, Products, Subscriptions.

Il portale è basato su un fork adattato del Framework Paperbits.The portal is based on an adapted fork of the Paperbits framework. La funzionalità Paperbits originale è stata estesa per fornire widget specifici di gestione API (ad esempio, un elenco di API, un elenco di prodotti) e un connettore al servizio gestione API per il salvataggio e il recupero del contenuto.The original Paperbits functionality has been extended to provide API Management-specific widgets (for example, a list of APIs, a list of Products) and a connector to API Management service for saving and retrieving content.

Domande frequentiFrequently asked questions

In questa sezione vengono riportate le risposte alle domande comuni sul nuovo portale per sviluppatori, che sono di natura generale.In this section, we answer common questions about the new developer portal, which are of general nature. Per domande specifiche per la versione self-hosted, vedere la sezione wiki del repository GitHub.For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

come è possibile eseguire la migrazione dalla versione di anteprima del portale? How can I migrate from the preview version of the portal?

Usando la versione di anteprima del portale per sviluppatori, è stato effettuato il provisioning del contenuto di anteprima nel servizio gestione API.By using the preview version of the developer portal, you provisioned the preview content in your API Management service. Il contenuto predefinito è stato modificato in modo significativo nella versione disponibile a livello generale per migliorare l'esperienza utente.The default content has been significantly modified in the generally available version for better user experience. Include anche nuovi widget.It also includes new widgets.

Se si usa la versione gestita, reimpostare il contenuto del portale facendo clic su Reimposta contenuto nella sezione del menu operazioni .If you're using the managed version, reset the content of the portal by clicking Reset content in the Operations menu section. Se si conferma questa operazione, verrà rimosso tutto il contenuto del portale ed eseguito il provisioning del nuovo contenuto predefinito.Confirming this operation will remove all the content of the portal and provision the new default content. Il motore del portale è stato aggiornato automaticamente nel servizio gestione API.The portal's engine has been automatically updated in your API Management service.

Reimposta contenuto portale

Se si usa la versione self-hosted, usare il scripts/cleanup.bat e scripts/generate.bat dal repository GitHub per rimuovere il contenuto esistente ed effettuare il provisioning di nuovo contenuto.If you're using the self-hosted version, use the scripts/cleanup.bat and scripts/generate.bat from the GitHub repository to remove existing content and provision new content. Assicurarsi di aggiornare il codice del portale alla versione più recente dal repository GitHub in anticipo.Make sure you upgrade your portal's code to the latest release from the GitHub repository beforehand.

Se non si vuole reimpostare il contenuto del portale, è possibile prendere in considerazione l'uso di widget appena disponibili in tutte le pagine.If you don't want to reset the content of the portal, you may consider using newly available widgets throughout your pages. I widget esistenti sono stati aggiornati automaticamente alle versioni più recenti.Existing widgets have been automatically updated to the latest versions.

Se il provisioning del portale è stato eseguito dopo l'annuncio della disponibilità generale, dovrebbe già presentare il nuovo contenuto predefinito.If your portal was provisioned after the general availability announcement, it should already feature the new default content. Non è richiesta alcuna azione da parte dell'utente.No action is required from your side.

Come è possibile eseguire la migrazione dal portale per sviluppatori precedente al nuovo portale per sviluppatori?How can I migrate from the old developer portal to the new developer portal?

I portali sono incompatibili ed è necessario eseguire la migrazione manuale del contenuto.Portals are incompatible and you need to migrate the content manually.

Il nuovo portale dispone di tutte le funzionalità del vecchio portale?Does the new portal have all the features of the old portal?

Il nuovo portale per sviluppatori non supporta applicazioni e problemi.The new developer portal doesn't support Applications and Issues. Se sono stati usati problemi nel portale precedente e ne sono necessari in una nuova, pubblicare un commento in un problema di GitHub dedicato.If you have used Issues in the old portal and need them in the new one, post a comment in a dedicated GitHub issue.

L'autenticazione con OAuth nella console per sviluppatori interattiva non è ancora supportata.Authentication with OAuth in the interactive developer console is not yet supported. È possibile tenere traccia dello stato di avanzamento tramite il problema di GitHub.You can track the progress through the GitHub issue.

Il portale precedente è stato deprecato?Has the old portal been deprecated?

I portali Developer e Publisher precedenti sono ora funzionalità legacy , che riceveranno solo gli aggiornamenti della sicurezza.The old developer and publisher portals are now legacy features - they will be receiving security updates only. Le nuove funzionalità verranno implementate solo nel nuovo portale per sviluppatori.New features will be implemented in the new developer portal only.

La deprecazione dei portali legacy verrà annunciata separatamente.Deprecation of the legacy portals will be announced separately. In caso di domande, problemi o commenti, è possibile generarli in un problema dedicato di GitHub.If you have questions, concerns, or comments, raise them in a dedicated GitHub issue.

Come è possibile automatizzare le distribuzioni del portale?How can I automate portal deployments?

È possibile accedere a livello di codice e gestire il contenuto del portale per sviluppatori tramite l'API REST, indipendentemente dal fatto che si usi una versione gestita o self-hosted.You can programmatically access and manage the developer portal's content through the REST API, regardless if you're using a managed or a self-hosted version.

L'API è documentata nella sezione wiki del repository GitHub.The API is documented in the GitHub repository's wiki section. Può anche essere usato per automatizzare le migrazioni di contenuto del portale tra ambienti, ad esempio da un ambiente di test all'ambiente di produzione.It can also be used for automating migrations of portal content between environments - for example from a test environment to the production environment. Altre informazioni su questo processo sono disponibili in questo articolo della documentazione su GitHub.You can learn more about this process in this documentation article on GitHub.

Il portale supporta i modelli di Azure Resource Manager e/o è compatibile con gestione API DevOps Resource Kit?Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?

No.No.

È necessario abilitare la connettività VNet aggiuntiva per le nuove dipendenze del portale gestito?Do I need to enable additional VNet connectivity for the new managed portal dependencies?

Nella maggior parte dei casi-no.In most cases - no.

Se il servizio gestione API si trova in una VNet interna, il portale per sviluppatori è accessibile solo dall'interno della rete.If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. 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.The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. Assicurarsi che l'endpoint di gestione sia registrato nel DNS.Make sure the management endpoint is registered in the DNS. In caso di errata configurazione, verrà visualizzato un errore: Unable to start the portal. See if settings are specified correctly in the configuration (...).In case of misconfiguration, you will see an error: Unable to start the portal. See if settings are specified correctly in the configuration (...).

Ho assegnato un dominio personalizzato di gestione API e il portale pubblicato non funzionaI have assigned a custom API Management domain and the published portal doesn't work

Dopo aver aggiornato il dominio, per rendere effettive le modifiche è necessario ripubblicare il portale .After you update the domain, you need to republish the portal for the changes to take effect.

È stato aggiunto un provider di identità e non è possibile visualizzarlo nel portaleI have added an identity provider and I can't see it in the portal

Dopo aver configurato un provider di identità (ad esempio, AAD, AAD B2C), è necessario ripubblicare il portale per rendere effettive le modifiche.After you configure an identity provider (for example, AAD, AAD B2C), you need to republish the portal for the changes to take effect.

Ho configurato la delega e il portale non lo usaI have set up delegation and the portal doesn't use it

Dopo aver configurato la delega, è necessario ripubblicare il portale per rendere effettive le modifiche.After you set up delegation, you need to republish the portal for the changes to take effect.

Le altre modifiche di configurazione di gestione API non sono state propagate nel portale per sviluppatoriMy other API Management configuration changes haven't been propagated in the developer portal

Per la maggior parte delle modifiche di configurazione, ad esempio VNet, accesso e termini del prodotto, è necessario ripubblicare il portale.Most configuration changes (for example, VNet, sign-in and product terms) require republishing the portal.

Viene ricevuto un errore CORS quando si usa la console interattivaI'm getting a CORS error when using the interactive console

La console interattiva esegue una richiesta API sul lato client dal browser.The interactive console makes a client-side API request from the browser. È possibile risolvere il problema CORS aggiungendo un criterio CORS sulle API.You can resolve the CORS problem by adding a CORS policy on your API(s). È possibile specificare tutti i parametri manualmente o usare i valori dei caratteri jolly *.You can specify all the parameters manually or use wildcard * values. Ad esempio:For example:

<cors>
    <allowed-origins>
        <origin>*</origin>
    </allowed-origins>
    <allowed-methods>
        <method>GET</method>
        <method>POST</method>
        <method>PUT</method>
        <method>DELETE</method>
        <method>HEAD</method>
        <method>OPTIONS</method>
        <method>PATCH</method>
        <method>TRACE</method>
    </allowed-methods>
    <allowed-headers>
        <header>*</header>
    </allowed-headers>
    <expose-headers>
        <header>*</header>
    </expose-headers>
</cors>

Nota

Se si applicano i criteri CORS nell'ambito del prodotto, invece dell'ambito delle API e l'API usa l'autenticazione con chiave di sottoscrizione tramite un'intestazione, la console non funzionerà.If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.

Il browser rilascia automaticamente una richiesta HTTP OPTIONS, che non contiene un'intestazione con la chiave di sottoscrizione.The browser automatically issues an OPTIONS HTTP request, which doesn’t contain a header with the subscription key. A causa della chiave di sottoscrizione mancante, gestione API non può associare la chiamata OPTIONS a un prodotto, quindi non può applicare i criteri CORS.Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can’t apply the CORS policy.

Come soluzione alternativa è possibile passare la chiave della sottoscrizione in un parametro di query.As a workaround you can pass the subscription key in a query parameter.

Quali autorizzazioni sono necessarie per modificare il portale per sviluppatori?What permissions do I need to edit the developer portal?

Se viene visualizzato l'errore Oops. Something went wrong. Please try again later. quando si apre il portale in modalità amministrativa, potrebbero mancare le autorizzazioni necessarie (RBAC).If you're seeing the Oops. Something went wrong. Please try again later. error when you open the portal in the administrative mode, you may be lacking the required permissions (RBAC).

I portali legacy hanno richiesto l'autorizzazione Microsoft.ApiManagement/service/getssotoken/action nell'ambito del servizio (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) per consentire all'amministratore utente di accedere ai portali.The legacy portals required the permission Microsoft.ApiManagement/service/getssotoken/action at the service scope (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) to allow the user administrator access to the portals. Il nuovo 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.The new portal requires the permission Microsoft.ApiManagement/service/users/token/action at the scope /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.You can use the following PowerShell script to create a role with the required permission. Ricordarsi di modificare il parametro <subscription-id>.Remember to change the <subscription-id> parameter.

#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 

Una volta creato, il ruolo può essere concesso a qualsiasi utente dalla sezione controllo di accesso (IAM) nel portale di Azure.Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. Assegnando questo ruolo a un utente, verrà assegnata l'autorizzazione nell'ambito del servizio.Assigning this role to a user will assign the permission at the service scope. L'utente sarà in grado di generare token SAS per conto di qualsiasi utente nel servizio.The user will be able to generate SAS tokens on behalf of any user in the service. Come minimo, questo ruolo deve essere assegnato all'amministratore del servizio.At the minimum, this role needs to be assigned to the administrator of the service. 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:The following PowerShell command demonstrates how to assign the role to a user user1 at the lowest scope to avoid granting unnecessary permissions to the user:

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" 

Dopo che le autorizzazioni sono state concesse a un utente, l'utente deve disconnettersi e accedere di nuovo al portale di Azure per rendere effettive le nuove autorizzazioni.After the permissions have been granted to a user, the user must sign out and sign in again to the Azure portal for the new permissions to take effect.

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

Questo errore viene visualizzato quando una chiamata GET https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview ha esito negativo.This error is shown when a GET call to https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview fails. La chiamata viene eseguita dal browser dall'interfaccia amministrativa del portale.The call is issued from the browser by the administrative interface of the portal.

Se il servizio gestione API si trova in una VNet, vedere la domanda di connettività VNet precedente.If your API Management service is in a VNet - refer to the VNet connectivity question above.

L'errore di chiamata può anche essere causato da un certificato SSL, che viene assegnato a un dominio personalizzato e non è considerato attendibile dal browser.The call failure may also be caused by an SSL certificate, which is assigned to a custom domain and is not trusted by the browser. Come mitigazione, è possibile rimuovere l'endpoint di gestione. gestione API del dominio personalizzato esegue il fallback all'endpoint predefinito con un certificato attendibile.As a mitigation, you can remove the management endpoint custom domain - API Management will fall back to the default endpoint with a trusted certificate.

Passaggi successiviNext steps

Altre informazioni sul nuovo portale per sviluppatori:Learn more about the new developer portal:

Esplora altre risorse:Browse other resources: