I webhook in tempo reale di Bird event webhooks sono uno strumento incredibilmente prezioso per i mittenti per avere dati automaticamente inviati ai loro sistemi. Questo può guidare automazioni a valle come l'aggiornamento delle liste di distribuzione, l'attivazione di viaggi email automatizzati o la popolazione di dashboard interne. Anche se gli stessi dati degli eventi possono essere accessibili tramite l'interfaccia utente di Bird utilizzando Event Search, o programmaticamente sfruttando il Events API di Bird, le limitazioni imposte sul numero di record restituiti in una singola richiesta o sui limiti di velocità posti sull'endpoint API possono rendere entrambi questi metodi restrittivi per mittenti grandi e sofisticati.
I webhook di eventi in tempo reale consentono a un mittente di configurare un endpoint in cui Bird trasmette i dati e i dati possono essere consumati senza dover pianificare job cron che estraggono i dati. Ci sono anche compromessi logistici quando si estraggono i dati rispetto ad avere i dati spinti a te, come dover identificare quale periodo di tempo e quali parametri utilizzare per ciascuna richiesta API. Se i periodi di tempo non sono allineati perfettamente, allora rischi di perdere dati, e se i periodi di tempo si sovrappongono, allora devi gestire record di dati duplicati. Con i webhook in tempo reale, i dati degli eventi vengono semplicemente inviati al tuo endpoint man mano che diventano disponibili all'interno di Bird.
Sebbene i vantaggi di ricevere dati degli eventi in tempo reale per guidare i processi di automazione a valle possano essere immediatamente compresi da molti mittenti, il processo effettivo per implementare e consumare i webhook può essere intimidatorio. Questo può essere particolarmente vero se non sei familiare con i componenti tecnici per creare un endpoint e gestire i dati programmaticamente. Ci sono servizi disponibili che consumeranno i dati dei webhook di Bird e li ETL nel tuo database automaticamente – un esempio sarebbe StitchData, di cui abbiamo parlato nel passato. Tuttavia, se desideri più controllo sul processo, puoi facilmente costruire i componenti tu stesso. Di seguito è fornito un semplice guida per aiutare i mittenti a sentirsi a proprio agio quando creano un webhook di eventi Bird e consumano i dati utilizzando l'infrastruttura all'interno di AWS.
Configurazione dell'Endpoint di Destinazione del Webhook
Quando un evento Bird viene creato, vogliamo che quei dati degli eventi vengano trasmessi in tempo reale a un endpoint in AWS in modo che possiamo consumare e utilizzare quei dati programmaticamente. I dati saranno inviati da Bird a un endpoint di destinazione, che inoltrerà il payload a una funzione lambda che elaborerà e memorizzerà i dati in un bucket S3. Un diagramma ad alto livello del flusso di dati descritto può essere visto qui sotto:
Per implementare questo flusso di lavoro, iniziamo a costruire in ordine inverso, iniziando dalla creazione di un bucket S3 dove memorizzeremo i nostri dati degli eventi e poi lavoreremo all'indietro, aggiungendo ciascun componente che alimenta ciò che abbiamo costruito.
Crea un Bucket S3 per Memorizzare i Dati del Webhook
Prima di creare il nostro bilanciatore di carico per accettare i dati, o la nostra funzione lambda per memorizzare i dati, dobbiamo prima creare il nostro bucket S3 dove i dati saranno memorizzati. Per fare questo, naviga al servizio S3 all'interno di AWS e premi “Crea Bucket.” Ti verrà chiesto di assegnare un nome al tuo bucket e impostare la regione – assicurati di utilizzare la stessa regione del tuo ALB e della tua funzione lambda. Quando il tuo bucket S3 viene creato, sarà vuoto – se desideri organizzare i dati all'interno di una cartella, puoi creare ora la directory prevista, oppure la directory verrà creata quando la tua funzione lambda memorizza il file. In questo esempio, abbiamo nominato il nostro bucket S3 “bird-webhooks” e creato una cartella chiamata “Dati Eventi B” per memorizzare i nostri dati degli eventi – vedrai questi nomi referenziati nella nostra funzione lambda qui sotto.
Crea una Funzione Lambda per Consumare i Dati
La reale elaborazione e memorizzazione dei dati sarà eseguita da una funzione lambda che viene invocata dal nostro bilanciatore di carico dell'applicazione (ALB).
Il primo passo è creare la tua funzione lambda navigando al servizio Lambda all'interno di AWS e cliccando “Crea Funzione.” Ti verrà chiesto di assegnare un nome alla tua funzione lambda e scegliere in quale linguaggio di programmazione scrivere la tua funzione. Per questo esempio, utilizziamo Python come linguaggio runtime.
Ora dobbiamo sviluppare la nostra funzione lambda. Per un momento, assumiamo che il nostro bilanciatore di carico dell'applicazione sia stato configurato e stia inoltrando il payload del webhook alla nostra funzione lambda – la lambda riceverà un payload che include gli header e il corpo completi. Il payload è passato alla nostra funzione lambda utilizzando l'oggetto “event” come dizionario. Puoi fare riferimento agli header e al corpo del payload indipendentemente accedendo agli oggetti “headers” e “body” all'interno del payload. In questo esempio, leggeremo semplicemente l'header “x-messagesystems-batch-id”, dove l'ID batch è un valore unico creato da Bird per il batch del webhook e lo useremo come nome file quando memorizziamo il corpo come file flat in S3; tuttavia, potresti voler aggiungere funzionalità aggiuntive come controlli di autenticazione o gestione degli errori, se necessario.
Quando memorizziamo il payload in un file flat su S3, dovremo definire il nome del bucket S3, la posizione e il nome del file in cui i dati del payload saranno memorizzati. Nella nostra funzione lambda di esempio, lo facciamo all'interno della funzione “store_batch”. In questo esempio, memorizzeremo l'intero batch come un singolo file, il che aiuta a garantire che i dati vengano raccolti e memorizzati prima che la connessione HTTP tra Bird e il tuo endpoint scada. Sebbene tu possa regolare le impostazioni di timeout di connessione sul tuo bilanciatore di carico, non ci sono garanzie che la connessione non scadrà sul lato di trasmissione (in questo caso Bird) o che la connessione non verrà terminata prima che la tua funzione lambda termini l'esecuzione. È una buona prassi mantenere la tua funzione di consumo il più efficiente possibile e riservare le attività di elaborazione dei dati per processi a valle dove possibile – come convertire il payload formattato in JSON in un file CSV o caricare i dati degli eventi in un database.
È importante notare che potresti dover aggiornare le autorizzazioni per la tua funzione lambda. Il tuo ruolo di esecuzione avrà bisogno di autorizzazioni PutObject e GetObject per S3. È una buona prassi applicare il principio del minimo privilegio, quindi consiglio di impostare queste autorizzazioni solo per il bucket S3 dove saranno memorizzati i payload dei webhook.
Un campione della nostra funzione lambda di consumo può essere trovato qui.
Come nota veloce sull'ID batch: Bird raggrupperà eventi in un singolo payload, dove ogni batch può contenere da 1 a 350 o più record di eventi. Il batch verrà dato un ID batch unico, che può essere utilizzato per visualizzare lo stato batch sfruttando il Event Webhooks API o all'interno del tuo account Bird cliccando su uno stream webhook e selezionando “Stato Batch.” Nel caso in cui un payload webhook non possa essere consegnato, ad esempio durante un timeout di connessione, Bird riproverà automaticamente il batch utilizzando lo stesso ID batch. Questo può accadere quando la tua funzione lambda sta eseguendo vicino al tempo massimo di round-trip di 10 secondi ed è un motivo per ottimizzare la funzione di consumo per ridurre il tempo di esecuzione.
Per gestire tutte le attività di elaborazione dei dati, consiglio di creare una funzione lambda separata che venga eseguita ogni volta che un nuovo file viene creato nel bucket S3 – in questo modo, l'elaborazione dei dati viene eseguita in modo asincrono alla trasmissione dei dati e non c'è rischio di perdere dati a causa di una connessione terminata. Discuterò la funzione lambda di elaborazione in una sezione successiva.
Crea un Bilanciatore di Carico delle Applicazioni
Per ricevere un payload webhook, dobbiamo fornire un endpoint a cui inviare i payload. Facciamo questo creando un bilanciatore di carico delle applicazioni all'interno di AWS navigando in EC2 > Load Balancers e cliccando “Crea Load Balancer.” Ti verrà chiesto di scegliere quale tipo di bilanciatore di carico desideri creare – per questo, vogliamo creare un bilanciatore di carico delle applicazioni. Dobbiamo utilizzare un bilanciatore di carico delle applicazioni (ALB) per costruire il nostro consumatore perché i webhook di eventi saranno inviati come una richiesta HTTP, e gli ALB sono utilizzati per instradare le richieste HTTP all'interno di AWS. Potremmo implementare un Gateway HTTP come alternativa; tuttavia, utilizziamo un ALB per questo progetto perché è più leggero e conveniente rispetto a un Gateway HTTP. È importante notare che se scegli di utilizzare un Gateway HTTP, il formato dell'evento potrebbe essere diverso rispetto a un ALB, quindi la tua funzione lambda dovrà gestire l'oggetto richiesta di conseguenza.
Una volta creato il tuo ALB, ti verrà chiesto di assegnare un nome al tuo ALB e configurare lo schema e le impostazioni di accesso/sicurezza – poiché intendiamo ricevere dati degli eventi da una fonte esterna (Bird), vorremmo che il nostro ALB fosse visibile su Internet. Sotto “Ascoltatori e instradamento,” l'ALB dovrebbe ascoltare HTTPS sulla porta 443 e vogliamo creare un gruppo di destinazione che punta alla nostra funzione lambda in modo che il nostro ALB inoltri le richieste in entrata alla funzione lambda di consumo che abbiamo creato sopra. Devi anche assicurarti che il gruppo di sicurezza abbia il permesso di accettare traffico attraverso la porta 443.
Crea un Record DNS per il Bilanciatore di Carico
Per rendere più facile utilizzare il nostro ALB come endpoint, creeremo un record A in DNS che punta al nostro ALB. Per questo, possiamo utilizzare il servizio AWS Route 53 (o il tuo attuale fornitore di DNS) e creare un record A per il nome host che desideri utilizzare per il tuo endpoint (ad es. spevents.<tuo_dominio>). Il record A dovrebbe essere configurato per puntare all'ALB che abbiamo creato. Se stai utilizzando Route 53 per gestire i record DNS, puoi fare riferimento direttamente all'istanza ALB abilitando “Alias” e selezionando l'ALB; in caso contrario, se stai utilizzando un fornitore di DNS esterno, dovresti puntare il record A all'indirizzo IP pubblico dell'istanza ALB.
Consiglio di utilizzare uno strumento come Postman per testare che tutto sia stato configurato correttamente prima di attivare il tuo webhook di Bird. Puoi effettuare una richiesta POST al tuo endpoint e confermare che venga ricevuta una risposta. Se la tua richiesta POST non restituisce una risposta, potrebbe essere necessario ricontrollare che il tuo ALB stia ascoltando sulla porta corretta.
Crea un Webhook Bird
Ora siamo pronti a creare il webhook in Bird e utilizzare il nome host definito dal record A sopra come nostro endpoint di destinazione. Per creare il webhook, vai alla sezione Webhooks all'interno del tuo account Bird e clicca “Crea Webhook.” Ti verrà chiesto di assegnare un nome al tuo webhook e fornire un URL di destinazione – il target dovrebbe essere il nome host del record A che hai creato in precedenza. Nota che l'URL di destinazione potrebbe richiedere di includere “HTTPS://” nell'URL.
Una volta completato, verifica che il sottoconto corretto e gli eventi siano selezionati, e premi “Crea Webhook” per salvare la tua configurazione. I dati degli eventi per tutti i tipi di eventi selezionati verranno ora trasmessi al nostro URL di destinazione e consumati dal nostro ALB per l'elaborazione a valle.
Elaborazione dei Dati degli Eventi del Webhook
A seconda dello scopo previsto per memorizzare i dati degli eventi di Bird, i tuoi requisiti potrebbero essere soddisfatti semplicemente memorizzando il payload JSON come file flat. Potresti anche avere un processo ETL a valle già stabilito che è in grado di consumare e caricare i dati in formato JSON. In entrambi questi casi, potresti essere in grado di utilizzare il file flat creato dalla nostra funzione lambda di elaborazione che abbiamo creato sopra così com'è.
Alternativamente, potresti aver bisogno di trasformare i dati – ad esempio, convertendo da un formato JSON a un formato CSV – o caricare i dati direttamente in un database. In questo esempio, creeremo una semplice funzione lambda che convertirà i dati del webhook dal formato JSON originale in un file CSV che potrebbe essere caricato in un database.
Crea una Lambda per Elaborare i Dati
Come per la funzione lambda per consumare i dati del webhook, dobbiamo creare una nuova funzione lambda navigando al servizio Lambda all'interno di AWS e premendo “Crea Funzione.” Questa nuova funzione lambda verrà attivata quando un nuovo file viene creato nel nostro bucket S3 – leggerà i dati e li convertirà in un nuovo file csv.
La funzione lambda accetta le informazioni sul file come evento. Nella funzione lambda di esempio, vedrai che prima abbiamo una serie di controlli di validazione per garantire che i dati siano completi e formattati come previsto. Successivamente, convertiamo il payload JSON in un file CSV utilizzando la libreria “csv” e scrivendo su un file temporaneo. Le funzioni lambda possono scrivere solo file locali nella directory “/tmp”, quindi creiamo un file csv temporaneo e lo nominiamo con la convenzione <batch_id>.csv. Il motivo per cui utilizziamo qui l'ID batch è semplicemente per assicurarci che eventuali processi paralleli che vengono eseguiti a seguito della ricezione di più payload webhook non interferiscano tra loro, poiché ogni batch webhook avrà un ID batch unico.
Una volta che i dati sono stati completamente convertiti in CSV, leggiamo i dati CSV come uno stream di byte, eliminiamo il file temporaneo e salviamo i dati CSV come un nuovo file su S3. È importante notare che è necessario un bucket S3 diverso per l'output, altrimenti rischiamo di creare un loop ricorsivo che può portare a un utilizzo aumentato di lambda e costi aumentati. Dobbiamo identificare in quale bucket S3 e posizione vogliamo memorizzare il nostro file CSV all'interno della nostra funzione lambda. Segui la stessa procedura di cui sopra per creare un nuovo bucket S3 per memorizzare il nostro file CSV.
Nota che la directory tmp è limitata a 512 MB di spazio, quindi è importante che il file temporaneo venga eliminato dopo per garantire spazio sufficiente per le esecuzioni future. Il motivo per cui utilizziamo un file temporaneo, invece di scrivere direttamente su S3, è per semplificare la connessione a S3 avendo una singola richiesta.
Proprio come con la funzione lambda di consumo, potresti dover aggiornare le autorizzazioni per la tua funzione lambda di processo. Questa funzione lambda richiede che il ruolo di esecuzione abbia autorizzazioni GetObject per il bucket S3 di input, e sia PutObject che GetObject per il bucket S3 di output.
Un campione della nostra funzione lambda di elaborazione può essere trovato qui.
Configura una Lambda per Eseguire Quando Nuovi Dati Vengono Memorizzati su S3
Ora che la nostra funzione lambda per convertire il file da formato JSON a CSV è stata creata, dobbiamo configurarla per attivarsi quando viene creato un nuovo file nel nostro bucket S3. Per fare ciò, dobbiamo aggiungere un trigger alla nostra funzione lambda aprendo la nostra funzione lambda e cliccando “Aggiungi Trigger” in cima alla pagina. Seleziona “S3” e fornisci il nome del bucket S3 dove sono memorizzati i payload webhook grezzi. Hai anche la possibilità di specificare il prefisso del file e/o il suffisso per filtrare. Una volta configurate le impostazioni, puoi aggiungere il trigger cliccando “Aggiungi” nella parte inferiore della pagina. Ora la tua funzione lambda di elaborazione sarà eseguita ogni volta che un nuovo file viene aggiunto al tuo bucket S3.
Caricare i Dati in un Database
In questo esempio, non tratterò il caricamento dei dati in un database in dettaglio, ma se hai seguito questo esempio hai alcune opzioni:
Caricare i dati direttamente nel tuo database all'interno della tua funzione lambda di elaborazione
Consumare il tuo file CSV utilizzando un processo ETL stabilito
Che tu stia utilizzando un servizio di database AWS, come RDS o DynamoDB, o che tu abbia il tuo database PostgreSQL (o simile), puoi connetterti al tuo servizio di database direttamente dalla tua funzione lambda di processo. Ad esempio, nello stesso modo in cui abbiamo chiamato il servizio S3 utilizzando “boto3” nella nostra funzione lambda, potresti anche utilizzare “boto3” per chiamare RDS o DynamoDB. Il servizio AWS Athena potrebbe anche essere utilizzato per leggere i file dati direttamente dai file flat e accedere ai dati utilizzando un linguaggio di query simile a SQL. Ti consiglio di riferirti alla documentazione rispettiva per il servizio che stai utilizzando per ulteriori informazioni su come meglio realizzare questo all'interno del tuo ambiente.
Allo stesso modo, ci sono molti servizi disponibili che possono aiutare a consumare file CSV e caricare i dati in un database. Potresti già avere un processo ETL stabilito che puoi sfruttare.
Speriamo che questa guida ti sia stata utile – buona invio!