Un outil de tableau de bord avec les API d'oiseaux

Zacharie Samuels

24 mars 2022

Email

1 min read

Un outil de tableau de bord avec les API d'oiseaux

Zacharie Samuels

24 mars 2022

Email

1 min read

Un outil de tableau de bord avec les API d'oiseaux

Ce script effleure à peine la surface de ce qui est possible en utilisant Python, Plotly Dash et nos API.

Il y a presque un an, Tom Mairs, directeur du succès client chez Bird, a écrit un outil de publipostage utilisant les APIs Bird. Dans cet article, je reprends là où il s'est arrêté. Son outil permet la transmission programmée des tâches, mais que faire si nous voulons créer nos propres tableaux de bord et journaux d'événements ?

Peut-être que je veux créer un tableau de bord spécifique pour un groupe d'affaires ou un tableau de bord orienté client, mais sans offrir aux utilisateurs un accès complet à l'UI de Bird. Ce script ne fait qu'effleurer la surface de ce qui est possible en utilisant Python, Plotly Dash, et nos APIs. Lors de la création de tableaux de bord qui traitent des données API à volume élevé, soyez conscient que des éléments d'infrastructure comme le DNS peuvent devenir des goulets d'étranglement - nous avons rencontré des défis d'évolutivité DNS avec AWS qui ont affecté nos capacités de traitement des données. Pour les amateurs de workflows visuels, vous pouvez également explorer l'intégration de Flow Builder avec Google Cloud Functions et Vision API pour ajouter de l'automatisation alimentée par l'IA à vos pipelines de traitement des données.

Lorsque j'ai commencé ma recherche en ligne, je voulais trouver la voie de moindre résistance. J'aurais pu créer tous les tableaux de bord et l'UI moi-même en HTML et python, cependant, après quelques recherches sur Google, je suis tombé sur Plotly’s Dash, qui s'intègre facilement avec python. J'ai choisi Dash pour 2 raisons : 1) il est open source, et 2) après avoir lu la documentation, il semblait facilement personnalisable pour ce que j'essayais de faire. Dash est une bibliothèque open source idéale pour créer et déployer des applications de données avec des interfaces utilisateur personnalisées. Cela a rendu la création d'une UI extrêmement simple. La question est alors devenue, à quel point je voulais complexifier cette application ? Plus je passais de temps, plus je voulais ajouter de fonctionnalités.

Pour le projet initial, je voulais m'assurer d'avoir un tableau de bord avec des métriques personnalisables et une période sélectionnable. Initialement, j'ai commencé avec un tableau de bord où vous ne pouviez choisir qu'une seule métrique dans le menu déroulant. Puis, à mesure que je recevais des retours de collègues, j'ai affiné le tableau de bord un peu pour ajouter la multi-sélection et les titres des axes. J'ai aussi décidé d'ajouter un onglet supplémentaire pour un journal des événements. Je suis arrivé au point où j'étais satisfait de ce que j'avais comme un bon point de départ pour quiconque souhaitant créer ses propres tableaux de bord. Pour les développeurs qui veulent alimenter leurs tableaux de bord avec des données de webhooks en temps réel, consultez notre guide sur la création de consommateurs de webhook avec Azure Functions. Bien sûr, j'ai mis le projet sur Github pour que vous puissiez le cloner ou le forker.

Commencer

Pour accéder à cette app, vous devrez vous assurer que vous utilisez Python 3.10 ou une version supérieure et installer les bibliothèques suivantes :

  • requests

  • dash

  • pandas

Ensuite, entrez votre clé API dans App.py et exécutez l'app. Elle fonctionnera sur http://localhost:8050. Pour plus d'informations sur le déploiement de cela sur un serveur accessible au public (tel que AWS), consultez les ressources suivantes :

Création de la page Dashboard

Tout d'abord, initialisez le cadre de données et le tableau de bord. Sans l'initialisation du tableau de bord, aucun tableau de bord n'apparaîtra dans l'interface utilisateur.

df = pd.DataFrame({

"Count": [0,0],

"Time": [0,0]

})

fig = px.line(df,x="Time",y="Count")

Ensuite, construisez le premier onglet. Il s'agit d'une combinaison d'un rappel d'application (pour vérifier quel onglet est utilisé) ; ainsi qu'une fonction conditionnelle pour vérifier quel onglet est actuellement sélectionné. Le code ci-dessous construit uniquement le tableau de bord vierge et les éléments de l'UI (nous aborderons l'onglet des événements plus tard). Les éléments dcc sont les Dash Core Components et les HTML Components permettent facilement d'utiliser HTML dans l'interface utilisateur.

html.H2('Analytics Dashboard'),

#Menu déroulant multi-sélection

dcc.Dropdown(['Count Accepted','Count Admin Bounce','Count Block Bounce','Count Bounce','Count Clicked','Count Delayed', 'Count Delayed First','Count Delivered','Count Delivered First','Count Delivered Subsequent','Count Generation Failed', 'Count Generation Rejection','Count Hard Bounce','Count Inband Bounce','Count Initial Rendered','Count Injected', 'Count Out of Band Bounce', 'Count Policy Rejection','Count Rejected','Count Rendered','Count Sent','Count Soft Bounce', 'Count Spam Complaint','Count Targeted','Count Undetermined Bounce','Count Unique Clicked','Count Unique Confirmed Opened', 'Count Unique Initial Rendered','Count Unique Rendered','Count Unsubscribe','Total Delivery Time First','Total Delivery Time Subsequent', 'Total Message Volume'], id="y-axis", multi=True, searchable=True, placeholder="Select metrics(s)"),

#Sélecteur de date (la date maximale autorisée est fixée à la date d'aujourd'hui) dcc.DatePickerRange( id='date-picker-range', start_date=date(2022,1,1), end_date=date(2022, 2, 1), max_date_allowed=date(datetime.today().year,datetime.today().month,datetime.today().day), ),

#Objet graphique dcc.Graph( id='Emails', figure=fig )

Notez avec Dash à quel point il est simple de créer une interface utilisateur de tableau de bord avec un menu déroulant multi-sélection et réglable. Pour désactiver la multi-sélection ou la recherche, les paramètres de création d'un menu déroulant peuvent être facilement modifiés. J'ai trouvé que la partie la plus complexe de ce projet était la construction du cadre de données réel à partir des entrées, ainsi que le fonctionnement correct de HTML + CSS dans l'interface utilisateur.

L' API des Métriques à Séries Temporelles permet de récupérer 33 métriques individuelles basées sur une plage de dates/temps. Vous pouvez filtrer plus en profondeur par Domaines, Campagnes, Pools IP, Domaines d'envoi, Sous-comptes, et spécifier la Précision des données de séries temporelles. Ces filtres supplémentaires ainsi que les analyses de délivrabilité pourraient constituer une amélioration future de ce projet (la gestion des erreurs devrait être mise en œuvre pour les clients qui n'ont pas accès aux analyses de délivrabilité).

En utilisant et en appelant l' API des Métriques, je construis un tableau de bord avec les paramètres sélectionnés par l'utilisateur et la plage de temps spécifiée. Le tableau de bord initialisé est ensuite mis à jour.

#Construisez l'appel API en utilisant les paramètres fournis params = { "from" : start_date + "T00:00", "to" : end_date + "T00:00", "delimiter" : ",", "precision" : "day", "metrics" : joined_values } api_url = BASE_URL + "/metrics/deliverability/time-series" response_API = requests.get(api_url, headers = {"Authorization" : API_KEY}, params=params) response_info = json.loads(response_API.text) new_df = pd.json_normalize(response_info, record_path=['results']) value_array = joined_values.split(",") #Construisez un nouveau tableau de bord en utilisant les nouvelles métriques et dates de l'appel API mis à jour fig = px.line(new_df, x=new_df['ts'], y=value_array, labels={"value": "Count", "variable": "Metric","ts":"Date"}) fig.update_xaxes(title_text="Time") fig.update_yaxes(title_text="Count") return fig

Un exemple de multiples métriques sélectionnées et une durée élargie.


Sparkpost analytics dashboard

Note: il y a de nombreux éléments incorporés automatiquement dans le graphique Dash (survol, zoom, mise à l'échelle automatique).

Tout d'abord, initialisez le cadre de données et le tableau de bord. Sans l'initialisation du tableau de bord, aucun tableau de bord n'apparaîtra dans l'interface utilisateur.

df = pd.DataFrame({

"Count": [0,0],

"Time": [0,0]

})

fig = px.line(df,x="Time",y="Count")

Ensuite, construisez le premier onglet. Il s'agit d'une combinaison d'un rappel d'application (pour vérifier quel onglet est utilisé) ; ainsi qu'une fonction conditionnelle pour vérifier quel onglet est actuellement sélectionné. Le code ci-dessous construit uniquement le tableau de bord vierge et les éléments de l'UI (nous aborderons l'onglet des événements plus tard). Les éléments dcc sont les Dash Core Components et les HTML Components permettent facilement d'utiliser HTML dans l'interface utilisateur.

html.H2('Analytics Dashboard'),

#Menu déroulant multi-sélection

dcc.Dropdown(['Count Accepted','Count Admin Bounce','Count Block Bounce','Count Bounce','Count Clicked','Count Delayed', 'Count Delayed First','Count Delivered','Count Delivered First','Count Delivered Subsequent','Count Generation Failed', 'Count Generation Rejection','Count Hard Bounce','Count Inband Bounce','Count Initial Rendered','Count Injected', 'Count Out of Band Bounce', 'Count Policy Rejection','Count Rejected','Count Rendered','Count Sent','Count Soft Bounce', 'Count Spam Complaint','Count Targeted','Count Undetermined Bounce','Count Unique Clicked','Count Unique Confirmed Opened', 'Count Unique Initial Rendered','Count Unique Rendered','Count Unsubscribe','Total Delivery Time First','Total Delivery Time Subsequent', 'Total Message Volume'], id="y-axis", multi=True, searchable=True, placeholder="Select metrics(s)"),

#Sélecteur de date (la date maximale autorisée est fixée à la date d'aujourd'hui) dcc.DatePickerRange( id='date-picker-range', start_date=date(2022,1,1), end_date=date(2022, 2, 1), max_date_allowed=date(datetime.today().year,datetime.today().month,datetime.today().day), ),

#Objet graphique dcc.Graph( id='Emails', figure=fig )

Notez avec Dash à quel point il est simple de créer une interface utilisateur de tableau de bord avec un menu déroulant multi-sélection et réglable. Pour désactiver la multi-sélection ou la recherche, les paramètres de création d'un menu déroulant peuvent être facilement modifiés. J'ai trouvé que la partie la plus complexe de ce projet était la construction du cadre de données réel à partir des entrées, ainsi que le fonctionnement correct de HTML + CSS dans l'interface utilisateur.

L' API des Métriques à Séries Temporelles permet de récupérer 33 métriques individuelles basées sur une plage de dates/temps. Vous pouvez filtrer plus en profondeur par Domaines, Campagnes, Pools IP, Domaines d'envoi, Sous-comptes, et spécifier la Précision des données de séries temporelles. Ces filtres supplémentaires ainsi que les analyses de délivrabilité pourraient constituer une amélioration future de ce projet (la gestion des erreurs devrait être mise en œuvre pour les clients qui n'ont pas accès aux analyses de délivrabilité).

En utilisant et en appelant l' API des Métriques, je construis un tableau de bord avec les paramètres sélectionnés par l'utilisateur et la plage de temps spécifiée. Le tableau de bord initialisé est ensuite mis à jour.

#Construisez l'appel API en utilisant les paramètres fournis params = { "from" : start_date + "T00:00", "to" : end_date + "T00:00", "delimiter" : ",", "precision" : "day", "metrics" : joined_values } api_url = BASE_URL + "/metrics/deliverability/time-series" response_API = requests.get(api_url, headers = {"Authorization" : API_KEY}, params=params) response_info = json.loads(response_API.text) new_df = pd.json_normalize(response_info, record_path=['results']) value_array = joined_values.split(",") #Construisez un nouveau tableau de bord en utilisant les nouvelles métriques et dates de l'appel API mis à jour fig = px.line(new_df, x=new_df['ts'], y=value_array, labels={"value": "Count", "variable": "Metric","ts":"Date"}) fig.update_xaxes(title_text="Time") fig.update_yaxes(title_text="Count") return fig

Un exemple de multiples métriques sélectionnées et une durée élargie.


Sparkpost analytics dashboard

Note: il y a de nombreux éléments incorporés automatiquement dans le graphique Dash (survol, zoom, mise à l'échelle automatique).

Tout d'abord, initialisez le cadre de données et le tableau de bord. Sans l'initialisation du tableau de bord, aucun tableau de bord n'apparaîtra dans l'interface utilisateur.

df = pd.DataFrame({

"Count": [0,0],

"Time": [0,0]

})

fig = px.line(df,x="Time",y="Count")

Ensuite, construisez le premier onglet. Il s'agit d'une combinaison d'un rappel d'application (pour vérifier quel onglet est utilisé) ; ainsi qu'une fonction conditionnelle pour vérifier quel onglet est actuellement sélectionné. Le code ci-dessous construit uniquement le tableau de bord vierge et les éléments de l'UI (nous aborderons l'onglet des événements plus tard). Les éléments dcc sont les Dash Core Components et les HTML Components permettent facilement d'utiliser HTML dans l'interface utilisateur.

html.H2('Analytics Dashboard'),

#Menu déroulant multi-sélection

dcc.Dropdown(['Count Accepted','Count Admin Bounce','Count Block Bounce','Count Bounce','Count Clicked','Count Delayed', 'Count Delayed First','Count Delivered','Count Delivered First','Count Delivered Subsequent','Count Generation Failed', 'Count Generation Rejection','Count Hard Bounce','Count Inband Bounce','Count Initial Rendered','Count Injected', 'Count Out of Band Bounce', 'Count Policy Rejection','Count Rejected','Count Rendered','Count Sent','Count Soft Bounce', 'Count Spam Complaint','Count Targeted','Count Undetermined Bounce','Count Unique Clicked','Count Unique Confirmed Opened', 'Count Unique Initial Rendered','Count Unique Rendered','Count Unsubscribe','Total Delivery Time First','Total Delivery Time Subsequent', 'Total Message Volume'], id="y-axis", multi=True, searchable=True, placeholder="Select metrics(s)"),

#Sélecteur de date (la date maximale autorisée est fixée à la date d'aujourd'hui) dcc.DatePickerRange( id='date-picker-range', start_date=date(2022,1,1), end_date=date(2022, 2, 1), max_date_allowed=date(datetime.today().year,datetime.today().month,datetime.today().day), ),

#Objet graphique dcc.Graph( id='Emails', figure=fig )

Notez avec Dash à quel point il est simple de créer une interface utilisateur de tableau de bord avec un menu déroulant multi-sélection et réglable. Pour désactiver la multi-sélection ou la recherche, les paramètres de création d'un menu déroulant peuvent être facilement modifiés. J'ai trouvé que la partie la plus complexe de ce projet était la construction du cadre de données réel à partir des entrées, ainsi que le fonctionnement correct de HTML + CSS dans l'interface utilisateur.

L' API des Métriques à Séries Temporelles permet de récupérer 33 métriques individuelles basées sur une plage de dates/temps. Vous pouvez filtrer plus en profondeur par Domaines, Campagnes, Pools IP, Domaines d'envoi, Sous-comptes, et spécifier la Précision des données de séries temporelles. Ces filtres supplémentaires ainsi que les analyses de délivrabilité pourraient constituer une amélioration future de ce projet (la gestion des erreurs devrait être mise en œuvre pour les clients qui n'ont pas accès aux analyses de délivrabilité).

En utilisant et en appelant l' API des Métriques, je construis un tableau de bord avec les paramètres sélectionnés par l'utilisateur et la plage de temps spécifiée. Le tableau de bord initialisé est ensuite mis à jour.

#Construisez l'appel API en utilisant les paramètres fournis params = { "from" : start_date + "T00:00", "to" : end_date + "T00:00", "delimiter" : ",", "precision" : "day", "metrics" : joined_values } api_url = BASE_URL + "/metrics/deliverability/time-series" response_API = requests.get(api_url, headers = {"Authorization" : API_KEY}, params=params) response_info = json.loads(response_API.text) new_df = pd.json_normalize(response_info, record_path=['results']) value_array = joined_values.split(",") #Construisez un nouveau tableau de bord en utilisant les nouvelles métriques et dates de l'appel API mis à jour fig = px.line(new_df, x=new_df['ts'], y=value_array, labels={"value": "Count", "variable": "Metric","ts":"Date"}) fig.update_xaxes(title_text="Time") fig.update_yaxes(title_text="Count") return fig

Un exemple de multiples métriques sélectionnées et une durée élargie.


Sparkpost analytics dashboard

Note: il y a de nombreux éléments incorporés automatiquement dans le graphique Dash (survol, zoom, mise à l'échelle automatique).

Création de la page Event Details

La page des détails de l'événement était un peu plus difficile car je ne savais pas quelle était la meilleure façon de présenter tous les métriques des événements de manière facile à lire. J'ai envisagé d'ajouter des paramètres de filtrage à cette page, cependant, j'ai décidé que cela ajouterait un temps considérable à ce projet, car le tableau devrait alors être dynamique (en plus d'ajouter les paramètres, les callbacks, etc.). J'ai opté pour montrer tous les événements et placer le timestamp en premier (car sans mettre le timestamp en premier, le graphique n'était pas facile à lire). Au départ, j'ai constaté qu'avec juste le HTML brut, le tableau était incroyablement difficile pour les yeux. Il n'y avait pas de bordures et pas de différences de couleur pour l'en-tête par rapport aux lignes. Pour rendre le tableau plus facile à lire, j'ai pu utiliser CSS avec Dash.

L'idée pour les détails de l'événement est presque la même que le tableau de bord, sauf que cette fois, j'appelle l'Events API et je fais venir tous les événements. Notez que les détails de l'événement ne montrent que les 10 événements les plus récents (en utilisant le paramètre max_rows et le filtrage API). Cela peut être augmenté, cependant, j'ai opté pour montrer les 10 événements les plus récents car plus d'événements sont affichés, plus l'appel API prend de temps. Une amélioration significative qui pourrait être faite serait la possibilité de paginer et d'inclure une page suivante / page précédente dans l'interface utilisateur.

Pour construire l'onglet (page) des événements, tout d'abord, j'appelle l'Events API et je parse la réponse JSON en un cadre de données. Ensuite, je trie et réorganise le cadre de données pour mettre le timestamp comme première colonne. Enfin, je construis le tableau HTML en itérant à travers le cadre de données.

#Construction et appel de l'Events API params = { "events" : "delivery,injection,bounce,delay,policy_rejection,out_of_band,open,click,generation_failure,generation_rejection,spam_complaint,list_unsubscribe,link_unsubscribe", "delimiter" : ",", "page" : "1", "per_page" : "10" } api_url = BASE_URL + "/events/message" response_API = requests.get(api_url, headers = {"Authorization" : API_KEY}, params=params) response_info = json.loads(response_API.text) new_df = pd.json_normalize(response_info, record_path=['results']) max_rows=10 #Nombre maximum de résultats affichés dans le tableau des événements #Placer le timestamp en tant que première colonne du tableau new_df = new_df.reindex(sorted(new_df.columns), axis=1) cols = ['timestamp'] new_df = new_df[cols + [c for c in new_df.columns if c not in cols]] #Afficher le nouveau HTML avec le tableau des événements (notez que ce tableau fait également référence à table.css) return html.Div([ html.H2("Event Details"), html.Table([ html.Thead( html.Tr([html.Th(col) for col in new_df.columns],className="table_css") ), html.Tbody([ html.Tr([ html.Td(new_df.iloc[i][col],className="table_css") for col in new_df.columns ]) for i in range(min(len(new_df), max_rows)) ]) ]) ])

Qui ressemble à ceci dans l'interface utilisateur.

Sparkpost event details

Étapes suivantes

Pour quelqu'un cherchant à créer leur propre tableau de bord ou journal d'événements, c'est un bon début. Avec la personnalisation ici, le ciel est la limite.

Comme discuté ci-dessus, certaines améliorations futures qui pourraient être apportées sont :

  • Ajout d'analyses de délivrabilité au tableau de bord

  • Ajout de plus de filtres au tableau de bord

  • Options de mise en cache possibles pour que l'API ne soit pas appelée à chaque fois pour afficher les pages

  • Améliorations de l'UI

  • Ajout de filtrage et de pagination à la page des détails de l'événement

Je serais intéressé d'entendre vos retours ou suggestions pour étendre ce projet.

~ Zach Samuels, Bird Senior Solutions Engineer

Connectons-vous avec un expert Bird.
Découvrez toute la puissance du Bird en 30 minutes.

En soumettant, vous acceptez que Bird puisse vous contacter au sujet de nos produits et services.

Vous pouvez vous désabonner à tout moment. Consultez la Déclaration de confidentialité de Bird pour plus de détails sur le traitement des données.

Company

Newsletter

Restez à jour avec Bird grâce aux mises à jour hebdomadaires dans votre boîte de réception.

Connectons-vous avec un expert Bird.
Découvrez toute la puissance du Bird en 30 minutes.

En soumettant, vous acceptez que Bird puisse vous contacter au sujet de nos produits et services.

Vous pouvez vous désabonner à tout moment. Consultez la Déclaration de confidentialité de Bird pour plus de détails sur le traitement des données.

Company

Newsletter

Restez à jour avec Bird grâce aux mises à jour hebdomadaires dans votre boîte de réception.

Connectons-vous avec un expert Bird.
Découvrez toute la puissance du Bird en 30 minutes.

En soumettant, vous acceptez que Bird puisse vous contacter au sujet de nos produits et services.

Vous pouvez vous désabonner à tout moment. Consultez la Déclaration de confidentialité de Bird pour plus de détails sur le traitement des données.

R

Atteindre

G

Grow

M

Manage

A

Automate

Company

Newsletter

Restez à jour avec Bird grâce aux mises à jour hebdomadaires dans votre boîte de réception.