BigQuery : insérer une ligne

Utilisez BigQuery : insérer une ligne pour diffuser une ligne dans une table BigQuery à partir d’une étape de parcours, via l’API d’insertion en streaming. Comme pour Google Sheets : ajouter une ligne, cet élément s’authentifie via le compte Google connecté une seule fois pour l’ensemble du compte. Il n’y a pas de champ de jeton sur l’élément lui-même.

Utilisations typiques :

• Alimenter une table de reporting : insérez une ligne pour chaque étape de parcours atteinte, pour un tableau de bord ou une requête planifiée en aval.
• Enregistrer les événements au fur et à mesure qu’ils se produisent : diffusez les données brutes du parcours dans BigQuery au lieu d’attendre une exportation par lots.
• Joindre avec des données existantes : insérez une valeur d’appareil ou de Tag que vos tables BigQuery peuvent joindre à vos propres ensembles de données.

Avant de commencer

Connectez un compte Google sous Paramètres > Intégrations tierces > Google. C’est la même connexion que celle utilisée par Google Sheets : ajouter une ligne. Après avoir connecté Google, installez l’intégration pour que l’élément apparaisse dans le constructeur de parcours.

Il ne s’agit pas de la carte Google BigQuery sur cette page. Celle-ci correspond à l’intégration BigQuery : elle diffuse chaque événement de message d’une application dans un schéma fixe sur une clé de compte de service. Cet élément écrit une ligne que vous définissez, à l’étape où vous le placez, et ne prend aucune clé propre.

Attention

Si vous avez connecté Google avant l’ajout du support BigQuery, reconnectez-le une fois. Une connexion conserve les autorisations qui lui ont été accordées, donc une ancienne connexion peut écrire dans Sheets mais pas dans BigQuery, et l’élément échoue avec une erreur 403.

Deux choses doivent également être en place du côté de Google Cloud, sinon la requête échoue :

• L’ensemble de données et la table doivent déjà exister. Cet élément écrit des lignes. Il ne crée jamais de table.
• Le compte Google connecté a besoin du rôle Éditeur de données BigQuery (ou de tout rôle accordant bigquery.tables.updateData) sur cet ensemble de données.

Configurer l’élément

1. Faites glisser BigQuery : insérer une ligne depuis la section Intégrations du panneau de gauche sur le canevas.
2. Double-cliquez sur l’élément et saisissez un Nom de l’étape.
3. Dans ID du projet, saisissez l’ID du projet Google Cloud. Utilisez l’ID, pas le nom d’affichage, par exemple my-analytics-prod.

4. Dans Ensemble de données, saisissez le nom de l’ensemble de données.

5. Dans Table, saisissez le nom de la table.

6. Dans Colonnes, ajoutez une ligne par colonne BigQuery à écrire. Saisissez le nom de la colonne et la valeur. Les noms doivent être non vides et uniques. Chaque colonne que vous listez doit exister dans le schéma de la table. Une valeur peut être un texte fixe ou une macro de voyageur telle que {{tag:Name}}, les mêmes macros que dans un corps de Webhook. Ou cliquez sur Insérer une valeur dynamique pour choisir un attribut produit par une étape antérieure de ce parcours, par exemple une réponse LLM ou une valeur de Webhook mappée.

Exemple

Avec Ensemble de données défini sur marketing et Table sur journey_events, définir Colonnes sur device_id avec l’ID de l’appareil du voyageur ({{device:hwid}}) écrit une ligne dans la colonne device_id de cette table.

7. Cliquez sur Enregistrer.

Réponse

Le voyageur continue vers l’étape suivante que vous connectez sur le canevas.

Attributs après l’exécution de l’étape

Cet élément ne renvoie pas d’attribut en cas de succès. Si BigQuery rejette une ligne, l’erreur est écrite dans bigquery_insert_error à la place. Voir Échecs et réponses inattendues.

Échecs et réponses inattendues

Ouvrez le Journal des appels dans le tiroir de l’élément et vérifiez la réponse :

• 401 — la connexion Google est manquante ou a expiré. Reconnectez-la sous Paramètres > Intégrations tierces.
• 403 avec accessDenied: Streaming insert is not allowed in the free tier — le projet n’a pas de compte de facturation associé. Les insertions en streaming, que cet élément utilise, ne font pas partie du bac à sable BigQuery. Activez la facturation sur le projet et la même requête passera.
• 403 avec accessDenied ou insufficientPermissions — la connexion a été accordée avant l’ajout du support BigQuery (reconnectez-la), ou le compte Google n’a pas d’accès en écriture à l’ensemble de données.
• 403 avec quotaExceeded ou rateLimitExceeded — le quota d’insertion en streaming du projet est épuisé. Rien à reconnecter. Le parcours doit envoyer moins de données, ou le quota doit être augmenté dans Google Cloud.
• 404 — le nom du projet, de l’ensemble de données ou de la table ne correspond à rien.

Attention

Une ligne que BigQuery rejette (une colonne inconnue, ou une valeur qui ne correspond pas au type de la colonne) est retournée comme un 200 avec un corps insertErrors, et non comme un statut d’erreur. Le voyageur continue comme si l’écriture avait réussi. Le premier message de ce type est écrit dans l’attribut du voyageur bigquery_insert_error. La division par condition ne peut pas se baser directement dessus, donc enregistrez-le d’abord dans un Tag avec Mettre à jour le profil utilisateur, puis effectuez une division sur ce Tag avec une Division par condition. Le corps complet se trouve dans le Journal des appels.

Une requête échouée retire le voyageur du parcours. Voir Erreurs et requêtes échouées.

Scénario d’exemple : Alimenter une table de reporting BigQuery

Une équipe souhaite que l’activité du parcours soit dans le même ensemble de données BigQuery que celui que leurs rapports planifiés interrogent déjà.

1. Ajoutez BigQuery : insérer une ligne juste après l’étape que vous souhaitez enregistrer. Définissez Ensemble de données sur marketing et Table sur journey_events. Dans Colonnes, définissez device_id sur {{device:hwid}}.
2. Cliquez sur Enregistrer.

Une fois cette opération effectuée, la ligne atterrit dans la même table que celle lue par la requête planifiée, de sorte que la prochaine exécution du rapport l’inclura déjà.