Abilitare e visualizzare il catalogo api della piattaforma del Centro API di Azure

Questo articolo illustra come fornire agli sviluppatori aziendali l'accesso al catalogo API della piattaforma del Centro API di Azure (anteprima) nell'estensione Visual Studio Code per Centro API di Azure. Usando il catalogo API della piattaforma, gli sviluppatori possono individuare le API nel centro API di Azure, visualizzare le definizioni delle API e, facoltativamente, generare client API quando non hanno accesso per gestire il centro API stesso o aggiungere API all'inventario. L'accesso al catalogo API della piattaforma viene gestito usando l'ID Microsoft Entra e il controllo degli accessi in base al ruolo di Azure.

Prerequisiti

Per gli amministratori del Centro API

• 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 sviluppatori di app

• Estensione Centro API di Azure per Visual Studio Code

  Importante

  Attualmente, l'accesso al catalogo API della piattaforma è disponibile solo nella versione non definitiva dell'estensione. Quando si installa l'estensione dal Marketplace di Visual Studio Code, è possibile scegliere di installare la versione di rilascio o una versione non definitiva. È possibile passare da una versione all'altra in qualsiasi momento usando il menu di scelta rapida Gestisci dell'estensione nella visualizzazione Estensioni.

L'estensione di Visual Studio Code seguente è facoltativa:

• Estensione Microsoft Kiota: per generare client API

Passaggi per gli amministratori del Centro API per abilitare l'accesso al catalogo

Le sezioni seguenti illustrano i passaggi per consentire agli amministratori del Centro API di consentire agli sviluppatori aziendali di accedere al catalogo api della piattaforma.

Creare la registrazione dell'app Microsoft Entra

Prima di tutto, configurare una registrazione dell'app nel tenant di Microsoft Entra ID. La registrazione dell'app consente all'estensione di Visual Studio Code per Centro API di Azure di accedere al catalogo API della piattaforma per conto di un utente connesso.

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

2. Selezionare + Nuova registrazione.

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

   • Impostare Name su un nome significativo, ad esempio platform-api-catalog
   • In Tipi di account supportati selezionare Account in questa directory organizzativa (tenant singolo).
   • In URI di reindirizzamento selezionare Applicazione a pagina singola e impostare l'URI sull'URI di runtime del centro API. Ad esempio: https://<service name>.data.<region>.azure-apicenter.ms. Esempio: https://contoso-apic.data.eastus.azure-apicenter.ms.
   • Selezionare Registra.

   Suggerimento

   È possibile usare la stessa registrazione dell'app per accedere a più centri API. In URI di reindirizzamento continuare ad aggiungere URI di reindirizzamento per altri centri API da visualizzare nel catalogo api della piattaforma.

4. Nella pagina Panoramica copiare l'ID applicazione (client) e l'ID directory (tenant). Questi valori vengono impostati in un secondo momento quando ci si connette al centro API dall'estensione di Visual Studio Code.

5. Nel menù a sinistra, in Gestisci, selezionare Autenticazione>+ Aggiungi una piattaforma.

6. Nella pagina Configura piattaforme selezionare Applicazioni per dispositivi mobili e desktop.

7. Nella pagina Configura desktop e dispositivi immettere l'URI di reindirizzamento seguente e selezionare Configura:

   https://vscode.dev/redirect

8. Nel menu a sinistra, in Gestisci, selezionare Autorizzazioni> API+ Aggiungi un'autorizzazione.

9. Nella pagina Richiedi autorizzazioni API eseguire le operazioni seguenti:

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

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

   

Abilitare l'accesso al catalogo API della piattaforma da parte di utenti e gruppi di Microsoft Entra

Gli sviluppatori aziendali devono accedere con un account Microsoft per visualizzare il catalogo api della piattaforma per il centro API. Se necessario, aggiungere o invitare sviluppatori al tenant di Microsoft Entra.

Quindi, per abilitare l'accesso, assegnare il ruolo lettore dati di Centro API di Azure a utenti o gruppi nel tenant, con ambito al centro API.

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. Nel portale di Azure andare 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.
4. Ripetere i passaggi precedenti per abilitare l'accesso al catalogo API della piattaforma per più centri API.

Passaggi per gli sviluppatori aziendali per accedere al catalogo api della piattaforma

Gli sviluppatori possono seguire questi passaggi per connettersi e accedere per visualizzare un catalogo API della piattaforma usando l'estensione Visual Studio Code. Le impostazioni per la connessione al centro API devono essere fornite dall'amministratore del Centro API.

Connettersi a un centro API

1. Installare la versione non definitiva dell'estensione Centro API di Azure per Visual Studio Code per Visual Studio Code.

2. In Visual Studio Code, nella barra delle attività a sinistra selezionare Centro API.

   

3. Usare il tasto di scelta rapida CTRL+MAIUSC+P per aprire il riquadro comandi. Digitare Centro API di Azure: connettersi a un Centro API e premere INVIO.

4. Rispondere alle richieste di immettere le informazioni seguenti:

   1. L'URL di runtime del centro API, nel formato <service name>.data.<region>.azure-apicenter.ms (non anteporre il prefisso con https://). Esempio: contoso-apic.data.eastus.azure-apicenter.ms. Questo URL di runtime viene visualizzato nella pagina Panoramica del centro API nel portale di Azure.
   2. ID applicazione (client) dalla registrazione dell'app configurata dall'amministratore nella sezione precedente.
   3. ID della directory (tenant) dalla registrazione dell'app configurata dall'amministratore nella sezione precedente.

   Suggerimento

   Un amministratore del Centro API deve fornire questi dettagli di connessione agli sviluppatori o fornire un collegamento diretto nel formato seguente:
   vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

   Dopo la connessione al centro API, il nome del centro API viene visualizzato nel catalogo api della piattaforma del Centro API.

5. Per visualizzare le API nel centro API, sotto il nome del centro API selezionare Accedi ad Azure. L'accesso è consentito con un account Microsoft a cui è assegnato il ruolo lettore dati di Centro API di Azure nel centro API.

   

6. Dopo l'accesso, selezionare API per elencare le API nel Centro API. Espandere un'API per esplorare le relative versioni e definizioni.

   

7. Ripetere i passaggi precedenti per connettersi a più centri API, se è configurato l'accesso.

Individuare e usare le API nel catalogo

Il catalogo API della piattaforma consente agli sviluppatori aziendali di individuare i dettagli dell'API e avviare lo sviluppo di client API. Gli sviluppatori possono accedere alle funzionalità seguenti facendo clic con il pulsante destro del mouse su una definizione API nel catalogo api della piattaforma:

• Esportare il documento di specifica dell'API - Esportare una specifica API da una definizione e quindi scaricarla come file
• Generare il client API: usare l'estensione Microsoft Kiota per generare un client API per la lingua preferita
• Generare la documentazione dell'API markdown nel formato Markdown
• Documentazione di OpenAPI: visualizzare la documentazione per una definizione dell'API e provare le operazioni in un'interfaccia utente di Swagger (disponibile solo per le definizioni OpenAPI)

Risoluzione dei problemi

Errore: Impossibile leggere le proprietà non predefinite (lettura 'nextLink')

In determinate condizioni, un utente potrebbe riscontrare il messaggio di errore seguente dopo aver eseguito l'accesso al catalogo api della piattaforma del Centro API ed espandendo l'elenco delle API per un centro API:

Error: Cannot read properties of undefined (reading 'nextLink')

Verificare che all'utente sia assegnato il ruolo Lettore dati di Centro API di Azure nel centro API. Se necessario, riassegnare il ruolo all'utente. Aggiornare quindi il catalogo API della piattaforma api di Centro API nell'estensione Visual Studio Code.

Non è possibile accedere ad Azure

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 ad Azure nel catalogo api della piattaforma, potrebbe verificarsi un problema con la configurazione della connessione.

Controllare le impostazioni nella registrazione dell'app configurata in Microsoft Entra ID. Verificare i valori dell'ID applicazione (client) e dell'ID della directory (tenant) nella registrazione dell'app e nell'URL di runtime del centro API. Configurare quindi di nuovo la connessione al centro API.

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

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.

Contenuto correlato

• Compilare e registrare API con l'estensione Centro API di Azure per Visual Studio Code
• Procedure consigliate per il controllo degli accessi in base al ruolo di Azure
• Registrare un provider di risorse