Condividi tramite

Ospitare in modalità self-host il portale di Centro API

  • Articolo

Questo articolo presenta il portale del Centro API, un sito Web che gli sviluppatori e altri stakeholder dell'organizzazione possono usare per individuare le API nel centro API. Distribuire un'implementazione di riferimento del portale dal repository iniziale del portale di Centro API.

Screenshot del portale di Centro API dopo l'accesso dell'utente.

Informazioni sul portale di Centro API

Il portale di Centro API è un sito Web che è possibile compilare e ospitare per visualizzare l'inventario API nel centro API. Il portale consente agli sviluppatori e ad altri stakeholder dell'organizzazione di individuare le API e visualizzare i dettagli dell'API.

È possibile compilare e distribuire un'implementazione di riferimento del portale usando il codice nel repository iniziale del portale di Centro API. Il portale usa l'API del piano dati di Centro API di Azure per recuperare i dati dal centro API. L'accesso utente alle informazioni sulle API si basa sul controllo degli accessi in base al ruolo di Azure.

L'implementazione di riferimento del portale di Centro API fornisce:

  • Framework per la pubblicazione e la gestione di un portale API gestito dal cliente tramite GitHub Actions
  • Piattaforma del portale che i clienti possono modificare o estendere per soddisfare le proprie esigenze
  • Flessibilità per ospitare infrastrutture diverse, tra cui la distribuzione a servizi come App Web statiche di Azure.

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.

  • Per compilare e distribuire il portale, è necessario un account GitHub e gli strumenti seguenti installati nel computer locale:

Creare la registrazione dell'app Microsoft Entra

Configurare prima di tutto 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.

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

  2. Seleziona + Nuova registrazione.

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

    • Impostare Nome su un nome significativo, ad esempio api-center-portal

    • In Tipi di account supportati selezionare Account in questa directory organizzativa (tenant singolo).

    • In URI di reindirizzamento selezionare Applicazione a pagina singola (SPA) e impostare l'URI.

      • Per i test locali, impostare l'URI su https://localhost:5173.
      • Per la produzione, impostare l'URI sull'URI della distribuzione del portale di Centro API.

    • Selezionare Registra.

  4. Nella pagina Panoramica copiare l'ID applicazione (client) e l'IDdirectory (tenant). Questi valori vengono impostati quando si compila il portale.

  5. Nella pagina Autorizzazioni API selezionare + Aggiungi un'autorizzazione.

    1. Nella pagina Richiedi autorizzazioni API selezionare la scheda API usate dall'organizzazione. Cercare e selezionare Centro API di Azure. È anche possibile cercare e selezionare l'ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573applicazione .
    2. Nella pagina Richiedi autorizzazioni selezionare user_impersonation.
    3. Selezionare Aggiungi autorizzazioni.

    Le autorizzazioni del Centro API di Azure vengono visualizzate in Autorizzazioni configurate.

    Screenshot delle autorizzazioni necessarie nella registrazione dell'app Microsoft Entra ID nel portale.

Configurare l'ambiente locale

Seguire questa procedura per compilare e testare il portale del Centro API in locale.

  1. Clonare il repository iniziale del portale di Centro API nel computer locale.

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. Passare alla APICenter-Portal-Starter directory.

    cd APICenter-Portal-Starter

  3. Eseguire il checkout del ramo main.

    git checkout main

  4. Per configurare il servizio, copiare o rinominare il public/config.example file in public/config.json.

  5. Modificare quindi il public/config.json file in modo che punti al servizio. Aggiornare i valori nel file come indicato di seguito:

    • Sostituire <service name> e <region> con il nome del centro API e l'area in cui è distribuita
    • Sostituire <client ID> e <tenant ID> con l'ID applicazione (client) e l'ID directory (tenant) della registrazione dell'app creata nella sezione precedente.
    • Aggiornare il valore di title in un nome che si desidera visualizzare nel portale.
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. Installare i pacchetti necessari.

    npm install

  7. Avviare il server di sviluppo. Il comando seguente avvierà il portale in modalità di sviluppo in esecuzione in locale:

    npm start

    Passare al portale all'indirizzo https://localhost:5173.

Distribuzione in Azure

Per la procedura per distribuire il portale in App Web statiche di Azure, vedere il repository iniziale del portale del Centro API.

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

Gli utenti devono accedere per visualizzare le API nel centro API. Per abilitare l'accesso, assegnare il ruolo lettore dati di Centro API di Azure a utenti o gruppi nell'organizzazione, con ambito al centro API.

Importante

Per impostazione predefinita, l'utente e altri amministratori del Centro API non hanno accesso alle API nel portale di Centro API. Assicurarsi di assegnare il ruolo lettore dati di Centro API di Azure a se stessi e ad altri amministratori.

Per i prerequisiti e i passaggi dettagliati per assegnare un ruolo a utenti e gruppi, vedere Assegnare ruoli di Azure usando il portale di Azure. Per brevi passaggi, seguire questa procedura:

  1. Nella portale di Azure passare al centro API.
  2. Nel menu a sinistra selezionare Controllo di accesso (IAM)>+ Aggiungi assegnazione di ruolo.
  3. Nel riquadro Aggiungi assegnazione di ruolo impostare i valori come segue:
    • Nella pagina Ruolo cercare e selezionare Lettore dati del Centro API di Azure. Selezionare Avanti.
    • Nella pagina Membri, in Assegna accesso a, selezionare Utente, gruppo o entità> servizio+ Seleziona membri.
    • 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.
    • Esaminare l'assegnazione di ruolo e selezionare Rivedi e assegna.

Nota

Per semplificare la configurazione di accesso per i nuovi utenti, è consigliabile assegnare il ruolo a un gruppo Microsoft Entra e configurare una regola di appartenenza dinamica ai gruppi. Per altre informazioni, vedere Creare o aggiornare un gruppo dinamico in Microsoft Entra ID.

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

Nota

Al primo utente di accedere al portale viene richiesto di fornire il consenso alle autorizzazioni richieste dalla registrazione dell'app del portale del Centro API. Successivamente, agli altri utenti configurati non viene richiesto di fornire il consenso.

Risoluzione dei problemi

Errore: "Non si è autorizzati ad accedere a questo portale"

In determinate condizioni, un utente potrebbe riscontrare il messaggio di errore seguente dopo l'accesso al portale di Centro API con un account utente configurato:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Prima di tutto, verificare che all'utente sia assegnato il ruolo Lettore dati di Centro API di Azure nel centro API.

Se all'utente viene assegnato il ruolo, potrebbe verificarsi un problema con la registrazione del provider di risorse Microsoft.ApiCenter nella sottoscrizione e potrebbe essere necessario registrare nuovamente il provider di risorse. A tale scopo, eseguire il comando seguente nell'interfaccia della riga di comando di Azure:

az provider register --namespace Microsoft.ApiCenter

Impossibile accedere al portale

Se gli utenti a cui è stato assegnato il ruolo lettore dati di Centro API di Azure non possono completare il flusso di accesso dopo aver selezionato Accedi nel portale di Centro API, potrebbe verificarsi un problema con la configurazione del provider di identità Microsoft Entra ID.

Nella registrazione dell'app Microsoft Entra rivedere e, se necessario, aggiornare le impostazioni URI di reindirizzamento per assicurarsi che l'URI corrisponda all'URI della distribuzione del portale del Centro API.

Impossibile selezionare le autorizzazioni del Centro API di Azure nella registrazione dell'app Microsoft Entra

Se non è possibile richiedere le autorizzazioni API al Centro API di Azure nella registrazione dell'app Microsoft Entra per il portale del Centro API, verificare di cercare Centro API di Azure (o ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573applicazione).

Se l'app non è presente, potrebbe verificarsi un problema con la registrazione del provider di risorse Microsoft.ApiCenter nella sottoscrizione. Potrebbe essere necessario registrare nuovamente il provider di risorse. A tale scopo, eseguire il comando seguente nell'interfaccia della riga di comando di Azure:

az provider register --namespace Microsoft.ApiCenter

Dopo aver riregistrato il provider di risorse, riprovare a richiedere le autorizzazioni API.

Criteri di supporto

Fornire commenti e suggerimenti, richiedere funzionalità e ottenere supporto per l'implementazione di riferimento del portale di Centro API nel repository di avvio del portale di Centro API.

Contenuto correlato