Registrare e usare connettori personalizzati in PowerAppsRegister and use custom connectors in PowerApps

PowerApps consente di creare applicazioni complete senza codice di applicazione tradizionale.PowerApps enables you to build full-featured apps with no traditional application code. In alcuni casi, però, è necessario estendere le funzionalità di PowerApps e i servizi Web sono una scelta adatta a tale scopo.But in some cases you need to extend PowerApps capabilites, and web services are a natual fit for this. L'app può connettersi a un servizio, eseguire operazioni e riottenere i dati.Your app can connect to a service, perform operations, and get data back. Quando si vuole connettere un servizio Web a PowerApps, è necessario registrarlo come connettore personalizzato.When you have a web service you want to connect to with PowerApps, you register the service as a custom connector. 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.This process enables PowerApps to understand the characteristics of your web API, including the authentication that it requires, the operations that it supports, and the parameters and outputs for each of those operations.

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.In this topic, we'll look at the steps required to register and use a custom connector, and we'll use the Azure Cognitive Services Text Analytics API as an example. Questa API identifica il linguaggio, la valutazione e le frasi chiave nel testo che le viene passato.This API identifies the language, sentiment, and key phrases in text that you pass to it. 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.The following image shows the interaction between the service, the custom connector we create from it, and the app that calls the API.

API, connettore personalizzato e app

PrerequisitiPrerequisites

  • Un account PowerApps.A PowerApps account.
  • Un file OpenAPI in formato JSON, un URL a una definizione di OpenAPI o un file Postman Collection per l'API.An OpenAPI file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. Se non si soddisfa nessuno di questi prerequisiti, saranno fornite alcune indicazioni utili.If you don't have any of these, we'll provide guidance for you.
  • Un'immagine da usare come icona per il connettore personalizzato (facoltativa).An image to use as an icon for your custom connector (optional).

Passaggi del processo del connettore personalizzatoSteps in the custom connector process

Il processo del connettore personalizzato prevede diversi passaggi, che verranno descritti brevemente di seguito.The custom connector process has several steps, which we describe briefly below. 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.This article assumes you already have a RESTful API with some type of authenticated access, so we'll focus on steps 3-6 in the rest of the article. Per un esempio dei passaggi 1 e 2, vedere Creare un'API Web personalizzata per PowerApps.For an example of steps 1 and 2, see Create a custom Web API for PowerApps.

  1. Compilare un'API RESTful nel linguaggio e nella piattaforma di propria scelta.Build a RESTful API in the language and platform of your choice. Per le tecnologie Microsoft, è consigliabile una delle operazioni seguenti.For Microsoft technologies, we recommend one of the following.

    • Funzioni di AzureAzure Functions
    • App Web di AzureAzure Web Apps
    • App API di AzureAzure API Apps
  2. Proteggere l'API usando uno dei seguenti meccanismi di autenticazione.Secure your API using one of the following authentication mechanisms. È possibile consentire l'accesso non autenticato alle API, ma non è consigliabile.You can allow unauthenticated access to your APIs, but we don't recommend it.

  3. Descrivere l'API in uno dei due modi standard del settore, in modo che PowerApps possa connettersi a essa.Describe your API in one of two industry-standard ways, so that PowerApps can connect to it.

    • Un file OpenAPI (noto anche come file Swagger)An OpenAPI file (also known as a Swagger file)
    • Un file Postman CollectionA Postman Collection

      È anche possibile compilare un file OpenAPI nel passaggio 4 come parte del processo di registrazione.You can also build an OpenAPI file in step 4 as part of the registration process.

  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.Register your custom connector using a wizard in PowerApps, where you specify an API description, security details, and other information.
  5. Usare il connettore personalizzato in un'app.Use your custom connector in an app. Creare una connessione all'API nell'app e chiamare qualsiasi operazione fornita dall'API, proprio come si chiamavano le funzioni native in PowerApps.Create a connection to the API in your app, and call any operations that the API provides, just like you call native functions in PowerApps.
  6. Condividere il connettore personalizzato come si farebbe con di altre connessioni dati in PowerApps.Share your custom connector like you do other data connections in PowerApps. Questo passaggio è facoltativo, ma è spesso opportuno condividere connettori personalizzati tra più autori di app.This step is optional, but it often makes sense to share custom connectors across multiple app creators.

Descrivere l'APIDescribe your 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.Assuming you have an API with some type of authenticated access, you need a way to describe the API so that PowerApps can connect to it. A tale scopo, creare un file OpenAPI o un file Postman Collection da qualsiasi endpoint API REST, tra cui:To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • API pubblicamente disponibili.Publicly available APIs. Ad esempio Spotify, Uber, Slack, Rackspace e altri ancora.Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • 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.An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • Un'API line-of-business personalizzata distribuita nella propria rete, purché esposta sulla rete Internet pubblica.A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

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:OpenAPI files and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • È possibile generare questi documenti usando una serie di strumenti a seconda del linguaggio e della piattaforma di cui si avvale l'API.You can generate these documents using a variety of tools depending on the language and platform that your API is built on. Per un esempio di file OpenAPI, vedere la documentazione dell'API Analisi del testo.See the Text Analytics API documentation for an example of an OpenAPI file.
  • 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.If you don't already have an OpenAPI file for your API and don't want to create one, you can still easily create a custom connector by using a Postman Collection. Per altre informazioni, vedere Creare un file Postman Collection.See Create a Postman Collection for more information.
  • PowerApps usa sostanzialmente OpenAPI dietro le quinte, in modo che un file Postman Collection venga analizzato e convertito in un file di definizione OpenAPI.PowerApps ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

Nota: le dimensioni del file devono essere inferiori a 1 MB.Note: Your file size must be less than 1MB.

Introduzione a OpenAPI e PostmanGetting started with OpenAPI and Postman

Registrare il connettore personalizzatoRegister your custom connector

A questo punto si userà il file OpenAPI o Postman Collection per registrare il connettore personalizzato in PowerApps.You will now use the OpenAPI file or Postman Collection to register your custom connector in PowerApps.

  1. In powerapps.com nel menu a sinistra fare clic su Connessioni.In powerapps.com, in the left menu, select Connections. Selezionare i puntini di sospensione (... ), quindi selezionare Gestisci connettori personalizzati in alto a destra.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    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.Tip: If you can't find where to manage custom connectors in a mobile browser, it might be under a menu in the upper left corner.

    Crea connettore personalizzato

  2. Selezionare Crea connettore personalizzato.Select Create custom connector.

    Proprietà del connettore personalizzato

  3. Nella scheda Generale scegliere come si vuole creare il connettore personalizzato.In the General tab, choose how you want to create the custom connector.

    • Caricare un file OpenAPIUpload an OpenAPI file
    • Usare un URL OpenAPIUse an OpenAPI URL
    • Caricare un file Postman Collection V1Upload Postman Collection V1

      Come creare un connettore personalizzato

      Caricare un'icona per il connettore personalizzato.Upload an icon for your custom connector. I campi Descrizione, Host e URL di Base sono in genere popolati automaticamente con le informazioni dal file OpenAPI.Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. Se non sono popolati automaticamente, è possibile aggiungervi informazioni manualmente.If they are not auto-populated, you can add information to those fields. Selezionare Continua.Select Continue.

  4. Nella scheda Sicurezza immettere eventuali proprietà di autenticazione.In the Security tab, enter any authentication properties.

    Tipi di autenticazione

    • Il tipo di autenticazione viene popolato automaticamente in base a ciò che si definisce nell'oggetto securityDefinitions del file OpenAPI.The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. Di seguito è riportato un esempio di OAuth 2.0.Below is an OAuth2.0 example.

      "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.If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • 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.When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Per un esempio di impostazione dell'autenticazione di Azure Active Directory (AAD), vedere Creare un'API Web personalizzata per PowerApps.For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for 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.In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. Se sono state definite tutte le operazioni necessarie, è possibile andare al passaggio 6 del processo di registrazione senza apportare modifiche in questa schermata.If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    Scheda Definizione

    Se si vogliono modificare le azioni esistenti o aggiungere nuove azioni al connettore personalizzato, continuare a leggere qui di seguito.If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    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.If you want to add a new action that was not already in your OpenAPI file or Postman Collection, select New action in the left pane and fill in the General section with the name, description, and visibility of your operation.
    2. Nella sezione Richiesta selezionare Importa da esempio in alto a destra.In the Request section, select Import from sample on the top right. Nel modulo a destra, incollare una richiesta di esempio.In the form on the right, paste in a sample request. 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.Sample requests are usually available in the API documentation, where you can get information to fill out the Verb, Request URL, Headers, and Body fields. Per un esempio, vedere la documentazione dell'API Analisi del testo.See the Text Analytics API documentation for an example.

      Importa da esempio

    3. Selezionare Importa per completare la definizione della richiesta.Select Import to complete the request definition. Definire la risposta in modo analogo.Define the response in a similar way.
  6. Dopo aver definito tutte le operazioni, selezionare Crea per creare il connettore personalizzato.Once you have all your operations defined, select Create to create your custom connector.
  7. Dopo aver creato il connettore personalizzato, passare alla scheda Test per testare le operazioni definite nell'API.Once you have created your custom connector, go to the Test tab to test the operations defined in the API. Scegliere una connessione e fornire parametri di input per testare un'operazione.Choose a connection, and provide input parameters to test an operation.

    Testare il connettore personalizzato

    Se la chiamata è riuscita, si otterrà una risposta valida.If the call is successful, you get a valid response.

    Testare la risposta dell'API

Usare il connettore personalizzatoUse your custom connector

Dopo aver registrato l'API, aggiungere il connettore personalizzato all'app come se si trattasse di qualsiasi altra origine dati.Now that you've registered your API, add the custom connector to your app like you would any other data source. Verrà esaminato un breve esempio.We'll go through a brief example here. Per altre informazioni sulle connessioni dati, vedere Aggiungere una connessione dati in PowerApps.For more information about data connections, see Add a data connection in PowerApps.

  1. In PowerApps Studio, nel riquadro più a destra, scegliere o toccare Aggiungi origine dati.In PowerApps Studio, in the right pane, click or tap Add data source.

  2. Scegliere o toccare il connettore personalizzato creato.Click or tap the custom connector that you created.

  3. Completare i passaggi necessari per accedere al servizio di cui a cui ci si sta connettendo.Complete any steps necessary to sign in to the service you're connecting to. Se l'API usa l'autenticazione OAuth potrebbe essere visualizzata una schermata di accesso.If your API uses OAuth authentication, you might be presented a sign-in screen. Per l'autenticazione della chiave API potrebbe essere richiesto di immettere un valore di chiave.For API key authentication, you might be prompted for a key value.
  4. Chiamare l'API nell'app.Call the API in your 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.For our example, we created an app that submits text to Cognitive Services and gets back a sentiment score of 0 to 1, which the app shows as a percentage.

    • 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.With this connector, if you start typing "Az" in the formula bar, you see the API and the operations that it makes available.

    • La chiamata complete è simile alla seguente, in cui viene passato testo dal controllo TextInput e si riceve un punteggio da visualizzare nell'app:The complete call looks like this, where we pass in text from the TextInput control and get back a score to display in the 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.We do a little more work in the app to handle the data that comes back, but it's not too complicated.

L'app completata avrà un aspetto simile a quello nell'immagine seguente:The finished app looks like the following image. semplice, ma con potenti funzionalità che permettono di chiamare Servizi cognitivi attraverso un connettore personalizzato.It's a simple app, but it gains powerful functionality by being able to call Cognitive Services through a custom connector.

Quote e limitazioniQuota and throttling

  • Per informazioni dettagliate sulle quote di creazione dei connettori personalizzati, vedere la pagina dei prezzi di PowerApps.See the PowerApps Pricing page for details about custom connector creation quotas. I connettori personalizzati condivisi con l'utente non vengono conteggiati in questa quota.Custom connectors that are shared with you don't count against this quota.
  • Per ogni connessione creata in un connettore personalizzato, gli utenti possono eseguire fino a 500 richieste al minuto.For each connection created on a custom connector, users can make up to 500 requests per minute.

Condividere il connettore personalizzatoShare your custom connector

Ora che è stato creato un connettore personalizzato, è possibile condividerlo con altri utenti nell'organizzazione.Now that you have a custom connector, you can share it with other users in your organization. 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.Keep in mind that when you share an API, others might start to depend on it, and deleting a custom connector deletes all the connections to the API. Se si vuole fornire un connettore agli utenti esterni all'organizzazione, vedere la panoramica sulla certificazione dei connettori personalizzati in PowerApps.If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in PowerApps.

  1. In powerapps.com nel menu a sinistra fare clic su Connessioni.In powerapps.com, in the left menu, select Connections. Selezionare i puntini di sospensione (... ), quindi selezionare Gestisci connettori personalizzati in alto a destra.Select the ellipsis (...), then select Manage custom connectors in the upper right corner.

    Nuova connessione

  2. Selezionare i puntini di sospensione (...) per il connettore, quindi selezionare Visualizza proprietà.Select the ellipsis (. . .) button for your connector, then select View properties.

    Visualizzare le proprietà del connettore

  3. Selezionare l'API, selezionare Condividi e quindi immettere gli utenti o i gruppi a cui si vuole concedere l'accesso all'API.Select your API, select Share, and then enter the users or groups to whom you want to grant access to your API.

    Condividere il connettore personalizzato

  4. Selezionare Salva.Select Save.

Passaggi successiviNext steps

Informazioni su come creare un file Postman CollectionLearn how to create a Postman Collection

Usare un'API Web ASP.NET.Use an ASP.NET Web API.

Registrare un'API di Azure Resource Manager.Register an Azure Resource Manager API.