BigQuery: Zeile einfügen

Verwenden Sie BigQuery: Zeile einfügen, um eine Zeile aus einem Journey-Schritt über die Streaming-Insert-API in eine BigQuery-Tabelle zu streamen. Ähnlich wie bei Google Sheets: Zeile hinzufügen, authentifiziert sich dieser Knoten über das Google-Konto, das einmal für das gesamte Konto verbunden wurde. Es gibt kein Token-Feld am Knoten selbst.

Typische Anwendungsfälle:

• Eine Reporting-Tabelle füllen: Fügen Sie pro erreichtem Journey-Schritt eine Zeile für ein Dashboard oder eine nachgelagerte geplante Abfrage ein.
• Ereignisse protokollieren, während sie stattfinden: Streamen Sie rohe Journey-Daten in BigQuery, anstatt auf einen Batch-Export zu warten.
• Mit vorhandenen Daten verknüpfen: Fügen Sie einen Geräte- oder Tag-Wert ein, mit dem Ihre BigQuery-Tabellen Ihre eigenen Datensätze verknüpfen können.

Bevor Sie beginnen

Verbinden Sie ein Google-Konto unter Einstellungen > Integrationen von Drittanbietern > Google. Dies ist dieselbe Verbindung, die auch Google Sheets: Zeile hinzufügen verwendet. Nachdem Sie Google verbunden haben, installieren Sie die Integration, damit der Knoten im Journey Builder erscheint.

Dies ist nicht die Google BigQuery-Karte auf dieser Seite. Das ist die BigQuery-Integration: Sie streamt jedes Nachrichtenereignis einer Anwendung in ein festes Schema über einen Dienstkontoschlüssel. Dieser Knoten schreibt eine von Ihnen definierte Zeile in dem Schritt, in dem Sie ihn platzieren, und benötigt keinen eigenen Schlüssel.

Vorsicht

Wenn Sie Google verbunden haben, bevor die BigQuery-Unterstützung hinzugefügt wurde, verbinden Sie es einmal neu. Eine Verbindung behält die Berechtigungen, die ihr erteilt wurden, sodass eine ältere Verbindung in Sheets, aber nicht in BigQuery schreiben kann und der Knoten mit einem 403-Fehler fehlschlägt.

Zwei Dinge müssen auch auf der Google Cloud-Seite vorhanden sein, sonst schlägt die Anfrage fehl:

• Das Dataset und die Tabelle müssen bereits existieren. Dieser Knoten schreibt Zeilen. Er erstellt niemals eine Tabelle.
• Das verbundene Google-Konto benötigt die Rolle BigQuery Data Editor (oder eine andere Rolle, die bigquery.tables.updateData gewährt) für dieses Dataset.

Den Knoten konfigurieren

1. Ziehen Sie BigQuery: Zeile einfügen aus dem Abschnitt Integrationen im linken Bereich auf die Arbeitsfläche.
2. Doppelklicken Sie auf den Knoten und geben Sie einen Schrittnamen ein.
3. Geben Sie unter Projekt-ID die Google Cloud-Projekt-ID ein. Verwenden Sie die ID, nicht den Anzeigenamen, zum Beispiel my-analytics-prod.

4. Geben Sie unter Dataset den Dataset-Namen ein.

5. Geben Sie unter Tabelle den Tabellennamen ein.

6. Fügen Sie unter Spalten eine Zeile pro zu schreibender BigQuery-Spalte hinzu. Geben Sie den Spaltennamen und den Wert ein. Namen müssen nicht leer und eindeutig sein. Jede von Ihnen aufgeführte Spalte muss im Schema der Tabelle vorhanden sein. Ein Wert kann fester Text oder ein Traveler-Makro wie {{tag:Name}} sein, dieselben Makros wie in einem Webhook-Body. Oder klicken Sie auf Dynamischen Wert einfügen, um ein Attribut auszuwählen, das ein früherer Schritt in dieser Journey erzeugt hat, zum Beispiel eine LLM-Antwort oder einen zugeordneten Webhook-Wert.

Beispiel

Wenn Dataset auf marketing und Tabelle auf journey_events gesetzt ist, schreibt das Setzen von Spalten auf device_id mit der Geräte-ID des Travelers ({{device:hwid}}) eine Zeile in die device_id-Spalte dieser Tabelle.

7. Klicken Sie auf Speichern.

Antwort

Der Traveler fährt mit dem nächsten Schritt fort, den Sie auf der Arbeitsfläche verbinden.

Attribute nach Ausführung des Schritts

Dieser Knoten gibt bei Erfolg kein Attribut zurück. Wenn BigQuery eine Zeile ablehnt, wird der Fehler stattdessen in bigquery_insert_error geschrieben. Siehe Fehler und unerwartete Antworten.

Fehler und unerwartete Antworten

Öffnen Sie das Anrufprotokoll im Menü des Knotens und überprüfen Sie die Antwort:

• 401 — die Google-Verbindung fehlt oder ist abgelaufen. Verbinden Sie sie unter Einstellungen > Integrationen von Drittanbietern neu.
• 403 mit accessDenied: Streaming insert is not allowed in the free tier — dem Projekt ist kein Rechnungskonto zugeordnet. Streaming-Inserts, die dieser Knoten verwendet, sind nicht Teil der BigQuery-Sandbox. Aktivieren Sie die Abrechnung für das Projekt, und dieselbe Anfrage wird erfolgreich sein.
• 403 mit accessDenied oder insufficientPermissions — die Verbindung wurde hergestellt, bevor die BigQuery-Unterstützung hinzugefügt wurde (verbinden Sie sie neu), oder das Google-Konto hat keinen Schreibzugriff auf das Dataset.
• 403 mit quotaExceeded oder rateLimitExceeded — das Streaming-Insert-Kontingent des Projekts ist aufgebraucht. Es muss nichts neu verbunden werden. Die Journey muss weniger senden, oder das Kontingent muss in Google Cloud erhöht werden.
• 404 — der Projekt-, Dataset- oder Tabellenname stimmt mit nichts überein.

Vorsicht

Eine von BigQuery abgelehnte Zeile (eine unbekannte Spalte oder ein Wert, der nicht zum Typ der Spalte passt) wird als 200 mit einem insertErrors-Body zurückgegeben, nicht als Fehlerstatus. Der Traveler fährt fort, als ob der Schreibvorgang erfolgreich war. Die erste solche Nachricht wird in das Traveler-Attribut bigquery_insert_error geschrieben. Eine Bedingungsaufteilung kann nicht direkt darauf verzweigen, speichern Sie es also zuerst mit Benutzerprofil aktualisieren in einem Tag und verzweigen Sie dann mit einer Bedingungsaufteilung auf diesen Tag. Der vollständige Body befindet sich im Anrufprotokoll.

Eine fehlgeschlagene Anfrage entfernt den Traveler aus der Journey. Siehe Fehler und fehlgeschlagene Anfragen.

Beispielszenario: Eine BigQuery-Reporting-Tabelle füllen

Ein Team möchte die Journey-Aktivität im selben BigQuery-Dataset haben, das ihre geplanten Berichte bereits abfragen.

1. Fügen Sie BigQuery: Zeile einfügen direkt nach dem Schritt hinzu, den Sie protokollieren möchten. Setzen Sie Dataset auf marketing und Tabelle auf journey_events. Setzen Sie unter Spalten device_id auf {{device:hwid}}.
2. Klicken Sie auf Speichern.

Sobald dies ausgeführt wird, landet die Zeile in derselben Tabelle, aus der die geplante Abfrage liest, sodass der nächste Berichtslauf sie bereits enthält.