Creare flussi di lavoro che è possibile chiamare, attivare o annidare usando gli endpoint HTTPS in App per la logica di Azure

  • Articolo

Si applica a: App per la logica di Azure (consumo + 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 tipi di trigger basati su richiesta seguenti:

  • Richiedi
  • Webhook HTTP
  • Trigger del connettore gestito con tipo Api Connessione ionWebhook e che possono ricevere richieste HTTPS in ingresso

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

  • Flusso di lavoro dell'app per la logica in cui si vuole usare il trigger basato su richiesta per creare l'endpoint chiamabile. È possibile iniziare con un flusso di lavoro vuoto o un flusso di lavoro esistente in cui è possibile sostituire il trigger corrente. Questo esempio inizia con un flusso di lavoro vuoto.

  • Per testare l'URL per l'endpoint chiamabile creato, è necessario uno strumento o un'app come Postman.

Creare un endpoint chiamabile

In base al fatto che si disponga di un flusso di lavoro di app per la logica standard o a consumo, seguire i passaggi corrispondenti:

  1. Nella portale di Azure aprire la risorsa dell'app per la logica Standard e il flusso di lavoro vuoto nella finestra di progettazione.

  2. Seguire questi passaggi generali per aggiungere il trigger di richiesta denominato Quando viene ricevuta una richiesta HTTP.

  3. 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 dei 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 shows Standard workflow with Request trigger and Request Body JSON Schema parameter with example schema.

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

    1. Nel trigger Richiesta selezionare Usa payload di esempio per generare lo schema.

    2. Nella casella Immettere o incollare un payload JSON di esempio immettere il payload di esempio, 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 mostra ora lo schema generato.

  4. Salvare il flusso di lavoro.

    La casella HTTP POST URL (URL POST HTTP) mostra ora l'URL di callback generato che altri servizi possono usare per chiamare e attivare il flusso di lavoro dell'app per la logica. Questo URL include parametri di query che specificano una chiave sas (Shared Access Signature), usata per l'autenticazione.

    Screenshot shows Standard workflow, Request trigger, and generated callback URL for endpoint.

  5. Per copiare l'URL di callback, sono disponibili queste opzioni:

    • A destra della casella HTTP POST URL (URL POST HTTP) selezionare Copy URL (copy files icon) (Copia URL (icona copia file).

    • Copiare l'URL di callback dalla pagina Panoramica del flusso di lavoro.

      1. Nel menu del flusso di lavoro selezionare Panoramica.

      2. Nella pagina Panoramica, in URL del flusso di lavoro spostare il puntatore sull'URL e selezionare Copia negli Appunti:

        Screenshot shows Standard workflow and Overview page with workflow URL.

  6. Per testare l'URL di callback ora disponibile per il trigger di richiesta, usare uno strumento o un'app come Postman e inviare la richiesta usando il metodo previsto dal trigger Request.

    In questo esempio viene usato il POST metodo :

    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 POST richiesta. Tuttavia, è possibile specificare un metodo diverso che il chiamante deve usare, ma solo un singolo metodo.

  1. Nel trigger Richiesta aprire l'elenco Parametri avanzati e selezionare Metodo, che aggiunge questa proprietà al trigger.

  2. Nell'elenco Metodo selezionare invece il metodo previsto dal trigger. In alternativa, è possibile specificare un metodo personalizzato.

    Ad esempio, selezionare il metodo GET in modo da poter testare l'URL dell'endpoint in un secondo momento.

Passare parametri tramite l'URL dell'endpoint

Quando si vogliono accettare i valori dei parametri tramite l'URL dell'endpoint, sono disponibili queste opzioni:

  • Accettare valori tramite parametri GET o parametri URL.

    Questi valori vengono passati come coppie nome-valore nell'URL dell'endpoint. 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 triggerOutputs() funzione in un'espressione.

  • Accettare valori tramite un percorso relativo per i parametri nel trigger di richiesta.

    Questi valori vengono passati attraverso un percorso relativo nell'URL dell'endpoint. È anche necessario selezionare in modo esplicito 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 valori tramite i parametri GET

  1. Nel trigger Request aprire i parametri Avanzati, aggiungere la proprietà Method al trigger e selezionare il metodo GET .

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

  2. Nella finestra di progettazione seguire questa procedura generale per aggiungere l'azione in cui si vuole usare il valore del parametro.

    Per questo esempio, selezionare l'azione denominata Response.

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

    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 di espressioni.

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

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

      Screenshot shows Standard workflow, Response action, and the triggerOutputs() expression.

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

      Screenshot shows Standard workflow with Response action's resolved triggerOutputs() expression.

      Se si salva il flusso di lavoro, si passa dalla finestra di progettazione e si torna alla finestra di progettazione, il token mostra il nome del parametro specificato, ad esempio:

      Screenshot shows Standard workflow with Response action's resolved expression for parameter name.

      Nella visualizzazione codice la proprietà Body viene visualizzata nella definizione dell'azione Response come indicato di seguito:

      "body": "@{triggerOutputs()['queries']['parameter-name']}",

      Si supponga, ad esempio, di voler passare un valore per un parametro denominato postalCode. La proprietà Body specifica la stringa, Postal Code: con uno spazio finale, seguita dall'espressione corrispondente:

      Screenshot shows Standard workflow with Response action and example triggerOutputs() expression.

Testare l'endpoint chiamabile

  1. Dal trigger Richiesta copiare l'URL del flusso di lavoro e incollare l'URL 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: Postal Code: 123456

    Screenshot shows browser with Standard workflow response from request to callback URL.

Nota

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

Accettare valori tramite un percorso relativo

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

    Screenshot shows Standard workflow, Request trigger, and added property named Relative path.

  2. Nella proprietà Percorso relativo specificare il percorso relativo per il parametro nello schema JSON che si vuole che l'URL accetti, /address/{postalCode}ad esempio .

    Screenshot shows Standard workflow, Request trigger, and Relative path parameter value.

  3. Nel trigger Richiesta seguire questa procedura generale per aggiungere l'azione in cui si vuole usare il valore del parametro.

    Per questo esempio, aggiungere l'azione Risposta .

  4. 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à Body immettere Postal Code: con uno spazio finale. Mantenere il cursore all'interno della casella di modifica in modo che l'elenco di contenuto dinamico rimanga aperto.

    2. Nell'elenco di contenuto dinamico, nella sezione Quando viene ricevuta una richiesta HTTP, selezionare l'output del trigger postalCode Parametri percorso.

      Screenshot shows Standard workflow, Response action, and specified trigger output to include in response body.

      La proprietà Body include ora il parametro selezionato:

      Screenshot shows Standard workflow and example response body with parameter.

  5. Salvare il flusso di lavoro.

    Nel trigger 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}

  6. 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 123456e premere INVIO.

    Il browser restituisce una risposta con questo testo: Postal Code: 123456

    Screenshot shows browser with Standard workflow response from request to callback URL.

Nota

Se si vuole includere il simbolo hash o cancelletto (#) nell'URI, usare invece 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. App per la logica di Azure flussi di lavoro hanno il supporto predefinito per gli endpoint di accesso diretto.

Token generati dallo schema

Quando si specifica uno schema JSON nel trigger Richiesta, la finestra di progettazione del flusso di lavoro genera token per le proprietà in tale schema. È quindi possibile usare questi token per passare i dati attraverso il flusso di lavoro.

Ad esempio, se si aggiungono altre proprietà, ad esempio "suite", allo schema JSON, i token per tali proprietà sono disponibili per l'uso nei passaggi successivi per il flusso di lavoro. Ecco 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 questa procedura:

  1. Nella finestra di progettazione seguire questa procedura generale per aggiungere l'azione Operazioni flusso di lavoro 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.

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

    Screenshot shows Standard workflow, action named Invoke a workflow in this workflow app, opened Workflow Name list, and available workflows to call.

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 il contenuto.

Ad esempio, se si passa contenuto con application/xml tipo, è possibile usare l'espressione@xpath()per eseguire un'estrazione XPath o usare l'espressione @json() per convertire XML in JSON. Altre informazioni sull'uso dei tipi di contenuto supportati.

Per ottenere l'output da una richiesta in ingresso, è possibile usare l'espressione @triggerOutputs. Si supponga, ad esempio, di avere un output simile all'esempio seguente:

{
   "headers": {
      "content-type" : "application/json"
   },
   "body": {
      "myProperty" : "property value"
   }
}

Per accedere in modo specifico alla body proprietà, è possibile usare l'espressione @triggerBody() come collegamento.

Rispondere alle richieste

A volte si vuole rispondere a determinate richieste che attivano il flusso di lavoro restituendo contenuto al chiamante. Per costruire il codice di stato, l'intestazione e il corpo per la risposta, usare l'azione Risposta. Questa azione può essere visualizzata in qualsiasi punto del flusso di lavoro, non solo alla fine del flusso di lavoro. 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 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 viene restituita alcuna risposta entro questo limite, la richiesta in ingresso raggiunge il timeout e riceve la risposta di timeout del client 408.

Per i flussi di lavoro annidati, il flusso di lavoro padre continua ad attendere una risposta fino al completamento di tutti i passaggi, 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 shows Response action and response content type.

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. Tuttavia, i codici di stato 3xx non sono consentiti.
Intestazioni headers Una o più intestazioni da includere nella risposta
Testo body Oggetto corpo 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 Risposta e la definizione JSON completa del flusso di lavoro, passare dalla visualizzazione della 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: Informazioni sulla sicurezza degli URL per le chiamate in ingresso?

R: Azure genera in modo sicuro gli URL di callback delle app per la logica usando la firma di accesso condiviso. Questa firma passa come parametro di query e deve essere convalidata prima che il flusso di lavoro possa essere eseguito. 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. A meno che un utente non abbia accesso alla chiave dell'app per la logica segreta, non può generare una firma valida.

Importante

Per i sistemi di produzione e sicurezza più elevati, è consigliabile non chiamare il flusso di lavoro direttamente dal browser per questi motivi:

  • La chiave di accesso condiviso viene visualizzata nell'URL.
  • Non è possibile gestire i criteri dei contenuti di sicurezza a causa di domini condivisi tra i clienti 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), noto in precedenza come Secure Sockets Layer (SSL), Microsoft Entra ID Open Authentication (Microsoft Entra ID OAuth), esporre il flusso di lavoro dell'app per la logica con Azure Gestione API 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.

D: È possibile configurare ulteriormente gli endpoint chiamabili?

R: Sì, gli endpoint HTTPS supportano una configurazione più avanzata tramite Azure Gestione API. 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:

Passaggi successivi