Condividi tramite

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:

Questa guida illustra come creare un endpoint chiamabile per il flusso di lavoro aggiungendo il trigger Request 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

  • Un account e una sottoscrizione di Azure. Se non si ha una sottoscrizione, è possibile iscriversi per creare un account Azure gratuito.

  • Risorsa dell'app per la logica con il flusso di lavoro in cui si vuole creare l'endpoint richiamabile.

    È 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:

    Attenzione

    Per 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. Lo strumento deve funzionare offline o in locale e non richiede l'accesso a un account online o sincronizzare i dati nel cloud. Quando si usa uno strumento con queste caratteristiche, 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:

  1. Nel portale di Azure, aprire la risorsa dell’app per la logica Standard.

  2. Nel menu della barra laterale della risorsa, in Flussi di lavoro selezionare Flussi di lavoro e quindi selezionare il flusso di lavoro vuoto.

  3. Nel menu della barra laterale del flusso di lavoro, in Strumenti, selezionare il designer per aprire il flusso di lavoro.

  4. Aggiungere il trigger Richiesta al flusso di lavoro seguendo i passaggi generali per aggiungere un trigger.

    Questo esempio continua con il trigger denominato Quando viene ricevuta una richiesta HTTP.

  5. 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"
            }
         }
      }
   }
}

    Screenshot mostra il flusso di lavoro Standard con il trigger di richiesta e il parametro Schema JSON del corpo della richiesta con schema di esempio.

    In alternativa, è possibile generare uno schema JSON fornendo un payload campione:

    1. Nel trigger di richiesta selezionare Usare il payload campione per generare lo schema.

    2. 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"
  }
}

    3. Quando si è pronti, selezionare Fine.

      La casella Schema JSON del corpo della richiesta ora mostra lo schema generato.

  6. Salvare il flusso di lavoro.

    La casella URL HTTP mostra ora l'URL di callback generato che altri servizi possono usare per chiamare e attivare il workflow della Logic App. Questo URL include i parametri di query che specificano una chiave Shared Access Signature (SAS), usata per l'autenticazione.

    Screenshot che mostra il flusso di lavoro Standard, il trigger di richiesta e l'URL di callback generato per l'endpoint.

  7. Copiare l'URL di callback selezionando l'icona Copia file accanto alla casella URL HTTP .

  8. 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.

  1. Nell'elenco Metodo del trigger Richiesta selezionare 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 request. In un'azione successiva è possibile ottenere i valori dei parametri come output del trigger usando la funzione triggerOutputs() in un'espressione.

  • Accetta valori tramite un percorso relativo per i parametri nell'attivatore 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

  1. Nell'elenco Metodo del trigger Request (Richiesta) selezionare il metodo GET.

    Per altre informazioni, vedere Selezionare il metodo di richiesta previsto.

  2. Aggiungere l'azione Risposta al flusso di lavoro seguendo i passaggi generali per aggiungere un'azione.

  3. Per compilare l'espressione triggerOutputs() che recupera il valore del parametro, seguire questi passi:

    1. Nell'azione 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.

    2. Nella casella dell'espressione immettere l'espressione seguente, sostituendo parameter-name con il nome del parametro, quindi selezionare OK.

      triggerOutputs()['queries']['parameter-name']

      Screenshot che mostra il flusso di lavoro Standard, l'azione Risposta e l'espressione triggerOutputs.

      Nella proprietà Corpo l'espressione viene risolta nel token triggerOutputs().

      La schermata mostra il flusso di lavoro Standard con l'espressione risolta triggerOutputs() dell'azione di risposta.

      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:

      Screenshot che mostra il flusso di lavoro Standard con l'espressione risolta dell'azione Response per il nome del parametro.

      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:

      Screenshot che mostra il flusso di lavoro Standard con l'azione

Testare l'endpoint chiamabile

  1. 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 e 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 questo testo: "Codice postale: 123456"

    Screenshot che mostra il browser con la risposta del flusso di lavoro standard dalla richiesta all'URL di callback.

Note

Se si desidera includere nell’URI il simbolo hash o cancelletto (#), usare questa versione codificata: %25%23

Accettare i valori tramite un percorso relativo

  1. Nel trigger di richiesta aprire l'elenco Parametri avanzati e selezionare Percorso relativo, che aggiunge questa proprietà al trigger.

    Screenshot che mostra il flusso di lavoro Standard, il trigger di richiesta e la proprietà aggiunta denominata Percorso relativo.

  2. 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}.

    Screenshot che mostra il flusso di lavoro Standard, il trigger di richiesta e il valore del parametro Percorso relativo.

  3. 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 Risposta restituisca Postal Code: {postalCode}.

    1. 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.

    2. Selezionare l'icona a forma di fulmine per aprire l'elenco di contenuto dinamico. Dalla sezione Quando viene ricevuta una richiesta HTTP selezionare l'output del trigger postalCode.

      Screenshot che mostra il flusso di lavoro Standard, l'azione di risposta e l'output del trigger specificato da includere nel corpo della risposta.

      La proprietà Corpo ora include il parametro selezionato:

      Screenshot che mostra il flusso di lavoro Standard e un esempio di corpo della risposta con parametro.

  4. 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}

  5. 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%7D nell'URL con 123456 e premere INVIO.

    Il browser restituisce una risposta con questo testo: "Codice postale: 123456"

    Screenshot che mostra il browser con la risposta del flusso di lavoro standard dalla richiesta all'URL di callback.

Note

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:

  1. Nella finestra di progettazione aggiungere l'azione Operazioni del flusso di lavoro denominata Chiama flusso di lavoro in questa app per la logica.

    L'elenco Nome flusso di lavoro mostra i flussi di lavoro idonei da selezionare.

  2. Nell'elenco Nome flusso di lavoro selezionare il flusso di lavoro che si desidera chiamare, ad esempio:

    Schermata che mostra il flusso di lavoro Standard, l'azione denominata Invoca un flusso di lavoro in questa app, l'elenco Nome flusso di lavoro aperto e i flussi di lavoro disponibili da richiamare.

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 specificamente alla body proprietà, è possibile usare l'espressionetriggerBody() come scorciatoia.

Rispondere alle richieste

A volte si desidera rispondere a determinate richieste che attivano il flusso di lavoro restituendo il contenuto al chiamante. Per costruire il codice di stato, l'intestazione e il corpo per la risposta, usare l'azione 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 Risposta , l'endpoint risponde immediatamente con lo stato 202 Accettato .

Affinché il chiamante originale ottenga correttamente la risposta, tutti i passaggi necessari per ottenere 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 town proprietà e postalCode , in base allo schema JSON descritto in precedenza in questo argomento per il trigger Request.

Screenshot che mostra l'azione di risposta e il tipo di contenuto della risposta.

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
Corpo 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 frequenti

Che cos'è la sicurezza degli URL per le chiamate in ingresso?

Azure genera in modo sicuro gli URL di callback delle app per la logica usando la firma di accesso condiviso. 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 sulla sicurezza, l'autorizzazione e la crittografia per le chiamate in ingresso al flusso di lavoro, ad esempio Transport Layer Security (TLS),Microsoft Entra ID Open Authentication (Microsoft Entra ID OAuth), esporre il flusso di lavoro dell'app per la logica con Gestione API di Azure o limitare gli indirizzi IP che hanno origine chiamate in ingresso, vedere Accesso sicuro e dati - Accesso per le chiamate in ingresso ai trigger basati su richiesta.

È possibile configurare ulteriormente gli endpoint chiamabili?

Sì, gli endpoint HTTPS supportano una configurazione più avanzata 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:

Contenuti correlati

  • Last updated on