Google BigQuery-Integration

Hilfe von Entwicklern benötigt

Sie benötigen Hilfe von Ihrem Entwicklungsteam oder Google Cloud-Administrator, um die Integration einzurichten. Bitte teilen Sie diese Anleitung mit ihnen.

Die Google BigQuery-Integration streamt ausgewählte Pushwoosh-Nachrichtenereignisse in Ihr BigQuery-Dataset. Nutzen Sie es, um Push-, E-Mail- und SMS-Lebenszyklusereignisse in BigQuery zu analysieren, benutzerdefinierte Berichte zu erstellen oder die Daten mit Ihren nachgelagerten Analyse-Workflows zu verbinden.

Integrationsübersicht

Voraussetzungen

Bereiten Sie Folgendes vor, bevor Sie die Einrichtung der Integration öffnen.

1. Verwenden Sie ein Google Cloud-Projekt, bei dem die Abrechnung aktiviert ist. Free-Trial-Guthaben werden unterstützt. Die BigQuery Sandbox ist nicht ausreichend, da die Storage Write API eine Abrechnung erfordert.

2. Stellen Sie sicher, dass Sie ein kostenpflichtiges Pushwoosh-Konto haben.

Preise

Sie bezahlen die Nutzung von BigQuery direkt an Google. Pushwoosh berechnet keine Gebühren für die Integration selbst.

Aktuelle Tarife, kostenlose Stufen und regionale Details finden Sie unter BigQuery-Preise.

Die Kosten können umfassen:

• Datenerfassung: Pushwoosh streamt Ereignisse mit der BigQuery Storage Write API.
• Speicher: BigQuery speichert die in Ihre Zieltabelle geschriebenen Zeilen.
• Abfragen: BigQuery berechnet die Gebühren für Abfragen basierend auf dem von Ihnen gewählten Preismodell.

Integrationstyp

Quelle: Daten werden von Pushwoosh an Ihr BigQuery-Dataset gesendet.

Unterstützte Plattformen

Pushwoosh streamt Ereignisse von den Plattformen iOS, Android, Huawei, Chrome, Safari, Firefox und Web.

Synchronisierte Entitäten

Ausgewählte Push-, E-Mail- und SMS-Lebenszyklusereignisse werden zu BigQuery gestreamt. Pushwoosh schreibt eine Zeile pro ausgewähltem Ereignis in die Zieltabelle.

Anwendungsfälle

• Nachrichtenanalyse in nahezu Echtzeit: Analysieren Sie Push-, E-Mail- und SMS-Lebenszyklusereignisse in BigQuery kurz nachdem sie in Pushwoosh verarbeitet wurden.
• Benutzerdefinierte Berichte: Erstellen Sie BigQuery-Berichte für ausgewählte Ereignisarten, Anwendungen, Kampagnen und Nachrichtenkennungen.
• Nachgelagerte Daten-Workflows: Verbinden Sie Pushwoosh-Ereignisdaten mit Ihren Analyse-, Berichts- oder Datenverarbeitungs-Workflows.

Wie die Integration funktioniert

Nachdem Sie die Konfiguration gespeichert haben, beginnt Pushwoosh damit, ausgewählte Nachrichtenereignisse in nahezu Echtzeit in Ihre BigQuery-Tabelle zu streamen. Für jedes Nachrichtenereignis, das durch Pushwoosh fließt, prüft das System, ob die Ereignisart in Ihrer Konfiguration ausgewählt ist.

Wenn dies der Fall ist, fügt Pushwoosh eine neue Zeile zu Ihrer Zieltabelle hinzu. Wenn die Tabelle noch nicht existiert, erstellt Pushwoosh sie automatisch mit dem unten beschriebenen Schema. Ereignisse erscheinen in der Regel innerhalb von 30 Sekunden nach der Verarbeitung in Pushwoosh in BigQuery.

Einrichtung der Integration in Google Cloud

Wählen Sie ein Google Cloud-Projekt

Melden Sie sich in der Google Cloud Console an und wählen oder erstellen Sie dann das Projekt, dem das BigQuery-Dataset gehören wird.

Tipp

Notieren Sie sich die Projekt-ID. Verwenden Sie die kurze Kennung, zum Beispiel my-company-12345, nicht den für Menschen lesbaren Projektnamen.

Aktivieren Sie die erforderlichen APIs

Gehen Sie in der Google Cloud Console zu APIs & Dienste → Bibliothek und aktivieren Sie diese APIs:

• BigQuery API
• BigQuery Storage API

Pushwoosh verwendet diese APIs, um die Zieltabelle zu erstellen und Ereignisse in BigQuery zu streamen.

Erstellen Sie ein Dienstkonto

Pushwoosh verwendet das Dienstkonto, um Ereignisse in Ihr BigQuery-Dataset zu schreiben.

1. Gehen Sie zu IAM & Verwaltung → Dienstkonten.

2. Klicken Sie auf Dienstkonto erstellen.

3. Geben Sie unter Name des Dienstkontos einen Namen ein, zum Beispiel pushwoosh-bigquery.

   Google Cloud generiert automatisch die Dienstkonto-ID aus dem Namen.

   

4. Klicken Sie auf Erstellen und fortfahren.

IAM-Rollen zuweisen

1. Weisen Sie dem Dienstkonto diese IAM-Rollen zu:

   • BigQuery-Daten-Editor: erlaubt Pushwoosh, die Tabelle zu erstellen und Zeilen anzuhängen.
   • BigQuery-Nutzer: erlaubt Pushwoosh, die Storage Write API zu verwenden.
   

Hinweis

Sie können die Rollen auf Projektebene oder auf Dataset-Ebene zuweisen. Der Zugriff auf Projektebene ist am einfachsten einzurichten. Der Zugriff auf Dataset-Ebene ist restriktiver und wird für die Produktion empfohlen.

2. Klicken Sie auf Weiter.

3. Klicken Sie auf Fertig.

Erstellen Sie einen JSON-Schlüssel

Pushwoosh verwendet den JSON-Schlüssel, um sich als Dienstkonto zu authentifizieren.

1. Öffnen Sie das von Ihnen erstellte Dienstkonto.

2. Gehen Sie zu Schlüssel → Schlüssel hinzufügen → Neuen Schlüssel erstellen.

3. Wählen Sie JSON.

Google Cloud lädt die JSON-Schlüsseldatei auf Ihren Computer herunter.

Vorsicht

Bewahren Sie die JSON-Schlüsseldatei sicher auf. Jeder, der diese Datei besitzt, kann in Ihr BigQuery-Projekt schreiben. Committen Sie sie nicht in Git und teilen Sie sie nicht über Chats. Pushwoosh speichert den Schlüssel im Ruhezustand verschlüsselt und zeigt ihn nach dem Hochladen nicht in der Benutzeroberfläche an.

Erstellen Sie ein Dataset

Das Dataset ist der Ort, an dem Pushwoosh die gestreamte Ereignistabelle speichert.

1. Öffnen Sie in der Google Cloud Console BigQuery.

2. Wählen Sie im Explorer das Projekt aus, das Sie für die Integration vorbereitet haben.

3. Klicken Sie auf Dataset erstellen.

4. Geben Sie unter Dataset-ID eine Dataset-ID ein, zum Beispiel pushwoosh_data.

5. Wählen Sie unter Datenspeicherort die Region des Datasets aus.

6. Klicken Sie auf Dataset erstellen.

Konfigurieren Sie die Integration in Pushwoosh

1. Gehen Sie in Ihrem Pushwoosh-Konto zu Einstellungen → Drittanbieter-Integrationen für die Anwendung, die Sie verbinden möchten.

2. Suchen Sie Google BigQuery in der Liste der verfügbaren Dienste und klicken Sie auf Konfigurieren.

3. Füllen Sie die Konfigurationsfelder aus.

• GCP-Projekt-ID: Geben Sie die Projekt-ID aus Google Cloud ein, zum Beispiel my-company-12345.
• Dienstkonto-JSON: Fügen Sie den gesamten Inhalt der JSON-Schlüsseldatei ein, die Sie aus Google Cloud heruntergeladen haben.
• Dataset-ID: Sobald die GCP-Projekt-ID und das Dienstkonto-JSON ausgefüllt sind, ruft Pushwoosh die Datasets ab, auf die Ihr Dienstkonto zugreifen kann. Wählen Sie das Zieldataset aus. Wenn das Dropdown-Menü leer ist, überprüfen Sie, ob das Dienstkonto Zugriff hat und ob das Dataset in dem von Ihnen angegebenen Projekt vorhanden ist.
• Dataset-Region: Wählen Sie die Region Ihres BigQuery-Datasets.
• Tabellenname: Lassen Sie das Feld leer, um die Standardtabelle pushwoosh_events zu verwenden. Pushwoosh erstellt die Tabelle mit dem unten beschriebenen Schema.
• Ereignisse: Wählen Sie die Ereignisse aus, die Sie streamen möchten. Sie können diese Liste später ändern.
• Ereignisse zu BigQuery streamen: Aktivieren Sie diesen Schalter. Deaktivieren Sie ihn, um das Streaming zu pausieren, ohne die Konfiguration zu löschen.

4. Klicken Sie auf Verbindung testen.

Pushwoosh validiert die Anmeldeinformationen bei BigQuery, ohne Daten zu schreiben.

Möglicherweise sehen Sie einen dieser Verbindungsstatus:

• Verbindung erfolgreich: Die Anmeldeinformationen funktionieren und das Dienstkonto kann auf das Dataset zugreifen.
• auth_failed: Der JSON-Schlüssel ist ungültig oder widerrufen.
• dataset_not_found: Die Dataset-ID ist falsch oder das Dienstkonto kann nicht darauf zugreifen.
• missing_permission: Dem Dienstkonto fehlt eine der erforderlichen Rollen.

5. Klicken Sie auf Anwenden.

Pushwoosh speichert die Konfiguration und beginnt innerhalb von etwa 30 Sekunden mit deren Verwendung. Danach werden ausgewählte Ereignisse zu BigQuery gestreamt.

Überprüfen Sie die Integration

1. Senden Sie einen Test-Push oder lösen Sie eine andere Nachricht aus, die eine der von Ihnen ausgewählten Ereignisarten erzeugt.

2. Warten Sie etwa 30 Sekunden.

3. Öffnen Sie BigQuery Studio.

4. Gehen Sie zu Ihrem Projekt und öffnen Sie dann das Dataset und die von Ihnen konfigurierte Zieltabelle. Wenn Sie Tabellenname leer gelassen haben, öffnen Sie pushwoosh_events.

5. Klicken Sie auf Vorschau.

Sie sollten die Ereigniszeile in der Tabelle sehen.

Tabellenschema

Pushwoosh schreibt jedes ausgewählte Ereignis als separate Zeile in die Zieltabelle. Um Abfragen schneller und einfacher filterbar zu machen, ist die Tabelle nach Tag unter Verwendung von timestamp partitioniert und nach app_id und event_kind geclustert.

Feldname	Typ	Beschreibung
event_kind	STRING	Art des Pushwoosh-Ereignisses, zum Beispiel Push Sent oder Email Opened.
message_id	STRING	Pushwoosh-Nachrichtencode, wie die Kampagnen- oder Nachrichtenkennung.
device_id	STRING	Pushwoosh-Hardware-ID des Geräts, das das Ereignis ausgelöst hat.
user_id	STRING	Ihre externe Benutzer-ID, falls bekannt. Leer für anonyme Geräte.
timestamp	TIMESTAMP	Ereigniszeit in UTC.
app_id	STRING	Pushwoosh-Anwendungscode.
platform	STRING	Quellplattform, zum Beispiel ios, android oder web.
properties	JSON	Zusätzliche Ereignisfelder. Verwenden Sie JSON_VALUE, um Felder abzufragen, wie unten gezeigt.

Eigenschaften abfragen

Die Spalte properties speichert zusätzliche Ereignisfelder als JSON. Verwenden Sie JSON_VALUE, um einzelne Felder in Ihren Abfragen zu extrahieren.

Um beispielsweise zu sehen, welche Kampagnen in den letzten 7 Tagen die meisten Öffnungen erzielt haben, klicken Sie auf +, um eine neue Abfrage zu erstellen, fügen Sie den folgenden SQL-Code ein und klicken Sie auf Ausführen.

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

Um die Ereigniszahlen der letzten Stunde zu überprüfen, führen Sie diese Abfrage aus:

SELECT
  event_kind,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

Aktualisieren der Integration

Rotieren des Dienstkontoschlüssels

1. Gehen Sie in der Google Cloud Console zu IAM & Verwaltung → Dienstkonten.

2. Öffnen Sie Ihr Dienstkonto.

3. Gehen Sie zu Schlüssel und erstellen Sie einen neuen JSON-Schlüssel.

4. Lassen Sie den alten Schlüssel aktiv, bis Sie bestätigen, dass der neue Schlüssel funktioniert.

5. Öffnen Sie in Pushwoosh das Konfigurationsmodal Google BigQuery.

6. Fügen Sie das neue JSON in Dienstkonto-JSON ein.

7. Klicken Sie auf Anwenden.

Pushwoosh validiert den neuen Schlüssel, ersetzt die gespeicherten Anmeldeinformationen und beginnt nach dem nächsten Neuladen der Konfiguration, was etwa 30 Sekunden dauert, mit dessen Verwendung.

Nachdem Sie bestätigt haben, dass die Ereignisse weiterhin fließen, löschen Sie den alten Schlüssel in der Google Cloud Console.

Ändern des Zieldatasets oder der Zieltabelle

1. Gehen Sie in Pushwoosh zu Einstellungen → Drittanbieter-Integrationen.

2. Öffnen Sie die Einstellungen für Google BigQuery.

3. Wählen Sie ein anderes Dataset aus oder geben Sie einen neuen Tabellennamen ein.

4. Klicken Sie auf Anwenden.

Pushwoosh öffnet den Stream mit dem neuen Ziel innerhalb von etwa 30 Sekunden erneut. Bereits geschriebene Zeilen verbleiben in der alten Tabelle. Pushwoosh füllt keine historischen Daten nach.

Um den gespeicherten Dienstkontoschlüssel bei der Aktualisierung anderer Einstellungen unverändert zu lassen, lassen Sie Dienstkonto-JSON leer, bevor Sie auf Anwenden klicken.

Fehlerbehebung

Problem	Was zu überprüfen ist
Verbindungstest schlägt mit auth_failed fehl	Das Dienstkonto-JSON ist fehlerhaft oder der Schlüssel wurde in Google Cloud widerrufen. Erstellen Sie einen neuen Schlüssel und fügen Sie die vollständige JSON-Datei erneut ein. Die Datei beginnt mit {, endet mit } und enthält einen private_key-Block.
Verbindungstest schlägt mit dataset_not_found fehl	Die Dataset-ID ist falsch geschrieben oder existiert nicht in dem von Ihnen angegebenen Projekt. Bei Dataset-IDs wird zwischen Groß- und Kleinschreibung unterschieden. Wählen Sie das Dataset aus dem Dropdown-Menü, um Tippfehler zu vermeiden.
Verbindungstest schlägt mit missing_permission fehl	Dem Dienstkonto fehlt BigQuery-Daten-Editor oder BigQuery-Nutzer. Weisen Sie beide Rollen auf Projektebene zu oder gewähren Sie sie auf Dataset-Ebene für einen restriktiveren Zugriff.
Verbindungstest erfolgreich, aber es erscheinen keine Zeilen in BigQuery	Warten Sie mindestens 30 Sekunden. Überprüfen Sie, ob die von Ihnen gesendete Ereignisart unter Ereignisse ausgewählt ist. Wenn beispielsweise nur Push Opened ausgewählt ist und niemand den Push öffnet, erscheinen keine Zeilen.
Konfiguration sieht korrekt aus, aber das Modal zeigt leere Felder an	Laden Sie die Seite neu. Die Konfiguration wird bei jedem Öffnen des Modals abgerufen und vom zugrunde liegenden Dienst für 30 Sekunden zwischengespeichert. Wenn Sie die Einstellungen gerade gespeichert haben, warten Sie einen Moment und öffnen Sie das Modal erneut.

Hinweis

Pushwoosh zeichnet Push Sent, Email Sent und SMS Sent unabhängig vom Zustellstatus auf, damit die BigQuery-Aggregate mit den kanonischen Pushwoosh-Statistiken übereinstimmen. Für Delivered, Opened, Bounced und Unsubscribed zeichnet Pushwoosh nur erfolgreiche Ereignisse auf.

FAQ

Kann ich ein kostenloses Google Cloud-Konto verwenden?

Ja, solange die Abrechnung für das Projekt aktiviert ist. Das Guthaben der kostenlosen Testversion reicht aus, um diese Integration bei typischen Volumina für die gesamte Testphase zu betreiben. Die BigQuery Sandbox ohne Abrechnung funktioniert nicht, da die Storage Write API eine Abrechnung erfordert.

Sieht Pushwoosh meine BigQuery-Daten?

Nein. Die von Ihnen hochgeladenen Anmeldeinformationen für das Dienstkonto autorisieren Pushwoosh, in das von Ihnen ausgewählte Dataset zu schreiben. Pushwoosh liest nicht aus Ihrem Dataset und hat keinen Zugriff auf den Rest Ihres Projekts.

Kann ich in mehrere BigQuery-Datasets exportieren?

Pro Anwendung wird ein Ziel unterstützt. Wenn Sie dieselben Ereignisse in zwei Datasets benötigen, richten Sie in Ihrem Projekt eine geplante BigQuery-Abfrage ein, um Daten von pushwoosh_events in eine andere Tabelle zu kopieren.

Kann ich das Tabellenschema ändern?

Das Schema ist für alle Kunden festgelegt. Wenn Sie zusätzliche Spalten benötigen, extrahieren Sie diese aus dem properties-JSON in Ihren eigenen Ansichten oder geplanten Abfragen.

Was passiert, wenn ich die Integration vorübergehend deaktiviere?

Deaktivieren Sie Ereignisse zu BigQuery streamen und klicken Sie auf Anwenden. Pushwoosh stoppt das Anhängen von Ereignissen für diese Anwendung innerhalb von etwa 30 Sekunden.

Ereignisse, die während der Deaktivierung der Integration erzeugt werden, werden nicht zwischengespeichert oder nachgefüllt, wenn Sie sie wieder aktivieren. Pushwoosh behält die Konfiguration bei, einschließlich Anmeldeinformationen, Dataset und Ereignisauswahl.

Wie lösche ich die Integration vollständig?

Kontaktieren Sie support@pushwoosh.com, um die Integrationskonfiguration zu löschen. Das Dataset und die bereits in BigQuery geschriebenen Zeilen verbleiben in Ihrem Google Cloud-Konto.

Gibt es Liefergarantien?

Die Integration verwendet eine „at-least-once“-Zustellung. Im Normalbetrieb sind Duplikate selten. Ein Prozessneustart zwischen einem Anhängen und einem Commit kann eine kleine Anzahl doppelter Zeilen erzeugen. Deduplizieren Sie in SQL, wenn Ihre nachgelagerte Pipeline „exactly-once“-Ergebnisse erfordert.

Warum gibt es kein „Push Clicked“-Ereignis?

Pushwoosh stellt derzeit Push Sent, Push Delivered und Push Opened für Push-Benachrichtigungen in dieser Integration zur Verfügung. Ein dedizierter Push-Klick-Schritt ist nicht verfügbar. E-Mail und SMS haben ihre eigenen Lebenszyklusereignisse.