Attività HTTP
Durante l'esecuzione del piano, puoi creare un'attività per inviare richieste HTTP a un endpoint di applicazioni di terze parti. Ad esempio, quando un'attività precedente viene eseguita correttamente, puoi inviare un messaggio HTTP a un endpoint designato con le informazioni relative a tale attività.
Nella visualizzazione Piano puoi creare attività HTTP per inviare una richiesta agli endpoint prima o dopo l'esecuzione di altre attività. Puoi anche utilizzare l'attività HTTP per generare un set di dati con una risposta a una chiamata API utilizzabile nel flusso di lavoro in Designer Cloud. Tali attività sono specificate nel pannello contestuale destro.
Un 'attività HTTP è una richiesta tra Alteryx One Platform e un'altra applicazione. Queste richieste vengono inviate tramite HTTP e possono essere interpretate dall'applicazione ricevente per intraprendere un'azione.
Nota
L'applicazione ricevente potrebbe richiedere di inserire nella whitelist l'host e il numero di porta o l'indirizzo IP della piattaforma. Consulta la documentazione relativa all'applicazione.
Un'attività HTTP è un tipo di attività disponibile in un piano. Per ulteriori informazioni, consulta la pagina Visualizzazione piano.
Limitazioni
Per il set di dati di input (Carica configurazione da set di dati):
Righe: 10.000
Dimensione file: 1 GB
Dimensione riga: 100 MB
Le richieste basate su HTTP hanno un limite di timeout di 30 secondi.
Non è possibile utilizzare certificati di sicurezza personalizzati.
Prerequisiti
Requisiti per l'applicazione ricevente
Per inviare una richiesta HTTP a un'applicazione di destinazione, è necessario configurare l'applicazione in modo che riceva la richiesta:
Le richieste provenienti dall'esterno del dominio dell'applicazione devono essere abilitate.
Nota
L'applicazione ricevente potrebbe richiedere di inserire nella whitelist l'host e il numero di porta o l'indirizzo IP della piattaforma. Consulta la documentazione relativa all'applicazione.
È necessario acquisire l'URL dell'endpoint a cui inviare la richiesta HTTP.
È necessario acquisire le intestazioni HTTP che devono essere inserite con ogni richiesta HTTP.
Se la richiesta deve essere firmata, è necessaria una configurazione aggiuntiva. I dettagli sono riportati di seguito.
Creazione dell'attività
Trascina l'attività HTTP dal riquadro a sinistra nell'area di disegno del piano.
Nel pannello a destra, seleziona Attività HTTP. Viene visualizzato il pannello Attività HTTP.
Figura: Attività HTTP
Campo | Descrizione |
|---|---|
Metodo | Seleziona il metodo HTTP da utilizzare per consegnare il messaggio. Il metodo appropriato dipende dall'applicazione di destinazione. La maggior parte dei casi di utilizzo richiede il metodo |
URL | URL a cui l'altra applicazione riceve la richiesta HTTP. |
Intestazioni | Inserisci le intestazioni dei contenuti HTTP come coppie chiave-valore. Se ad esempio il corpo è in formato JSON, devi includere l'intestazione seguente: key: Content-Type value: application/json Nota Per la chiave |
Corpo | (Solo metodi {"text":"My text message to the receiving application."}Suggerimento Come parte dei campi del corpo della richiesta o dell'intestazione, puoi inserire metadati che fanno riferimento alla definizione del piano, all'esecuzione corrente, alle attività già completate nell'ambito dell'esecuzione, ai dati delle colonne e alle origini dati. Per ulteriori informazioni sui metadati disponibili, vedi Riferimenti ai metadati del piano. |
Chiave segreta | (Facoltativo) È possibile utilizzare una chiave segreta per verificare il payload della richiesta. Il valore del segreto deve essere inserito in questa posizione e deve essere incluso nel codice utilizzato per elaborare le richieste nell'applicazione di destinazione. Inserisci qui il valore del segreto, in formato stringa senza virgolette. |
Convalida del certificato SSL | Se impostata su Nota Se hai l'esigenza di inviare una richiesta a un endpoint che ha un certificato scaduto o non valido, devi disabilitare la verifica SSL. |
Riprova | Se il codice di stato restituito non rientra nell'intervallo 200-299, l'attività HTTP è considerata non riuscita. Quando questa opzione è abilitata, la richiesta viene ritentata. Se la richiesta non riesce, questo valore indica il numero dei tentativi da eseguire. Se nessuno di questi tentativi ha successo, l'attività non riesce. |
Crea set di dati da risposta | Quando ha valore |
Configurazione dell'attività
Imposta i parametri richiesti. Per ulteriori informazioni sui parametri, consulta la sezione Visualizzazione piano per le attività HTTP.
Puoi specificare le informazioni sui metadati del piano nei valori dell'intestazione e nel corpo della richiesta. Per ulteriori informazioni, consulta la sezione Riferimenti ai metadati del piano.
Per verificare la connessione, fai clic su Test. Viene visualizzato un messaggio di operazione riuscita.
Suggerimento
Un codice di stato 200 indica che il test è stato eseguito correttamente.
Suggerimento
Puoi utilizzare il metodo GET per i test. Una richiesta GET non modifica alcun dato sulla piattaforma di destinazione, ma può consentire di specificare elementi nel corpo della richiesta.
Per aggiungere l'operazione, fai clic su Salva.
Rinomina di un'attività
Per rinominare l'attività, fai clic sul menu Altro > Modifica nel pannello a destra.
Suggerimento
Una denominazione valida può includere l'endpoint e il metodo della piattaforma di destinazione, nonché gli scopi dell'attività nel piano.
Eliminazione di un'attività
Per eliminare l'attività, fai clic sul menu Altro > Elimina. Conferma di voler eliminare l'attività.
Avvertimento
Questa operazione non può essere annullata.
Riferimenti ai metadati del piano
All'interno del messaggio delle altre attività, puoi fare riferimento ai metadati relativi al piano, alle sue attività e alla loro esecuzione. Per ulteriori informazioni, consulta la sezione Riferimenti ai metadati del piano.
Esempi
Messaggio del canale Slack
Suggerimento
Le attività Slack sono ora una funzionalità supportata del prodotto.
Puoi creare un'attività HTTP per inviare un messaggio di testo a un canale Slack a scelta.
Imposta l'installazione Slack per ricevere messaggi HTTP:
Se necessario, crea un canale Slack per ricevere i messaggi.
Crea un'app.
Attiva i messaggi HTTP in arrivo per l'app.
Specifica il canale per la ricezione dei messaggi in arrivo.
Copia l'URL per la richiesta HTTP in entrata dall'istruzione cURL.
Parametro | Descrizione |
|---|---|
Nome | Questo nome viene visualizzato solo in Alteryx One. |
Metodo | Seleziona il metodo |
Url | Incolla l'URL copiato da Slack. |
Intestazioni | Copia le intestazioni del contenuto dal comando cURL di Slack: key: Content-Type value: application/json |
Corpo | {"text":"Your job has completed."} |
Fai clic su Test per verificare che l'attività funzioni.
Esegui un lavoro e verifica la presenza di un messaggio nel canale Slack.
Pianificazione degli esempi di metadati
Puoi fare riferimento alle informazioni sui metadati dalla definizione del piano e dall'esecuzione del piano corrente come parte della richiesta dell'attività HTTP.
Note:
Puoi inserire solo riferimenti ai metadati per le attività che hanno già avuto luogo nell'esecuzione del piano prima dell'inizio dell'attività HTTP.
Per ogni attività nell'esecuzione corrente viene utilizzato come riferimento un codice a due lettere. Esempio:
{{$http_xx.name}}
Per costruire un riferimento ai metadati del piano si utilizza la sintassi seguente. Nella casella di testo appropriata, immetti uno dei seguenti valori:
Suggerimento
Inizia digitando $, che consente di accedere a una struttura ad albero di menu con riferimenti ai metadati per ogni tipo di riferimento ai metadati. La sintassi finale è riportata sopra.
Piani:
Informazioni sui metadati dalla definizione del piano o dall'esecuzione del piano corrente:
{{$planIl seguente corpo della richiesta contiene riferimenti al nome del piano, all'identificatore dell'esecuzione del piano e al flusso appena eseguito:
{"text":"Plan: {{$plan.name}}
RunId: {{$plan.runId}}
Flow: {{$flow_7p.name}}
Success."}Il seguente corpo della richiesta contiene informazioni sull'esecuzione del piano utilizzando timestamp:
{"text":"Plan: {{$plan.name}}
RunId: {{$plan.runId}}
- plan start: {{$plan.startTime}}
Running time: {{$plan.duration}}
Times:
- last task start: {{$flow_7p.startTime}}
- last task end: {{$flow_7p.endTime}}
"}È possibile consultare le informazioni di un'attività HTTP che si è già verificata:
{"text":"{{$http_qg.name}} returned {{$http_qg.statusCode}}."} Per ulteriori informazioni, consulta la sezione Riferimenti ai metadati del piano.
Invio di metadati di input alla funzione cloud
In questo esempio viene illustrato come utilizzare un'attività HTTP per fornire metadati del piano alle funzioni AWS Lambda. Un approccio simile potrebbe essere utilizzato per le funzioni di Google Cloud.
In questo caso, il valore rowCount ricavato dall'esecuzione dell'attività di flusso viene fornito tramite un'attività HTTP a una funzione AWS Lambda.
Passaggi generali:
Definisci il piano.
Attività di flusso: esegui il flusso per generare gli output necessari per la funzione Lambda.
Attività HTTP: genera una richiesta HTTP il cui corpo include un riferimento alla variabile di metadati rowCount. Corpo della richiesta:
{ "rowCount": "{{$flow_7p['My Flow Name'].output['My output name'].rowCount}}" }Funzioni AWS Lambda: di seguito è riportato uno pseudo-codice per Lambda:
import json def lambda_handler(event, context): httpTaskBody = json.loads(event["body"]) rowCount = httpTaskBody["rowCount"] return { 'statusCode': 200, 'body': json.dumps(rowCount) }Funzioni Google Cloud: di seguito è riportato uno pseudo-codice per le funzioni Google Cloud:
def get_row_count(request): request_json = request.get_json() if request_json and 'rowCount' in request_json: rowCount = request_json['rowCount'] return rowCount return 'No rowCount attribute provided'
Creazione di un set di dati con la risposta API per il flusso di lavoro Designer Cloud
In Plans puoi usare l'attività HTTP per leggere e generare set di dati con risposte a chiamate API, che possono essere utilizzati in modo naturale nel flusso di lavoro Designer Cloud.
Parametro | Descrizione |
|---|---|
Nome | Questo nome viene visualizzato solo in Alteryx One. |
Metodo | Campo obbligatorio. Seleziona il metodo |
URL | Campo obbligatorio. URL a cui l'altra applicazione riceve la richiesta HTTP. Esempio: |
Intestazioni | Intestazioni dei contenuti HTTP come coppie chiave-valore in formato JSON. {
"X-Custom-Header": "value",
"X-Parametrized-Header": "${wf1.id}"
} |
Corpo | Corpo della richiesta inviato all'applicazione di destinazione. Può contenere {"text":"My text message to the receiving application."} |
Passaggi generali:
Crea un flusso di lavoro con il tuo input.
Crea ed esegui un piano con un'attività HTTP per la generazione di un set di dati.
Assicurati di deselezionare la casella di spunta Elimina set di dati con risposta a chiamata API, impostando l'attività in modo da mantenere il set di dati.
In Designer Cloud, usa il set di dati generato nel passaggio precedente per creare un flusso di lavoro che comincia con la risposta API.
Selezionando la casella di spunta Carica configurazione da set di dati hai la possibilità di caricare una configurazione (con tutti i parametri) dal set di dati di output dell'attività del flusso di lavoro a monte.
Attenzione
Per informazioni sulle limitazioni del set di dati di input, vedi la sezione Limitazioni.
In Piano, aggiungi il flusso di lavoro come attività a valle per un'attività HTTP preesistente. Modifica il piano in modo da utilizzare l'output dell'attività HTTP (specificato nel Passaggio 1) come input del flusso di lavoro Designer Cloud.
Ora puoi pianificare il Piano. Questa configurazione effettua una chiamata API e la risposta viene passata al flusso di lavoro Designer Cloud, che viene eseguito. L'output finale è disponibile come sempre.
Verifica delle firme
Avvertimento
A seconda dell'applicazione di destinazione, l'implementazione della verifica della firma può richiedere competenze da parte dello sviluppatore.
Facoltativamente, puoi configurare la piattaforma per firmare le richieste HTTP. Le richieste firmate rappresentano una garanzia, in quanto sono inviate dalla piattaforma e non da terze parti.
Di seguito, puoi vedere come viene creata la firma, per poter configurare l'applicazione ricevente in modo che elabori correttamente la firma e la relativa richiesta.
Intestazione firma
Le richieste HTTP vengono firmate inserendo l'intestazione X-Webhook-Signature nella richiesta. Queste firme presentano la forma seguente:
X-Webhook-Signature: t=<timestamp>,sha256=<signature>
dove:
<Timestamp>: indicatore di data e ora dell'invio della firma. Il valore è rappresentato con l'indicatore di orario UNIX.<Signature>: firma SHA256. La piattaforma genera questa firma utilizzando un codice di autenticazione dei messaggi (HMAC) basato su hash con SHA-256.
Ulteriori informazioni su questi valori sono disponibili di seguito.
Esempio:
X-Webhook-Signature: t=1568818215724,sha256=55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a
Verifica degli strumenti dell'applicazione
A seconda dell'applicazione, potrebbe essere necessario completare una delle seguenti serie di attività per verificare le firme delle attività:
Nota
Potresti aver bisogno di inserire la piattaforma nella whitelist dell'applicazione. Per ulteriori informazioni, consulta la documentazione dell'applicazione.
Potresti aver bisogno di creare una codifica personalizzata per l'applicazione. Di seguito, puoi rivedere i dettagli su come farlo, incluso un esempio JavaScript.
Elaborazione delle richieste firmate
Il valore timestamp (t=<timestamp>) viene visualizzato all'inizio del valore dell'intestazione per evitare replay attack, in cui un utente malintenzionato può intercettare un payload valido e la sua firma e ritrasmetterli.
Per evitare tali attacchi, nell'intestazione della firma viene incluso un timestamp, che viene incorporato anche all'interno del payload firmato.
Poiché il timestamp fa parte del payload firmato, un utente malintenzionato non può modificarne il valore senza invalidare la firma.
Se la firma è valida ma il timestamp è troppo vecchio, puoi rifiutare la richiesta.
Ad esempio, se ricevi una richiesta con un timestamp che corrisponde a una data di un'ora fa, probabilmente dovresti rifiutare la richiesta.
Per ulteriori informazioni sui replay attack, consulta https://en.wikipedia.org/wiki/Replay_attack.
Nell'ambito del suo valore hash, la firma dell'attività include:
La chiave segreta (immessa sopra)
Il valore timestamp
Dati della richiesta:
(POST/PUT/PATCH): il corpo della richiesta
(GET/DELETE): URL della richiesta
Suddividi l'intestazione X-Webhook-Signature:
Suddividi i valori utilizzando la virgola (,) come separatore.
Suddividi ogni parte utilizzando il simbolo uguale (=).
Estrai i valori per timestamp e firma. Dall'esempio precedente:
timestamp:
1568818215724firma:
55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a
Nell'applicazione ricevente, puoi ricalcolare la firma per verificare che la richiesta sia stata inviata dalla piattaforma.
Concatena il timestamp, il carattere punto (.) e il corpo della richiesta (metodi POST/PUT/PATCH) o l'URL (metodi GET/DELETE).
Supponiamo che l'esempio riportato sopra sia la firma per una richiesta
POSTe che il corpo della richiesta siatest. Il valore concatenato è il seguente:1568818215724.test
Ora puoi calcolare il codice di autenticazione HMAC nell'applicazione ricevente. Nell'esempio JavaScript seguente, il valore della chiave segreta è
mySecret:const crypto = require('crypto'); const message = '1568818215724.test'; // as defined above const hmac = crypto.createHmac('sha256', 'mySecret'); hmac.update(message) const expectedSignature = hmac.digest('hex');
Confronta il valore restituito dal codice e il valore incluso come firma nell'intestazione X-Webhook-Signature:
Se i valori non corrispondono, rifiuta la richiesta.
Se i valori corrispondono, calcola la differenza tra il timestamp corrente e quello nell'intestazione. Se la differenza non rientra nel limite consentito, rifiuta la richiesta.
In caso contrario, elabora la richiesta normalmente nell'applicazione.
Caricamento della configurazione HTTP da un set di dati
Se hai l'esigenza di creare una richiesta API dinamica o più richieste, puoi utilizzare Designer Cloud per definire un output con la configurazione e passarlo all'attività HTTP in Plans.
Per definire un output con la configurazione e utilizzarlo per l'attività HTTP, procedi come segue:
Crea un flusso di lavoro in Designer Cloud. Per ulteriori informazioni, consulta la sezione Creazione di flussi di lavoro.
Nel flusso di lavoro, per l'output imposta un file in formato CSV che contiene le colonne seguenti (i nomi non distinguono tra maiuscole e minuscole):
Metodo (stringa, valori: GET | POST | DELETE | PUT)
URL (stringa, URL della richiesta)
Intestazioni (stringa, elenco di intestazioni con valori in formato {"Nome":"Valore", "Nome":"Valore", ...}),
Corpo (stringa)
Vai a Plans e crea un piano.
Aggiungi un'attività Designer Cloud e seleziona il flusso di lavoro appena creato.
Aggiungi un'attività HTTP dopo l'attività Designer Cloud e connettila con una riga di connettore.
Nella configurazione HTTP, seleziona la casella di spunta Carica configurazione da set di dati e la casella di spunta Carica configurazione da set di dati.
Premi il pulsante Seleziona set di dati di input.
Scegli l'attività Designer Cloud e i relativi dati di output con la configurazione HTTP.
Seleziona Conferma.
La casella di spunta Crea set di dati da risposta viene selezionata automaticamente. Puoi personalizzare il nome del set di dati ed eseguire il piano.
Nota
Ogni riga nel file di output della configurazione conduce a una richiesta separata. La risposta a ciascuna richiesta viene aggiunta come riga al set di dati di output.
Uso di una risposta HTTP come input per l'attività a valle
Dopo aver impostato l'attività HTTP in modo da creare un set di dati a partire da una risposta, puoi utilizzare questo set di dati come input per le attività a valle.
Per utilizzare il set di dati come input per le attività a valle, procedi come segue:
Nella configurazione HTTP, seleziona la casella di spunta Crea set di dati da risposta.
Aggiungi un'attività Designer Cloud dopo l'attività HTTP e connettila con una riga di connettore.
Nell'attività Designer Cloud, seleziona il flusso di lavoro desiderato.
Nell'elenco degli input del flusso di lavoro, seleziona Sostituzione per l'input che desideri sostituire con la risposta HTTP.
Seleziona l'attività HTTP e il relativo output.
Seleziona Conferma ed esegui il piano.