Condividi tramite

Creare API personalizzate che è possibile chiamare da App per la logica di Azure

  • Articolo

Si applica a: App per la logica di Azure (consumo)

Sebbene App per la logica di Azure offra centinaia di connettori che è possibile usare nei flussi di lavoro delle app per la logica, è consigliabile chiamare le API, i sistemi e i servizi che non sono disponibili come connettori. È possibile creare API personalizzate che forniscono azioni e trigger da usare nei flussi di lavoro. Ecco altri motivi per cui è possibile creare API personalizzate che è possibile chiamare dai flussi di lavoro:

  • Estendere gli attuali flussi di lavoro di integrazione del sistema e integrazione dei dati.
  • Aiutare i clienti a usare il servizio per gestire attività professionali o personali.
  • Espandere la copertura, l'individuabilità e l'uso del servizio.

In pratica, i connettori sono API Web che usano REST per le interfacce collegabili, il formato dei metadati Swagger per la documentazione e JSON come formato di scambio di dati. Poiché i connettori sono API REST che comunicano tramite endpoint HTTP, è possibile usare qualsiasi linguaggio per compilare connettori, ad esempio .NET, Java, Python o Node.js. È anche possibile ospitare le API nel servizio app di Azure, una soluzione PaaS (platform-as-a-service) che offre uno dei modi più efficaci, semplici e scalabili per ospitare le API.

Affinché le API personalizzate funzionino con il flusso di lavoro dell'app per la logica, l'API può fornire azioni che eseguono attività specifiche nei flussi di lavoro. L'API può anche fungere da trigger che avvia un'esecuzione del flusso di lavoro quando nuovi dati o un evento soddisfa una condizione specificata. Questo argomento descrive i modelli comuni che è possibile seguire per la creazione di azioni e trigger nell'API, in base al comportamento previsto per l'API.

È possibile ospitare le API in Servizio app di Azure, una soluzione PaaS (Platform-as-a-Service, piattaforma distribuita come servizio) che offre hosting di API semplice e altamente scalabile.

Suggerimento

Benché sia possibile distribuire le API come app Web, è consigliabile distribuirle come app per le API, in modo da semplificare le attività durante la compilazione, l'hosting e l'utilizzo delle API nel cloud e in locale. Non è necessario modificare il codice nelle API. È sufficiente distribuire il codice in un'app per le API. Ad esempio, è possibile compilare app per le API create con questi linguaggi:

Differenza tra le API e i connettori personalizzati

Le API personalizzate e i connettori personalizzati sono API Web che usano REST per le interfacce modulari, il formato dei metadati Swagger per la documentazione e JSON come formato di scambio di dati. Poiché questi connettori e API sono API REST che comunicano tramite endpoint HTTP, è possibile usare qualsiasi linguaggio, ad esempio .NET, Java, Python o Node.js, per la creazione di API e connettori personalizzati.

Le API personalizzate consentono di chiamare API che non sono connettori e forniscono gli endpoint che è possibile chiamare con HTTP + Swagger, Gestione API di Azure o Servizi app. I connettori personalizzati funzionano come le API personalizzate, ma hanno anche questi attributi:

  • Sono registrati come risorse connettore di App per la logica in Azure.
  • Vengono visualizzati con icone insieme ai connettori gestiti da Microsoft in Progettazione app per la logica.
  • Disponibile solo per gli autori e le risorse dell'app per la logica dei connettori che hanno lo stesso tenant di Microsoft Entra e la stessa sottoscrizione di Azure nell'area in cui vengono distribuite le app per la logica.

È anche possibile designare connettori registrati per la certificazione Microsoft. Questo processo verifica che i connettori registrati soddisfino i criteri per l'uso pubblico e rende i connettori disponibili per gli utenti in Power Automate e Microsoft Power Apps.

Per altre informazioni, vedere la documentazione seguente:

Strumenti utili

Un'API personalizzata funziona meglio con le app per la logica quando l'API include anche un documento Swagger che descrive le operazioni e i parametri dell'API. Molte librerie, ad esempio Swashbuckle, sono in grado di generare automaticamente il file Swagger. Per annotare il file Swagger per i nomi visualizzati, i tipi di proprietà e così via, è anche possibile usare TRex in modo che il file Swagger funzioni bene con le app per la logica.

Modelli di azione

Affinché le app per la logica eseguano le attività, l'API personalizzata deve specificare delle azioni. Ogni operazione dell'API è mappata a un'azione. Un'azione di base è un controller che accetta le richieste HTTP e restituisce risposte HTTP. Ad esempio, un flusso di lavoro invia una richiesta HTTP all'app Web o all'app per le API. L'app restituisce quindi una risposta HTTP, insieme al contenuto che il flusso di lavoro può elaborare.

Per un'azione standard, è possibile scrivere un metodo di richiesta HTTP nell'API e descrivere tale metodo in un file Swagger. È quindi possibile chiamare l'API direttamente con un'azione HTTP o un'azione HTTP + Swagger. Per impostazione predefinita, le risposte devono essere restituite entro il limite di timeout della richiesta.

Standard action pattern

Per fare in modo che un flusso di lavoro attenda il completamento delle attività a esecuzione prolungata, l'API può seguire il modello di polling asincrono o il modello di webhook asincrono descritto in questo argomento. Per un'analogia che consente di visualizzare i diversi comportamenti di questi modelli, si immagini la procedura necessaria per ordinare una torta personalizzata a un panificio. Il modello di polling rispecchia il comportamento in cui si chiama il panificio ogni 20 minuti per verificare se la torta è pronta. Il modello webhook rispecchia il comportamento in cui il panificio chiede al cliente il numero di telefono in modo da poterlo chiamare quando la torta è pronta.

Eseguire attività a esecuzione prolungata con il modello di azione di polling

Per fare in modo che l'API esegua attività che possono avere una durata superiore al limite di timeout della richiesta, è possibile usare il modello di polling asincrono. Questo modello ha l'API funziona in un thread separato, ma mantiene una connessione attiva al motore di App per la logica di Azure. In questo modo, il flusso di lavoro non scade o continua con il passaggio successivo nel flusso di lavoro prima che l'API termini il funzionamento.

Di seguito è illustrato il modello generale:

  1. Verificare che il motore "sappia" che l'API ha accettato la richiesta e ha iniziato a lavorare.
  2. Quando il motore effettua le richieste successive dello stato del processo, indicare al motore quando l'API termina l'attività.
  3. Restituisce dati pertinenti al motore in modo che il flusso di lavoro possa continuare.

Applicare ora la stessa analogia del panificio al modello di polling e immaginare di chiamare un panificio e ordinare una torta personalizzata da consegnare. Il processo di preparazione della torta richiede tempo e non si vuole attendere al telefono mentre il panificio è al lavoro sulla torta. Il panificio conferma l'ordine e chiede di chiamare ogni 20 minuti per sapere qual è lo stato della torta. Dopo 20 minuti, si chiama il panificio ma dicono che la torta non è pronta e che è necessario chiamare dopo altri 20 minuti. Questo andare avanti e indietro continua fino a quando si telefona e il panificio dice che l'ordine è pronto e consegna la torta.

Questo scenario si può mappare al modello di polling. La panetteria rappresenta l'API personalizzata, mentre il cliente della torta rappresenta il motore di App per la logica di Azure. Quando il motore chiama l'API con una richiesta, l'API conferma la richiesta e risponde con l'intervallo di tempo quando il motore è in grado di controllare lo stato del processo. Il motore continua a verificare lo stato del processo finché l'API risponde indicando che il processo è completato e restituisce i dati all'app per la logica, che quindi continua il flusso di lavoro.

Polling action pattern

Questi sono i passaggi specifici che l'API deve seguire, descritti dalla prospettiva dell'API:

  1. Quando l'API riceve una richiesta HTTP per avviare il lavoro, restituisce immediatamente una risposta HTTP 202 ACCEPTED con l'intestazione location descritta più avanti in questo passaggio. Questa risposta consente al motore di App per la logica di Azure di sapere che l'API ha ottenuto la richiesta, ha accettato il payload della richiesta (input di dati) ed è ora in corso l'elaborazione.

    La risposta 202 ACCEPTED deve includere queste intestazioni:

    • Obbligatorio: location intestazione che specifica il percorso assoluto di un URL in cui il motore di App per la logica di Azure può controllare lo stato del processo dell'API

    • Facoltativa: un'intestazione retry-after che specifica il numero di secondi che il motore deve attendere prima di controllare l'URL location per lo stato del processo.

      Per impostazione predefinita, il motore esegue il polling dell'URL location dopo un secondo. Per specificare un intervallo diverso, includere l'intestazione retry-after e il numero di secondi fino al polling successivo.

  2. Al termine del tempo specificato, il motore di App per la logica di Azure esegue il polling dell'URL location per controllare lo stato del processo. L'API deve eseguire questi controlli e restituire queste risposte:

    • Se il processo viene eseguito, restituisce una risposta HTTP 200 OK insieme al payload di risposta (input per il passaggio successivo).

    • Se il processo è ancora in fase di elaborazione, restituisce un'altra risposta HTTP 202 ACCEPTED con le stesse intestazioni della risposta originale.

Quando l'API segue questo modello, non è necessario eseguire alcuna operazione nella definizione del flusso di lavoro per continuare a controllare lo stato del processo. Quando il motore ottiene una risposta HTTP 202 ACCEPTED e un'intestazione valida location , il motore rispetta il modello asincrono e controlla l'intestazione fino a quando l'API location non restituisce una risposta non 202.

Suggerimento

Per un esempio di modello asincrono, esaminare questo esempio di risposta del controller asincrono in GitHub.

Eseguire attività a esecuzione prolungata con il modello di azione webhook

In alternativa, è possibile usare il modello webhook per le attività di lunga durata e l'elaborazione asincrona. Questo modello sospende il flusso di lavoro e attende che un "callback" dall'API finisca l'elaborazione prima di continuare il flusso di lavoro. Questo callback è un HTTP POST che invia un messaggio a un URL quando si verifica un evento.

Applicare ora la stessa analogia del panificio al modello webhook e immaginare di chiamare un panificio e ordinare una torta personalizzata da consegnare. Il processo di preparazione della torta richiede tempo e non si vuole attendere al telefono mentre il panificio è al lavoro sulla torta. Il panificio conferma l'ordine, ma questa volta il cliente lascia il proprio numero di telefono in modo che possano chiamarlo quando la torta è pronta. Questa volta il panificio avvisa quando l'ordine è pronto e consegna la torta.

Quando si esegue il mapping di questo modello webhook indietro, il panificio rappresenta l'API personalizzata, mentre il cliente della torta rappresenta il motore di App per la logica di Azure. Il motore chiama l'API con una richiesta e include un URL di "callback". Quando il processo viene eseguito, l'API usa l'URL per notificare al motore e restituire i dati all'app per la logica, che quindi continua il flusso di lavoro.

Per questo modello, configurare due endpoint sul controller: subscribe e unsubscribe

  • subscribeendpoint: quando l'esecuzione raggiunge l'azione dell'API nel flusso di lavoro, il motore di App per la logica di Azure chiama l'endpointsubscribe. Questo passaggio fa sì che il flusso di lavoro crei un URL di callback archiviato dall'API e quindi attenda il callback dall'API al termine del lavoro. L'API quindi richiama con un HTTP POST all'URL e passa eventuali contenuti e intestazioni come input all'app per la logica.

  • unsubscribeendpoint: se l'esecuzione del flusso di lavoro viene annullata, il motore di App per la logica di Azure chiama l'endpointunsubscribe. L'API può quindi annullare la registrazione dell'URL di callback e arrestare i processi in base alle esigenze.

Webhook action pattern

Attualmente, la finestra di progettazione del flusso di lavoro non supporta l'individuazione degli endpoint webhook tramite Swagger. Per questo modello è quindi necessario aggiungere un'azione webhook e specificare l'URL, le intestazioni e il corpo per la richiesta. Vedere anche Azioni e trigger del flusso di lavoro. Per un esempio di modello webhook, esaminare questo esempio di trigger webhook in GitHub.

Di seguito altri suggerimenti e note:

  • Per passare l'URL di callback, è possibile usare la funzione di flusso di lavoro @listCallbackUrl() in uno qualsiasi dei campi precedenti in base alle necessità.

  • Se si è proprietari della risorsa dell'app per la logica e del servizio sottoscritto, non è necessario chiamare l'endpoint dopo la chiamata dell'URL unsubscribe di callback. In caso contrario, il runtime di App per la logica di Azure deve chiamare l'endpoint unsubscribe per segnalare che non sono previste altre chiamate e consentire la pulizia delle risorse sul lato server.

Modelli di trigger

L'API personalizzata può fungere da trigger che avvia un'esecuzione del flusso di lavoro quando nuovi dati o un evento soddisfa una condizione specificata. Questo trigger può verificare regolarmente, o attendere e restare in ascolto, la presenza di nuovi dati o eventi presso l'endpoint servizio. Se nuovi dati o eventi soddisfano la condizione specificata, il trigger viene attivato e avvia l'app per la logica, che è in ascolto di quel trigger. Per avviare l'app per la logica in questo modo, l'API può seguire il modello di trigger di polling o trigger webhook. Questi modelli sono simili alle loro controparti per le azioni di polling e le azioni webhook. Vedere anche le informazioni sulla misurazione dell'utilizzo per i trigger.

Verificare la presenza di nuovi dati o eventi regolarmente con il modello di trigger di polling

Un trigger di polling funziona in modo molto simile all'azione di polling descritta in precedenza in questo argomento. Il motore App per la logica di Azure chiama periodicamente e controlla l'endpoint del trigger per individuare nuovi dati o eventi. Se il motore rileva nuovi dati o eventi che soddisfano la condizione specificata, il trigger viene attivato. Il motore crea quindi un'istanza del flusso di lavoro che elabora i dati come input.

Polling trigger pattern

Nota

Ogni richiesta di polling viene conteggiato come esecuzione di un'azione, anche quando non viene creata alcuna istanza del flusso di lavoro. Per evitare che gli stessi dati vengano elaborati più volte, il trigger deve pulire i dati che sono già stati letti e passati all'app per la logica.

Di seguito sono riportati i passaggi specifici per un trigger di polling, descritti dalla prospettiva dell'API:

Sono stati rilevati nuovi dati o eventi? Risposta dell'API
Trovato Restituire uno stato HTTP 200 OK con il payload di risposta (input per il passaggio successivo).
Questa risposta crea un'istanza del flusso di lavoro e avvia il flusso di lavoro.
Non trovato Restituire uno stato HTTP 202 ACCEPTED con un'intestazione location e un'intestazione retry-after.
Per i trigger, l'intestazione location deve contenere anche un triggerState parametro di query, che in genere è un "timestamp". L'API può usare questo identificatore per tenere traccia dell'ultima attivazione del flusso di lavoro.

Ad esempio, per verificare periodicamente se nel servizio sono presenti nuovi file, si può creare un trigger di polling con questi comportamenti:

La richiesta include triggerState? Risposta dell'API
No Restituire uno stato HTTP 202 ACCEPTED oltre a un'intestazione location con triggerState impostato sull'ora corrente e l'intervallo retry-after su 15 secondi.
Sì Verificare se nel servizio sono presenti file aggiunti dopo DateTime per triggerState.
Numero di file trovati Risposta dell'API
Singolo file Restituire uno stato HTTP 200 OK e il payload del contenuto, aggiornare triggerState a DateTime per il file restituito e impostare l'intervallo retry-after su 15 secondi.
Più file Restituire un file alla volta e uno stato HTTP 200 OK, aggiornare triggerState e impostare l'intervallo retry-after su 0 secondi.
Questi passaggi consentono al motore di sapere che sono disponibili più dati e che il motore deve richiedere immediatamente i dati dall'URL nell'intestazione location .
Nessun file Restituire uno stato HTTP 202 ACCEPTED, non modificare triggerState e impostare l'intervallo retry-after su 15 secondi.

Suggerimento

Per un esempio di modello di trigger di polling, vedere questo esempio di controller di trigger di polling in GitHub.

Attendere e restare in ascolto di nuovi dati o eventi con il modello di trigger webhook

Un trigger webhook è un trigger di push che attende e resta in ascolto di nuovi dati o eventi in corrispondenza dell'endpoint servizio. Se nuovi dati o un evento soddisfano la condizione specificata, il trigger viene attivato e crea un'istanza del flusso di lavoro, che quindi elabora i dati come input. I trigger webhook funzionano in modo molto simile alle azioni webhook descritte in precedenza in questo argomento e sono impostati con gli endpoint subscribe e unsubscribe.

  • subscribeendpoint: quando si aggiunge e si salva un trigger webhook nell'app per la logica, il motore di App per la logica di Azure chiama l'endpointsubscribe. Questo passaggio fa sì che il flusso di lavoro crei un URL di callback archiviato dall'API. Quando sono presenti nuovi dati, o un evento, che soddisfano la condizione specificata o nuovi dati, l'API richiama con un HTTP POST all'URL. Il payload di contenuto e le intestazioni vengono passati come input all'app per la logica.

  • unsubscribeendpoint: se il trigger webhook o l'intera risorsa dell'app per la logica viene eliminato, il motore di App per la logica di Azure chiama l'endpointunsubscribe. L'API può quindi annullare la registrazione dell'URL di callback e arrestare i processi in base alle esigenze.

Webhook trigger pattern

Attualmente, la finestra di progettazione del flusso di lavoro non supporta l'individuazione degli endpoint webhook tramite Swagger. Per questo modello è quindi necessario aggiungere un trigger webhook e specificare l'URL, le intestazioni e il corpo per la richiesta. Vedere anche Trigger HTTPWebhook. Per un esempio di modello webhook, esaminare questo esempio di controller di trigger webhook in GitHub.

Di seguito altri suggerimenti e note:

  • Per passare l'URL di callback, è possibile usare la funzione di flusso di lavoro @listCallbackUrl() in uno qualsiasi dei campi precedenti in base alle necessità.

  • Per evitare che gli stessi dati vengano elaborati più volte, il trigger deve pulire i dati che sono già stati letti e passati all'app per la logica.

  • Se si è proprietari della risorsa dell'app per la logica e del servizio sottoscritto, non è necessario chiamare l'endpoint dopo la chiamata dell'URL unsubscribe di callback. In caso contrario, il runtime di App per la logica deve chiamare l'endpoint unsubscribe per segnalare che non sono previste altre chiamate e consentire la pulizia delle risorse sul lato server.

Migliorare la sicurezza delle chiamate alle API dalle app per la logica

Dopo aver creato le API personalizzate, configurare l'autenticazione per le API in modo che possano essere chiamate in modo sicuro da app per la logica. Informazioni su come migliorare la sicurezza delle chiamate ad API personalizzate dalle app per la logica.

Distribuire e chiamare le API

Dopo aver configurato l'autenticazione, configurare la distribuzione per le API. Vedere Come distribuire e chiamare API personalizzate da app per la logica.

Pubblicare API personalizzate in Azure

Per rendere disponibili le API personalizzate per altri utenti di App per la logica di Azure, è necessario aggiungere la sicurezza e registrarle come connettori App per la logica di Azure. Per altre informazioni, vedere Panoramica dei connettori personalizzati.

Per rendere disponibili le API personalizzate a tutti gli utenti in App per la logica, Power Automate e Microsoft Power Apps, è necessario aggiungere sicurezza, registrare le API come connettori App per la logica di Azure e nominare i connettori per il programma Microsoft Azure Certified.

Ottenere supporto

Passaggi successivi