Individuazione e utilizzo delle API
L'individuazione e l'utilizzo delle API sono una parte importante dell'uso delle API in un'organizzazione.
In questa unità si vedrà in che modo l'estensione Centro API in VS Code consente di individuare e usare facilmente le API.
Prerequisiti
Per gestire le API tramite l'estensione Centro API in VS Code, è necessario:
- Installare Visual Studio Code
- Installare l'estensione Centro API
Le estensioni di Visual Studio Code seguenti sono facoltative e necessarie solo per determinati scenari, come indicato:
- Estensione client REST: per inviare richieste HTTP e visualizzare direttamente le risposte in Visual Studio Code.
- Estensione Microsoft Kiota: per generare client API.
Individuazione e utilizzo delle API
È possibile visualizzare il catalogo API dell'organizzazione direttamente in Visual Studio Code, con tutte le API, le versioni, le definizioni, gli ambienti e le distribuzioni. A una prima occhiata, si ottiene immediatamente una panoramica di tutte le API disponibili all'interno dell'organizzazione.
Ma cosa succede se l'organizzazione ha centinaia o migliaia di API? Nessun problema, poiché è possibile cercare le API tramite l'icona di ricerca, come illustrato di seguito.
Visualizzare la documentazione relativa alle API
È anche possibile ottenere rapidamente l’accesso e visualizzare in anteprima la documentazione dell'API e i test dell'endpoint per le API in VS Code.
- Aprire l'estensione Centro API dalla scheda.
- Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.
- Fare clic con il pulsante destro del mouse sulla definizione e selezionare Apri documentazione API.
- Viene visualizzata una nuova scheda con l'interfaccia utente di Swagger per la definizione dell'API.
- Selezionare un endpoint, quindi selezionare Prova, specificare i parametri necessari e scegliere Esegui.
Provare le API
Con l'estensione Centro API è possibile visualizzare un file .http basato sulla definizione dell'API fornita nel Centro API. In questo file è possibile inviare direttamente richieste HTTP e visualizzare le risposte direttamente nell'editor.
Nota
Per usare questa funzionalità, è necessario installare l'estensione Client REST.
- Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.
- Fare clic con il pulsante destro del mouse sulla definizione e scegliere Genera file HTTP.
- Viene visualizzata una nuova scheda che esegue il rendering di un documento .http popolato dalla specifica dell'API.
- Per effettuare una richiesta, selezionare un endpoint e selezionare Invia richiesta.
Generare SDK
L'estensione Centro API usa anche Microsoft Kiota per generare un client per l'API REST HTTP per il linguaggio preferito, come definito nella specifica OpenAPI. In questo modo è possibile generare immediatamente i client per tutti gli endpoint o per quelli selezionati per l'API, per soddisfare le esigenze aziendali.
Nota
Per usare questa funzionalità, è necessario installare l'estensione Microsoft Kiota.
Espandere la visualizzazione della struttura ad albero del Centro API per visualizzare una definizione API.
Fare clic con il pulsante destro del mouse sulla definizione e scegliere Genera Client API. Viene visualizzato il riquadro Kiota OpenAPI Generator.
Selezionare gli endpoint API e le operazioni HTTP da includere negli SDK. È possibile passare il puntatore del mouse su un endpoint e selezionare il pulsante '+' per aggiungerlo o '-' per rimuoverlo.
Al termine, selezionare il pulsante "Play" per generare il client API.
Selezionare Genera client API.
a. Immettere i dettagli di configurazione relativi al nome dell'SDK, allo spazio dei nomi e alla directory di output.
b. Selezionare la lingua per l'SDK generato.
Portale di Centro API self-hosted
Il portale di Centro API è un sito web che consente agli sviluppatori e alle parti interessate di individuare e interagire facilmente con le API nell'inventario API. Con questo sito web self-hosted, le organizzazioni offrono agli utenti un'esperienza di individuazione e utilizzo di API basata sul web.
I tecnici della piattaforma API vogliono una posizione centralizzata e autonoma per tutti i consumer di API, sia interni che esterni. Per iniziare, è possibile usare il modello di avvio del portale di Centro API seguendo questa procedura:
Nota
Le istruzioni seguenti riguardano la distribuzione in App Web statiche di Azure, ma è possibile eseguire la distribuzione nell'infrastruttura preferita.
Creare una copia tramite fork del codice di implementazione di riferimento del Centro API.
Creare una risorsa App Web statiche in Azure.
In Dettagli distribuzione, selezionare GitHub come origine e indirizzare al repository contenente il codice di avvio di Centro API.
App Web statiche rileverà i set di impostazioni di compilazione e li popolerà con React.
Immettere / come percorso dell'app.
Immettere dist come percorso di output.
Seleziona Crea.
Potrebbero essere necessari fino a 5 minuti per visualizzare il codice pubblicato nel sito web.
Per visualizzare il portale di Centro API in esecuzione in App Web statiche, selezionare Visualizza app nel browser dalla scheda Panoramica nella risorsa App Web statica creata nel portale di Azure.
Configurazione del controllo degli accessi in base al ruolo
Gli amministratori hanno il controllo completo dell'assegnazione delle autorizzazioni per accedere alle API e agli asset all'interno del Centro API dell'organizzazione con il controllo degli accessi in base al ruolo.
Nota
Per impostazione predefinita, gli amministratori di Centro API non hanno accesso alle API nel portale di Centro API. Assicurarsi di assegnare il ruolo di lettore dati di Centro API di Azure a se stessi e ad altri amministratori.
Per accedere alle API in Centro API, gli utenti devono accedere al portale e devono avere le autorizzazioni necessarie, appartenenti al Centro API. Per abilitare l'accesso, assegnare il ruolo di lettore dati di Centro API di Azure a utenti o gruppi nell'organizzazione, seguendo i passaggi descritti qui.