Creare un connettore personalizzato per un'API Web

Questo tutorial ti mostra come iniziare a creare un'API Web ASP.NET, ospitarla nella funzionalità App Web di Azure di Servizio app di Azure, abilita l'autenticazione Microsoft Entra ID e quindi registrare l'API Web ASP.NET in Power Automate. Dopo aver registrato l'API, puoi connetterti a essa e chiamarla dal flusso. È anche possibile registrare e chiamare l'API da Power Apps o App per la logica di Azure.

Prerequisiti

Creare e distribuire un'app Web ASP.NET in Azure

Per questa esercitazione, crea un'app Web ASP.NET Visual C#.

  1. Apri Visual Studio, quindi seleziona File > Nuovo progetto.

    1. Espandi Installati, vai a Modelli > Visual C# > Web, quindi seleziona Applicazione Web ASP.NET.

    2. Immetti il nome del progetto, la posizione e il nome della soluzione per la tua app, quindi seleziona OK.

    Screenshot che mostra una nuova applicazione Web ASP.NET Visual C#.

  2. Nella casella Nuova applicazione Web ASP.NET, seleziona il modello API Web, assicurati verifica che la casella di controllo Ospita nel cloud sia selezionata, quindi seleziona Modifica autenticazione.

    Screenshot che mostra la finestra di dialogo Nuova applicazione Web ASP.NET.

  3. Seleziona Nessuna autenticazione, quindi seleziona OK. Puoi impostare l'autenticazione in un secondo momento.

    Seleziona Nessuna autenticazione.

  4. Quando la casella Nuova applicazione Web ASP.NET viene nuovamente visualizzata, seleziona OK.

  5. Nella casella Crea servizio app, rivedi le impostazioni di hosting descritte nella tabella seguente, apporta le modifiche desiderate e seleziona Crea.

    Un piano di servizio app rappresenta una raccolta di risorse fisiche utilizzate per l'hosting di app nella sottoscrizione di Azure. Informazioni sul servizio app.

    Crea un servizio app.

    Impostazione Valore suggerito Descrzione
    Account aziendale o dell'istituto di istruzione di Azure o account Microsoft personale your-user-account Seleziona il tuo account utente.
    Nome app Web custom-web-api-app-name o il nome predefinito Immetti il nome per l'app API Web che viene utilizzato nell'URL dell'app, ad esempio: http://web-api-app-name.
    Abbonamento Azure-subscription-name Seleziona la sottoscrizione di Azure da usare.
    Gruppo di risorse Azure-resource-group-name Seleziona un gruppo di risorse di Azure esistente o, se non lo hai già fatto, crea un gruppo di risorse.

    Nota: un gruppo di risorse di Azure consente di organizzare le risorse di Azure nella sottoscrizione di Azure.

    Piano di servizio app App-Service-plan-name Seleziona un piano di servizio app esistente o, se non lo hai già fatto, crea un piano.

    Se crei un piano di servizio app, specifica quanto segue.

    Impostazione Valore suggerito Descrzione
    Location deployment-region Seleziona la regione per distribuire la tua app.
    Dimensione App-Service-plan-size Seleziona la dimensione del tuo piano, che determina il costo e la capacità delle risorse di calcolo per il tuo piano di servizio.

    Per configurare qualsiasi altra risorsa richiesta dalla tua app, seleziona Esplora altri servizi di Azure.

    Impostazione Valore suggerito Descrizione
    Tipo di risorsa Azure-resource-type Seleziona e configura eventuali risorse aggiuntive richieste dalla tua app.
  6. Dopo che Visual Studio distribuisce il tuo progetto, crea il codice per la tua app.

Creare un file OpenAPI (Swagger) che descriva l'API Web

Per connettere l'app per le API Web a Power Automate, Power Apps o App per la logica, è necessario un file OpenAPI (in precedenza Swagger) che descriva le operazioni dell'API. Puoi scrivere la definizione OpenAPI per la tua API con l'editor online Swagger, ma questo tutorial utilizza uno strumento open source denominato Swashbuckle.

  1. Se non lo hai già fatto, installa il pacchetto Swashbuckle NuGet nel tuo progetto Visual Studio:

    1. In Visual Studio, seleziona Strumenti > Gestione pacchetti NuGet > Console di gestione pacchetti.

    2. Nella Console di gestione pacchetti, vai alla directory del progetto dell'app se non ci sei già (esegui Set-Location "project-path") ed esegui questo cmdlet di PowerShell:

      Install-Package Swashbuckle

      Screenshot che mostra Swashbuckle installato utilizzando la Console di gestione pacchetti.

    Suggerimento

    Se esegui la tua app dopo aver installato Swashbuckle, Swashbuckle genera un file OpenAPI a questo URL:

      http://{your-web-api-app-root-URL}/swagger/docs/v1

    Swashbuckle genera anche un'interfaccia utente a questo URL:

      http://{your-web-api-app-root-URL}/swagger

  2. Quando sei pronto, pubblica l'app API Web in Azure. Per pubblicare da Visual Studio, fai clic con il pulsante destro del mouse sul progetto Web in Esplora soluzioni, seleziona Pubblica... e segui le istruzioni.

    Importante

    Se un documento OpenAPI contiene ID operazione duplicata, non sarà valido. Il modello C# di esempio ripete l'ID operazione, Values_Get.

    Se hai usato il modello C# di esempio, puoi risolvere questo problema modificando un'istanza dell'ID operazione in Value_Get e ripubblicandolo.

  3. Recupera il documento OpenAPI navigando in questa posizione:

    http://{your-web-api-app-root-URL}/swagger/docs/v1

    È anche possibile scaricare un documento OpenAPI di esempio da questa esercitazione. Assicurati di rimuovere i commenti, che iniziano con //, prima di utilizzare il documento.

  4. Salva il contenuto come file JSON. A seconda del browser, potrebbe essere necessario copiare e incollare il testo in un file di testo vuoto.

Configura l'autenticazione Microsoft Entra ID

Ora creerai due applicazioni Microsoft Entra ID in Azure. Per saperne di più, vai a Integrazione delle applicazioni con Microsoft Entra ID.

Importante

Entrambe le app devono essere nella stessa directory.

Prima applicazione Microsoft Entra ID: protezione dell'API Web

La prima applicazione Microsoft Entra ID viene usata per proteggere l'API Web. Assegnale il nome webAPI. Puoi abilitare l'autenticazione Microsoft Entra ID sull'API Web seguendo questi passaggi con i seguenti valori:

  • URL di accesso: https://login.windows.net
  • URL di risposta: https://<your-root-url>/.auth/login/aad/callback
  • Non hai bisogno di una chiave client.
  • Non hai bisogno di delegare alcuna autorizzazione.
  • Copia l'ID applicazione perché ne avrai bisogno in seguito.

Seconda applicazione Microsoft Entra ID: protezione del connettore personalizzato e dell'accesso delegato

La seconda applicazione Microsoft Entra ID viene usata per proteggere la registrazione del connettore personalizzato e acquisire l'accesso delegato all'API Web protetta dalla prima applicazione. Assegnale il nome webAPI-customAPI.

  • URL di accesso: https://login.windows.net
  • URL di risposta: https://msmanaged-na.consent.azure-apim.net/redirect
  • Aggiungi le autorizzazioni per disporre dell'accesso delegato all'API Web.
  • Copia l'ID applicazione perché ne avrai bisogno in seguito.
  • Genera una chiave client e copiala perché ne avrai bisogno in seguito.

Aggiungere l'autenticazione all'App Web di Azure

  1. Accedi al portale di Azure e trova l'App Web distribuita nella prima sezione.

  2. Seleziona Impostazioni, quindi Autenticazione/Autorizzazione.

  3. Attiva Autenticazione del servizio app e quindi seleziona Azure Active Directory. Nel pannello successivo seleziona Rapida.

  4. Seleziona Seleziona app AD esistente, quindi seleziona l'applicazione Microsoft Entra ID webAPI creata in precedenza.

A questo punto sarà possibile usare Microsoft Entra ID per autenticare l'app Web.

Aggiungere il connettore personalizzato a Power Automate

  1. Modifica OpenAPI aggiungendo l'oggetto securityDefintions e l'autenticazione Microsoft Entra ID usata per l'app Web. La sezione del file OpenAPI contenente la proprietà host dovrebbe avere questo aspetto:
// File header should be above here...

"host": "<your-root-url>",
"schemes": [
    "https"      //Make sure this is https!
],
"securityDefinitions": {
    "Microsoft Entra ID": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
        "tokenUrl" : "https://login.windows.net/common/oauth2/token",
        "scopes": {}
    }
},

// The rest of the OpenAPI follows...
  1. Passa a Power Automate e aggiungi un connettore personalizzato come descritto in Usare i connettori personalizzati in Power Automate.

  2. Dopo aver caricato OpenAPI, la procedura guidata riconosce automaticamente che è in uso l'autenticazione di Microsoft Entra ID per l'API Web.

  3. Configura l'autenticazione di Microsoft Entra ID per il connettore personalizzato.

  • ID client: ID client di webAPI-CustomAPI
  • Segreto: chiave client di webAPI-CustomAPI
  • URL di accesso: https://login.windows.net
  • ResourceUri: ID client di webAPI
  1. Seleziona Crea per creare una connessione con il connettore personalizzato.

Vedi anche

Scopri di più sull'autenticazione Microsoft Entra ID

Inviare commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.