Registrare e usare connettori personalizzati in PowerApps

PowerApps consente di creare applicazioni complete senza codice di applicazione tradizionale. In alcuni casi, però, è necessario estendere le funzionalità di PowerApps e i servizi Web sono una scelta adatta a tale scopo. L'app può connettersi a un servizio, eseguire operazioni e riottenere i dati. Quando si vuole connettere un servizio Web a PowerApps, è necessario registrarlo come connettore personalizzato. Questo processo consente a PowerApps di comprendere le caratteristiche dell'API Web, inclusa l'autenticazione che richiede, le operazioni che supporta e i parametri e gli output per ognuna di tali operazioni.

In questo argomento vengono esaminati i passaggi necessari per registrare e usare un connettore personalizzato e si userà l'API Analisi del testo di Servizi cognitivi di Azure come esempio. Questa API identifica il linguaggio, la valutazione e le frasi chiave nel testo che le viene passato. L'immagine seguente illustra l'interazione tra il servizio, il connettore personalizzato creato in base a quest'ultimo e l'app che chiama l'API.

Prerequisiti

• Un account PowerApps.
• Un file OpenAPI in formato JSON, un URL a una definizione di OpenAPI o un file Postman Collection per l'API. Se non si soddisfa nessuno di questi prerequisiti, saranno fornite alcune indicazioni utili.
• Un'immagine da usare come icona per il connettore personalizzato (facoltativa).

Passaggi del processo del connettore personalizzato

Il processo del connettore personalizzato prevede diversi passaggi, che verranno descritti brevemente di seguito. Questo articolo presuppone che si abbia già un'API RESTful con un tipo qualsiasi di accesso con autenticazione, perciò la parte restante sarà incentrata sui passaggi da 3 a 6. Per un esempio dei passaggi 1 e 2, vedere Creare un'API Web personalizzata per PowerApps.

1. Compilare un'API RESTful nel linguaggio e nella piattaforma di propria scelta. Per le tecnologie Microsoft, è consigliabile una delle operazioni seguenti.

   • Funzioni di Azure
   • App Web di Azure
   • App API di Azure

2. Proteggere l'API usando uno dei seguenti meccanismi di autenticazione. È possibile consentire l'accesso non autenticato alle API, ma non è consigliabile.

   • Azure Active Directory. Per altre informazioni, vedere Usare Azure Active Directory con un connettore personalizzato in PowerApps.
   • OAuth 2.0 per servizi specifici come Dropbox, Facebook e SalesForce
   • OAuth 2.0 generica
   • Chiave API
   • Autenticazione di base

3. Descrivere l'API in uno dei due modi standard del settore, in modo che PowerApps possa connettersi a essa.

   • Un file OpenAPI (noto anche come file Swagger)
   • Un file Postman Collection

   È anche possibile compilare un file OpenAPI nel passaggio 4 come parte del processo di registrazione.

4. Registrare il connettore personalizzato usando una procedura guidata in PowerApps, in cui si specifica una descrizione dell'API, i dettagli relativi alla sicurezza e altre informazioni.

5. Usare il connettore personalizzato in un'app. Creare una connessione all'API nell'app e chiamare qualsiasi operazione fornita dall'API, proprio come si chiamavano le funzioni native in PowerApps.

6. Condividere il connettore personalizzato come si farebbe con di altre connessioni dati in PowerApps. Questo passaggio è facoltativo, ma è spesso opportuno condividere connettori personalizzati tra più autori di app.

Descrivere l'API

Supponendo che si abbia un'API con un tipo qualsiasi di accesso con autenticazione, è necessario descriverla in modo che PowerApps possa connettersi a essa. A tale scopo, creare un file OpenAPI o un file Postman Collection da qualsiasi endpoint API REST, tra cui:

• API pubblicamente disponibili. Ad esempio Spotify, Uber, Slack, Rackspace e altri ancora.
• Un'API creata e distribuita in qualsiasi provider di hosting su cloud, tra cui Azure, Amazon Web Services (AWS), Heroku, Google Cloud e altri ancora.
• Un'API line-of-business personalizzata distribuita nella propria rete, purché esposta sulla rete Internet pubblica.

I file OpenAPI e Postman Collection usano formati differenti, ma sono entrambi documenti indipendenti dal linguaggio e in un formato leggibile al computer che descrivono le operazioni e i parametri dell'API:

• È possibile generare questi documenti usando una serie di strumenti a seconda del linguaggio e della piattaforma di cui si avvale l'API. Per un esempio di file OpenAPI, vedere la documentazione dell'API Analisi del testo.
• Se non si ha già un file OpenAPI per la propria API e non si vuole crearne uno, è comunque possibile creare facilmente un connettore personalizzato usando un file Postman Collection. Per altre informazioni, vedere Creare un file Postman Collection.
• PowerApps usa sostanzialmente OpenAPI dietro le quinte, in modo che un file Postman Collection venga analizzato e convertito in un file di definizione OpenAPI.

Nota: le dimensioni del file devono essere inferiori a 1 MB.

Introduzione a OpenAPI e Postman

• Se non si ha familiarità con OpenAPI, vedere l'introduzione a OpenAPI sul sito swagger.io.
• Se non si ha familiarità con Postman, installare l'app Postman dal relativo sito.
• Se l'API viene compilata con le App per le API di Azure o Funzioni di Azure, vedere Esportazione di un'API ospitata in Azure in PowerApps e Microsoft Flow per altre informazioni.

Registrare il connettore personalizzato

A questo punto si userà il file OpenAPI o Postman Collection per registrare il connettore personalizzato in PowerApps.

1. In powerapps.com nel menu a sinistra fare clic su Connessioni. Selezionare i puntini di sospensione (... ), quindi selezionare Gestisci connettori personalizzati in alto a destra.

   Suggerimento: se non si riesce a trovare l'opzione che consente di gestire i connettori personalizzati in un browser per dispositivi mobili, potrebbe trovarsi in un menu nell'angolo in alto a sinistra.

   

2. Selezionare Crea connettore personalizzato.

   

3. Nella scheda Generale scegliere come si vuole creare il connettore personalizzato.

   • Caricare un file OpenAPI
   • Usare un URL OpenAPI
   • Caricare un file Postman Collection V1

   

   Caricare un'icona per il connettore personalizzato. I campi Descrizione, Host e URL di Base sono in genere popolati automaticamente con le informazioni dal file OpenAPI. Se non sono popolati automaticamente, è possibile aggiungervi informazioni manualmente. Selezionare Continua.

4. Nella scheda Sicurezza immettere eventuali proprietà di autenticazione.

   

   • Il tipo di autenticazione viene popolato automaticamente in base a ciò che si definisce nell'oggetto securityDefinitions del file OpenAPI. Di seguito è riportato un esempio di OAuth 2.0.

     "securityDefinitions": {
         "AAD": {
         "type": "oauth2",
         "flow": "accessCode",
         "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
         "scopes": {}
         }
     },
     

   • Se il file OpenAPI non usa l'oggetto securityDefintions, non è necessario specificare valori aggiuntivi.

   • Quando si usa un file Postman Collection, il tipo di autenticazione viene popolato automaticamente solo quando si usano i tipi di autenticazione supportati, ad esempio OAuth 2.0 o Di base.

   • Per un esempio di impostazione dell'autenticazione di Azure Active Directory (AAD), vedere Creare un'API Web personalizzata per PowerApps.

5. Nella scheda Definizioni, tutte le operazioni definite nel file OpenAPI o Postman Collection, insieme ai valori di richiesta e risposta, vengono popolati automaticamente. Se sono state definite tutte le operazioni necessarie, è possibile andare al passaggio 6 del processo di registrazione senza apportare modifiche in questa schermata.

   

   Se si vogliono modificare le azioni esistenti o aggiungere nuove azioni al connettore personalizzato, continuare a leggere qui di seguito.

   1. Se si vuole aggiungere una nuova azione che non è già nel file OpenAPI o Postman Collection, selezionare Nuova azione nel riquadro a sinistra e compilare la sezione Generale con il nome, la descrizione e la visibilità dell'operazione.

   2. Nella sezione Richiesta selezionare Importa da esempio in alto a destra. Nel modulo a destra, incollare una richiesta di esempio. Le richieste di esempio sono in genere disponibili nella documentazione dell'API, in cui è possibile ottenere informazioni per la compilazione dei campi Verbo, URL richiesta, Intestazioni e Corpo. Per un esempio, vedere la documentazione dell'API Analisi del testo.

      

   3. Selezionare Importa per completare la definizione della richiesta. Definire la risposta in modo analogo.

6. Dopo aver definito tutte le operazioni, selezionare Crea per creare il connettore personalizzato.

7. Dopo aver creato il connettore personalizzato, passare alla scheda Test per testare le operazioni definite nell'API. Scegliere una connessione e fornire parametri di input per testare un'operazione.

   

   Se la chiamata è riuscita, si otterrà una risposta valida.

   

Usare il connettore personalizzato

Dopo aver registrato l'API, aggiungere il connettore personalizzato all'app come se si trattasse di qualsiasi altra origine dati. Verrà esaminato un breve esempio. Per altre informazioni sulle connessioni dati, vedere Aggiungere una connessione dati in PowerApps.

1. In PowerApps Studio, nel riquadro più a destra, scegliere o toccare Aggiungi origine dati.

   

2. Scegliere o toccare il connettore personalizzato creato.

   

3. Completare i passaggi necessari per accedere al servizio di cui a cui ci si sta connettendo. Se l'API usa l'autenticazione OAuth potrebbe essere visualizzata una schermata di accesso. Per l'autenticazione della chiave API potrebbe essere richiesto di immettere un valore di chiave.

4. Chiamare l'API nell'app. Per questo esempio, è stata creata un'app che invia testo a Servizi cognitivi e riceve un punteggio di valutazione da 0 a 1, che l'app mostra come percentuale.

   • Con questo connettore, se si inizia a digitare "Az" nella barra della formula, vengono visualizzate l'API e le operazioni che questa mette a disposizione.

     

   • La chiamata complete è simile alla seguente, in cui viene passato testo dal controllo TextInput e si riceve un punteggio da visualizzare nell'app:

     'AzureMachineLearning-TextAnalytics'.Sentiment({documents:Table({language:"en",id:"1",text:TextInput.Text})}).documents.score)
     

   • Sono necessarie alcune ulteriori operazioni nell'app per gestire i dati restituiti, peraltro non troppo complicate.

L'app completata avrà un aspetto simile a quello nell'immagine seguente: semplice, ma con potenti funzionalità che permettono di chiamare Servizi cognitivi attraverso un connettore personalizzato.

Quote e limitazioni

• Per informazioni dettagliate sulle quote di creazione dei connettori personalizzati, vedere la pagina dei prezzi di PowerApps. I connettori personalizzati condivisi con l'utente non vengono conteggiati in questa quota.
• Per ogni connessione creata in un connettore personalizzato, gli utenti possono eseguire fino a 500 richieste al minuto.

Condividere il connettore personalizzato

Ora che è stato creato un connettore personalizzato, è possibile condividerlo con altri utenti nell'organizzazione. Tenere presente che quando si condivide un'API, altri utenti potrebbe iniziare a dipendere da essa e l'eliminazione di un connettore personalizzato comporta l'eliminazione di tutte le connessioni all'API. Se si vuole fornire un connettore agli utenti esterni all'organizzazione, vedere la panoramica sulla certificazione dei connettori personalizzati in PowerApps.

1. In powerapps.com nel menu a sinistra fare clic su Connessioni. Selezionare i puntini di sospensione (... ), quindi selezionare Gestisci connettori personalizzati in alto a destra.

   

2. Selezionare i puntini di sospensione (...) per il connettore, quindi selezionare Visualizza proprietà.

   

3. Selezionare l'API, selezionare Condividi e quindi immettere gli utenti o i gruppi a cui si vuole concedere l'accesso all'API.

   

4. Selezionare Salva.

Passaggi successivi

Informazioni su come creare un file Postman Collection

Usare un'API Web ASP.NET.

Registrare un'API di Azure Resource Manager.