Configurare e personalizzare il portale di Centro API

Questo articolo illustra come configurare e personalizzare il portale del Centro API (anteprima), un sito Web gestito da Azure per l'individuazione di API, server MCP e asset correlati nel centro API.

Il portale di Centro API supporta e semplifica il lavoro degli sviluppatori che usano e creano API all'interno dell'organizzazione. Gli utenti con accesso possono:

• Cercare le API in base al nome o usare la ricerca semantica assistita da intelligenza artificiale.
• Filtrare le API in base al tipo o alla fase del ciclo di vita.
• Visualizzare i dettagli e le definizioni dell'API , inclusi endpoint, metodi, parametri e formati di risposta.
• Scaricare le definizioni api nel computer o aprirle in Visual Studio Code.
• Provare le API con la chiave API o l'autenticazione OAuth 2.0.

Prerequisiti

• Un centro API nella sottoscrizione di Azure. Se non ne è già stato creato uno, vedere Avvio rapido: Creare il centro API.

• Autorizzazioni per creare una registrazione dell'app in un tenant di Microsoft Entra associato alla sottoscrizione di Azure e autorizzazioni per concedere l'accesso ai dati nel centro API.

Configurare l'accesso al portale di Centro API

Scegliere prima di tutto come si vuole che gli utenti acceutino al portale del Centro API. È possibile configurare Microsoft Entra ID come provider di identità o consentire l'accesso anonimo.

Opzione 1: Configurare l'autenticazione dell'ID Entra di Microsoft per il portale (scelta consigliata)

Per configurare Microsoft Entra ID come provider di identità, configurare innanzitutto una registrazione dell'app nel tenant di Microsoft Entra ID. La registrazione dell'app consente al portale di Centro API di accedere ai dati dal centro API per conto di un utente connesso.

Il Centro API può configurare automaticamente la registrazione dell'app oppure è possibile creare manualmente la registrazione dell'app.

Configurare automaticamente la registrazione dell'app (scelta consigliata)

Per configurare automaticamente la registrazione dell'app, seguire questa procedura:

1. Nel portale di Azure passare al centro API.

2. Nel menu della barra laterale selezionare Impostazioni del portale> del Centro API.

3. Nella scheda Accesso selezionare Configura ID Entra.

4. Nella pagina Configura l'accesso utente con Microsoft Entra IDselezionare Configura.

5. Nella scheda Accesso selezionare Salva e pubblica.

Se è necessario accedere alla registrazione dell'app in un secondo momento, è possibile trovarla nel portale in Registrazioni app. L'applicazione viene denominata con il formato seguente: <api-center-name-apic-aad>.

Configurare manualmente la registrazione dell'app

Per creare manualmente la registrazione dell'app, seguire questa procedura:

1. Nel portale di Azure passare a Microsoft Entra ID>Gestisci>registrazioni app.

2. Seleziona + Nuova registrazione.

3. Nella pagina Registra un'applicazione impostare i valori come segue:

   1. Impostare Nome su un nome significativo, ad esempio api-center-portal
   2. In Tipi di account supportati selezionare Account solo in questa directory organizzativa (<Nome directory> - Tenant singolo).
   3. In URI di reindirizzamento selezionare Applicazione a pagina singola (SPA) e impostare l'URI. Immettere l'URI della distribuzione del portale di Centro API nel formato seguente: https://<service-name>.portal.<location>.azure-apicenter.ms. Sostituire <service name> e <location> con il nome del centro API e la posizione in cui è distribuita, ad esempio: https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. Selezionare Registra.

Configurare URI di reindirizzamento aggiuntivi per l'estensione di VS Code

Quando si abilita la visualizzazione del portale di Centro API nell'estensione Visual Studio Code per Centro API, configurare anche gli URI di reindirizzamento seguenti nella registrazione dell'app:

1. Nel portale di Azure passare alla registrazione dell'app.

2. Nella pagina Gestisci>autenticazione selezionare Aggiungi una piattaforma e selezionare Applicazioni per dispositivi mobili e desktop.

3. Configurare i tre URI di reindirizzamento personalizzati seguenti:
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   Sostituire <application-client-id> con l'ID applicazione (client) dell'app. È possibile trovare questo valore nella pagina Panoramica della registrazione dell'app.

Opzione 2: Consentire l'accesso anonimo al portale

Per abilitare l'accesso anonimo, seguire questa procedura.

1. Nel portale di Azure passare al centro API.

2. Nel menu della barra laterale selezionare Impostazioni del portale> del Centro API.

3. Nella scheda Accesso selezionare Consenti accesso anonimo.

   

4. Per configurare l'accesso, selezionare Conferma e Abilita.

Visualizzare il portale

Dopo aver configurato l'accesso, aprire il portale di Centro API selezionando Visualizza portale del Centro API nella pagina Impostazioni oppure visitare:
https://<service-name>.portal.<location>.azure-apicenter.ms

Sostituire <service-name> e <location> con il nome e il percorso di distribuzione del centro API.

Per impostazione predefinita, la home page del portale è raggiungibile pubblicamente. Se Microsoft Entra ID è configurato per l'accesso, gli utenti devono selezionare Accedi per accedere alle API. Per informazioni dettagliate sulla configurazione dell'accesso utente, vedere Abilitare l'accesso al portale da parte di utenti e gruppi di Microsoft Entra .

Abilitare l'accesso al portale da parte di utenti e gruppi di Microsoft Entra

Quando Microsoft Entra ID è configurato per l'accesso al portale, gli utenti devono accedere al portale di Centro API per accedere alle API. Per abilitare l'accesso, assegnare il ruolo Lettore Dati di Centro API di Azure a utenti o gruppi nell'organizzazione, limitatamente al centro API.

Per i prerequisiti e i passaggi dettagliati per assegnare un ruolo a utenti e gruppi, vedere Assegnare ruoli di Azure tramite il portale di Azure. Brevi passaggi sotto:

1. Nel portale di Azure passare al centro API.
2. Nel menu della barra laterale selezionare Controllo di accesso (IAM)>+ Aggiungi assegnazione di ruolo.
3. Nel riquadro Aggiungi assegnazione di ruolo impostare i valori come segue:
   1. Nella pagina Ruolo cercare e selezionare Lettore dati del Centro API di Azure. Seleziona Avanti.
   2. Nella pagina membri, in Assegna accesso a, selezionare Utente, gruppo o entità servizio> + Seleziona membri.
   3. Nella pagina Seleziona membri cercare e selezionare gli utenti o i gruppi a cui assegnare il ruolo. Fare clic su Seleziona e quindi su Avanti.
   4. Rivedere l'assegnazione di ruolo e selezionare Rivedi + Assegna.

Dopo aver configurato l'accesso al portale, gli utenti possono accedere al portale e visualizzare le API nel centro API.

Personalizzare il portale di Centro API

Le sezioni seguenti illustrano come personalizzare l'esperienza del portale del Centro API per gli utenti. Per una personalizzazione più completa, è anche possibile scegliere di ospitare autonomamente il portale di Centro API.

Profilo sito

Nella scheda Profilo sito delle impostazioni del portale del Centro API specificare facoltativamente un nome personalizzato da visualizzare nella barra superiore del portale.

Visibilità dell'API

Nella scheda Visibilità controllare quali API sono individuabili (visibili) agli utenti del portale del Centro API. Le impostazioni di visibilità si applicano a tutti gli utenti del portale di Centro API.

Per rendere visibili solo API specifiche, aggiungere condizioni di filtro per le API in base alle proprietà predefinite. Ad esempio, visualizzare le API solo di determinati tipi, ad esempio REST o GraphQL, o in base a determinati formati di specifica, ad esempio OpenAPI.

Ricerca semantica

Se si abilita la ricerca semantica nella scheda Ricerca semantica , il portale del Centro API integra la ricerca api basata sui nomi di base con la ricerca semantica assistita dall'intelligenza artificiale basata su nomi API, descrizioni e metadati facoltativamente personalizzati. La ricerca semantica è disponibile solo nel piano Standard .

Gli utenti possono cercare API usando query in linguaggio naturale per trovare LE API in base alla finalità. Ad esempio, se uno sviluppatore cerca "Ho bisogno di un'API per la gestione dell'inventario", il portale può suggerire API pertinenti, anche se i nomi o le descrizioni API non includono queste parole esatte.

Per usare la ricerca assistita dall'intelligenza artificiale quando è stato eseguito l'accesso al portale di Centro API, selezionare la casella di ricerca, scegliere Cerca con intelligenza artificiale e immettere una query.

Metadati personalizzati

Nella scheda Metadati selezionare facoltativamente le proprietà dei metadati personalizzate che si desidera esporre nei dettagli dell'API e nella ricerca semantica.

Abilitare l'accesso alla console di test per le API

È possibile configurare le impostazioni utente per autorizzare in modo granulare l'accesso alle API e alle versioni specifiche nel centro API. Ad esempio, configurare determinate versioni api per usare le chiavi API per l'autenticazione e creare criteri di accesso che consentano a utenti specifici di eseguire l'autenticazione usando tali chiavi.

I criteri di accesso si applicano anche alla funzionalità "Prova questa API" per le API nel portale di Centro API, assicurando che solo gli utenti del portale con i criteri di accesso appropriati possano usare la console di test per tali versioni dell'API. Altre informazioni sull'autorizzazione dell'accesso alle API.

Portale di Gestione API e Centro API

I servizi Gestione API di Azure e Centro API di Azure forniscono entrambi i portali per gli sviluppatori per individuare e usare le API:

• Il portale per sviluppatori di Gestione API consente agli utenti di trovare API gestite (inclusi i gruppi di API gestite come prodotti), informazioni su come usarle, richiedere l'accesso e testarle.
• Il portale di Centro API (anteprima) è un portale multigateway in cui gli utenti possono individuare e filtrare l'inventario API completo dell'organizzazione.

Anche se i due portali condividono alcune funzionalità, presentano anche differenze distinte. Nella tabella seguente vengono confrontate le funzionalità correnti per determinare il portale da usare. Alcune organizzazioni potrebbero preferire un portale, mentre altre potrebbero richiedere entrambe.

¹ Il portale del Centro API può contenere tutte le API dell'organizzazione, incluse quelle gestite in Gestione API di Azure e altre piattaforme, nonché API e API non gestite in fase di sviluppo.

Contenuti correlati

• Abilitare e visualizzare il portale del Centro API di Azure in Visual Studio Code
• Ospitare in modalità self-host il portale di Centro API