Creare flussi di lavoro che è possibile chiamare, attivare o annidare usando endpoint HTTPS in App per la logica di Azure
Si applica a: App per la logica di Azure (a consumo e standard)
Alcuni scenari potrebbero richiedere la creazione di un flusso di lavoro dell'app per la logica in grado di ricevere richieste in ingresso da altri servizi o flussi di lavoro, oppure un flusso di lavoro che è possibile chiamare usando un URL. Per questa attività, è possibile esporre un endpoint HTTPS sincrono nativo nel flusso di lavoro quando si usa uno dei seguenti tipi di trigger basati sulla richiesta:
- Richiedi
- Webhook HTTP
- Trigger del connettore gestito con tipo ApiConnectionWebhook e che possono ricevere richieste HTTPS in ingresso
Questa guida illustra come creare un endpoint chiamabile per il flusso di lavoro aggiungendo il trigger di richiesta e quindi chiamare tale endpoint da un altro flusso di lavoro. Tutti i principi si applicano in modo identico agli altri tipi di trigger basati sulla richiesta che possono ricevere richieste in ingresso.
Prerequisiti
Account e sottoscrizione di Azure. Se non si ha una sottoscrizione, è possibile iscriversi per creare un account Azure gratuito.
Un flusso di lavoro dell'app per la logica in cui si desidera usare il trigger basato sulla richiesta per creare l'endpoint chiamabile. È possibile iniziare con un flusso di lavoro vuoto o con un flusso di lavoro esistente in cui è possibile sostituire il trigger corrente. Questo esempio inizia con un flusso di lavoro vuoto.
Installare o usare uno strumento che può inviare richieste HTTP per testare la soluzione, ad esempio:
- Visual Studio Code con un'estensione da Visual Studio Marketplace
- PowerShell Invoke-RestMethod
- Microsoft Edge - Strumento console di rete
- Bruno
- curl
Attenzione
Per gli scenari in cui sono presenti dati sensibili, ad esempio credenziali, segreti, token di accesso, chiavi API e altre informazioni simili, assicurarsi di usare uno strumento che protegge i dati con le funzionalità di sicurezza necessarie, funziona offline o in locale, non sincronizza i dati nel cloud e non richiede l'accesso a un account online. In questo modo si riduce il rischio di esporre i dati sensibili al pubblico.
Creare un endpoint richiamabile
A seconda che si disponga di un flusso di lavoro di app per la logica Standard o A consumo, seguire i passi corrispondenti:
Nel portale di Azure aprire la risorsa dell'app per la logica Standard e il flusso di lavoro vuoto nella finestra di progettazione.
Facoltativamente, nella casella Schema JSON del corpo della richiesta è possibile immettere uno schema JSON che descrive il payload o i dati che si prevede che il trigger riceva.
La finestra di progettazione usa questo schema per generare token che rappresentano gli output del trigger. Quindi, è possibile fare facilmente riferimento a questi output nel flusso di lavoro dell'app per la logica. Altre informazioni sui token generati da schemi JSON.
Per questo esempio, immettere lo schema seguente:
{ "type": "object", "properties": { "address": { "type": "object", "properties": { "streetNumber": { "type": "string" }, "streetName": { "type": "string" }, "town": { "type": "string" }, "postalCode": { "type": "string" } } } } }
In alternativa, è possibile generare uno schema JSON fornendo un payload campione:
Nel trigger di richiesta selezionare Usare il payload campione per generare lo schema.
Nella casella Immettere o incollare un payload JSON campione immettere il payload campione, ad esempio:
{ "address": { "streetNumber": "00000", "streetName": "AnyStreet", "town": "AnyTown", "postalCode": "11111-1111" } }Quando si è pronti, selezionare Fine.
La casella Schema JSON del corpo della richiesta ora mostra lo schema generato.
Salvare il flusso di lavoro.
La casella URL POST HTTP ora mostra l'URL di callback generato che gli altri servizi possono usare per chiamare e attivare il flusso di lavoro dell'app per la logica. Questo URL include i parametri di query che specificano una chiave Shared Access Signature (SAS), usata per l'autenticazione.
Per copiare l'URL di callback, sono disponibili queste opzioni:
A destra della casella URL POST HTTP, selezionare Copia URL (icona copia file).
Copiare l'URL di callback dalla pagina Informazioni generali del flusso di lavoro.
Nel menu del flusso di lavoro, selezionare Informazioni generali.
Nella pagina Informazioni generali, in URL del flusso di lavoro spostare il puntatore sull'URL e selezionare Copia negli Appunti:
Per testare l'URL di callback e attivare il flusso di lavoro, inviare una richiesta HTTP all'URL, incluso il metodo previsto dal trigger Richiesta, usando lo strumento di richiesta HTTP e le relative istruzioni.
Questo esempio usa il metodo POST con l'URL copiato, simile all'esempio seguente:
POST https://{logic-app-name}.azurewebsites.net:443/api/{workflow-name}/triggers/{trigger-name}/invoke?api-version=2022-05-01&sp=%2Ftriggers%2F{trigger-name}%2Frun&sv=1.0&sig={shared-access-signature}
Selezionare il metodo di richiesta previsto
Per impostazione predefinita, il trigger di richiesta prevede una richiesta POST. Tuttavia, è possibile specificare un metodo diverso che deve usare il chiamante, ma solo un singolo metodo.
Nel trigger di richiesta aprire l'elenco Parametri avanzati e selezionare Metodo, che aggiunge questa proprietà al trigger.
Nell'elenco Metodo selezionare invece il metodo previsto dal trigger. In alternativa, è possibile specificare un metodo personalizzato.
Per questo esempio, selezionare GET in modo che in un secondo momento sia possibile testare l'URL dell'endpoint.
Passare i parametri tramite l'URL dell'endpoint
Quando si desidera accettare i valori dei parametri tramite l'URL dell'endpoint, sono disponibili queste opzioni:
Accettare i valori tramite i parametri GET o i parametri URL.
Questi valori vengono passati nell'URL dell'endpoint come coppie nome-valore. Per questa opzione, è necessario usare il metodo GET nel trigger di richiesta. In un'azione successiva è possibile ottenere i valori dei parametri come output del trigger usando la funzione
triggerOutputs()in un'espressione.Accettare valori tramite un percorso relativo per i parametri nel trigger di richiesta.
Questi valori vengono passati nell'URL dell'endpoint attraverso un percorso relativo. Inoltre è necessario selezionare il metodo previsto dal trigger. In un'azione successiva è possibile ottenere i valori dei parametri come output del trigger facendo riferimento direttamente a tali output.
Accettare i valori tramite i parametri GET
Nel trigger di richiesta aprire Parametri avanzati, aggiungere al trigger la proprietà Metodo e selezionare il metodo GET.
Per altre informazioni, vedere Selezionare il metodo di richiesta previsto.
Nella finestra di progettazione seguire questi passi generali per aggiungere l'azione in cui si desidera usare il valore del parametro.
Per questo esempio, selezionare l'azione denominata Risposta.
Per compilare l'espressione
triggerOutputs()che recupera il valore del parametro, seguire questi passi:Nell'azione di risposta selezionare all'interno della proprietà Corpo in modo che vengano visualizzate le opzioni per il contenuto dinamico (icona a forma di fulmine) e l'editor di espressioni (icona della formula). Selezionare l'icona della formula per aprire l'editor dell’espressione.
Nella casella dell'espressione immettere l'espressione seguente, sostituendo
parameter-namecon il nome del parametro, quindi selezionare OK.triggerOutputs()['queries']['parameter-name']
Nella proprietà Corpo l'espressione viene risolta nel token
triggerOutputs().
Se si salva il flusso di lavoro, ci si sposta dalla finestra di progettazione e si torna alla finestra di progettazione, il token mostra il nome del parametro specificato, ad esempio:
Nella visualizzazione codice la proprietà Corpo viene visualizzata nella definizione dell'azione di risposta, come indicato di seguito:
"body": "@{triggerOutputs()['queries']['parameter-name']}",Ad esempio si supponga di voler passare un valore per un parametro denominato
postalCode. La proprietà Corpo specifica la stringa,Postal Code:con uno spazio finale, seguita dall'espressione corrispondente:
Testare l'endpoint chiamabile
Dal trigger di richiesta copiare l'URL del flusso di lavoro e incollarlo in un'altra finestra del browser. Nell'URL aggiungere il nome e il valore del parametro all'URL nel formato seguente, quindi premere INVIO.
...invoke/{parameter-name}/{parameter-value}?api-version=2022-05-01...Ad esempio:
https://mystandardlogicapp.azurewebsites.net/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/12345?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}Il browser restituisce una risposta con il testo:
Postal Code: 123456
Nota
Se si desidera includere nell’URI il simbolo hash o cancelletto (#), usare questa versione codificata: %25%23
Accettare i valori tramite un percorso relativo
Nel trigger di richiesta aprire l'elenco Parametri avanzati e selezionare Percorso relativo, che aggiunge questa proprietà al trigger.
Nella proprietà Percorso relativo specificare il percorso relativo per il parametro nello schema JSON che si vuole che l'URL accetti, ad esempio,
/address/{postalCode}.
Nel trigger di richiesta, seguire questi passi generali per aggiungere l'azione in cui si vuole usare il valore del parametro.
Per questo esempio, aggiungere l'azione Risposta.
Nella proprietà Corpo dell'azione di risposta includere il token che rappresenta il parametro specificato nel percorso relativo del trigger.
Si supponga, ad esempio, che si desideri che l'azione di risposta restituisca
Postal Code: {postalCode}.Nella proprietà Corpo immettere
Postal Code:con uno spazio finale. Mantenere il cursore all'interno della casella di modifica in modo che l'elenco del contenuto dinamico rimanga aperto.Nell'elenco di contenuto dinamico, nella sezione Quando viene ricevuta una richiesta HTTP, selezionare l'output del trigger Path Parameters postalCode.
La proprietà Corpo ora include il parametro selezionato:
Salvare il flusso di lavoro.
Nel trigger di richiesta, l'URL di callback viene aggiornato e ora include il percorso relativo, ad esempio:
https://mystandardlogicapp.azurewebsites.net/api/Stateful-Workflow/triggers/When_a_HTTP_request_is_received/invoke/address/%7BpostalCode%7D?api-version=2022-05-01&sp=%2Ftriggers%2FWhen_a_HTTP_request_is_received%2Frun&sv=1.0&sig={shared-access-signature}Per testare l'endpoint chiamabile, copiare l'URL di callback aggiornato dal trigger di richiesta, incollare l'URL in un'altra finestra del browser, sostituire
%7BpostalCode%7Dnell'URL con123456e premere INVIO.Il browser restituisce una risposta con il testo:
Postal Code: 123456
Nota
Se si desidera includere nell’URI il simbolo hash o cancelletto (#), usare questa versione codificata: %25%23
Chiamare il flusso di lavoro tramite l'URL dell'endpoint
Dopo aver creato l'endpoint, è possibile attivare il flusso di lavoro inviando una richiesta HTTPS all'URL completo dell'endpoint. I flussi di lavoro di App per la logica di Azure includono il supporto predefinito per gli endpoint di accesso diretto.
Token generati dallo schema
Quando si specifica uno schema JSON nel trigger di richiesta, Progettazione flussi di lavoro genera i token per le proprietà in quello schema. È quindi possibile usare tali token per passare dati tramite il flusso di lavoro.
Ad esempio, se si aggiungono allo schema JSON altre proprietà, quale "suite", i token per tali proprietà sono disponibili per l'uso nei passi successivi per il flusso di lavoro. Di seguito è riportato lo schema JSON completo:
{
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"streetNumber": {
"type": "string"
},
"streetName": {
"type": "string"
},
"suite": {
"type": "string"
},
"town": {
"type": "string"
},
"postalCode": {
"type": "string"
}
}
}
}
}
Chiamare altri flussi di lavoro
È possibile chiamare altri flussi di lavoro che possono ricevere richieste, annidandoli all'interno del flusso di lavoro corrente. Per chiamare questi flussi di lavoro, seguire questi passi:
Nella finestra di progettazione seguire questi passi generali per aggiungere l'azione di Workflow Operations denominata Richiama un flusso di lavoro in questa app del flusso di lavoro.
L'elenco Nome flusso di lavoro mostra i flussi di lavoro idonei da selezionare.
Nell'elenco Nome flusso di lavoro selezionare il flusso di lavoro che si desidera chiamare, ad esempio:
Riferimento al contenuto da una richiesta in ingresso
Se il tipo di contenuto della richiesta in ingresso è application/json, è possibile fare riferimento alle proprietà nella richiesta in ingresso. In caso contrario, questo contenuto viene considerato come una singola unità binaria che è possibile passare ad altre API. Per fare riferimento a questo contenuto all'interno del flusso di lavoro dell'app per la logica, è prima necessario convertire tale contenuto.
Ad esempio, se si passa contenuto con tipo application/xml, è possibile usare l' @xpath() espressione per eseguire un'estrazione XPath, oppure usare l' @json()espressione per convertire XML in JSON. Altre informazioni sul lavoro con i tipi di contenuto supportati.
Per ottenere l'output da una richiesta in ingresso, è possibile usare la @triggerOutputs espressione. Si supponga di avere un output simile all'esempio seguente:
{
"headers": {
"content-type" : "application/json"
},
"body": {
"myProperty" : "property value"
}
}
Per accedere in modo specifico alla proprietà body, è possibile usare l' @triggerBody()espressione come collegamento.
Rispondere alle richieste
A volte si desidera rispondere a determinate richieste che attivano il flusso di lavoro restituendo il contenuto al chiamante. Per creare il codice di stato, l'intestazione e il corpo per la risposta, usare l'azione di risposta. Questa azione può trovarsi in qualsiasi punto del flusso di lavoro, non solo alla fine di esso. Se il flusso di lavoro non include un'azione di risposta, l'endpoint risponde immediatamente con lo stato 202 Accettato.
Affinché il chiamante originale ottenga correttamente la risposta, tutti i passi necessari per la risposta devono terminare entro il limite di timeout della richiesta, a meno che il flusso di lavoro attivato non venga chiamato come flusso di lavoro annidato. Se non è restituita alcuna azione di risposta entro questo limite, si verifica il timeout della richiesta in ingresso, che riceverà 408 Timeout client.
Per i flussi di lavoro annidati, il flusso di lavoro padre continua ad attendere una risposta fino al completamento di tutti i passi, indipendentemente dal tempo necessario.
Costruire la risposta
Nel corpo della risposta è possibile includere più intestazioni e qualsiasi tipo di contenuto. Ad esempio, l'intestazione della risposta seguente specifica che il tipo di contenuto della risposta è application/json e che il corpo contiene valori per le proprietà town e postalCode, in base allo schema JSON descritto in precedenza in questo argomento per il trigger di richiesta.
Le risposte hanno le seguenti proprietà:
| Proprietà (visualizzazione) | Proprietà (JSON) | Descrizione |
|---|---|---|
| Codice di stato | statusCode |
Codice di stato HTTPS da usare nella risposta per la richiesta in ingresso. Può essere qualsiasi codice di stato valido che inizia con 2xx, 4xx o 5xx. I codici di stato 3xx non sono consentiti. |
| Intestazioni | headers |
Una o più intestazioni da includere nella risposta |
| Testo | body |
Oggetto body che può essere una stringa, un oggetto JSON o anche contenuto binario a cui si fa riferimento da un passaggio precedente |
Per visualizzare la definizione JSON per l'azione di risposta e la definizione JSON completa del flusso di lavoro, passare dalla visualizzazione finestra di progettazione alla visualizzazione codice.
"Response": {
"type": "Response",
"kind": "http",
"inputs": {
"body": {
"postalCode": "@triggerBody()?['address']?['postalCode']",
"town": "@triggerBody()?['address']?['town']"
},
"headers": {
"content-type": "application/json"
},
"statusCode": 200
},
"runAfter": {}
}
Domande e risposte
D: E per quanto riguarda la sicurezza degli URL per le chiamate in ingresso?
R: Azure genera in modo sicuro gli URL di callback dell'app per la logica mediante una firma di accesso condiviso (SAS). La firma viene trasmessa come parametro di query e deve essere convalidata prima dell’esecuzione del flusso di lavoro. Azure genera la firma con una combinazione univoca che include la chiave privata per ogni app per la logica, il nome del trigger e l'operazione in esecuzione. Pertanto, se un utente non ottiene l'accesso alla chiave privata dell'app per la logica, non potrà generare una firma valida.
Importante
Per i sistemi di produzione e con protezione elevata, è fortemente consigliabile non chiamare il flusso di lavoro direttamente dal browser. Questo è dovuto ai motivi di seguito:
- La chiave di accesso condiviso viene visualizzata nell'URL.
- Non è possibile gestire i criteri dei contenuti di sicurezza a causa dei domini condivisi tra i clienti di App per la logica di Azure.
Per altre informazioni su sicurezza, autorizzazione e crittografia per le chiamate in ingresso al flusso di lavoro, ad esempio Transport Layer Security (TLS), precedentemente noto come Secure Sockets Layer (SSL), Microsoft Entra ID OAuth, esponendo il flusso di lavoro dell'app per la logica con Gestione API di Azure, o limitando gli indirizzi IP che originano dalle chiamate in ingresso, vedere Proteggere l'accesso e i dati : accesso per le chiamate in ingresso ai trigger basati sulla richiesta.
D: È possibile configurare ulteriormente gli endpoint chiamabili?
R: Sì, gli endpoint HTTPS supportano configurazioni più avanzate tramite Gestione API di Azure. Questo servizio offre inoltre la possibilità di gestire tutte le API in modo coerente, incluse le app per la logica, di impostare i nomi di dominio personalizzato, usare più metodi di autenticazione e altro ancora, ad esempio:
- Impostare il metodo della richiesta
- Modificare i segmenti dell'URL della richiesta
- Configurare i domini di Gestione API nel portale di Azure
- Impostare la norma per verificare l'autenticazione di base