Google BigQuery-Integration

Hilfe von Entwicklern erforderlich

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. Verwenden Sie sie, 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.

Diese Integration sendet Daten nur in eine Richtung, von Pushwoosh zu BigQuery. Um stattdessen ein Segment von BigQuery-Benutzern in Pushwoosh zu importieren, siehe Externe Segmente.

Integrationsübersicht

Voraussetzungen

Bereiten Sie Folgendes vor, bevor Sie die Integrationseinrichtung öffnen.

1. Verwenden Sie ein Google Cloud-Projekt, für das die Abrechnung aktiviert ist. Guthaben aus der kostenlosen Testversion 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 Google direkt für die Nutzung von BigQuery. Pushwoosh berechnet für die Integration selbst keine Gebühren.

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

Die Kosten können umfassen:

• Datenerfassung: Pushwoosh streamt Ereignisse mit der BigQuery Storage Write API.
• Speicherung: BigQuery speichert die in Ihre Zieltabelle geschriebenen Zeilen.
• Abfragen: BigQuery berechnet die Kosten 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 mit dem Streamen ausgewählter Nachrichtenereignisse in Ihre BigQuery-Tabelle in nahezu Echtzeit. Für jedes Nachrichtenereignis, das durch Pushwoosh fließt, prüft das System, ob die Ereignisart in Ihrer Konfiguration ausgewählt ist.

Wenn ja, fügt Pushwoosh eine neue Zeile an Ihre Zieltabelle an. Wenn die Tabelle noch nicht existiert, erstellt Pushwoosh sie automatisch mit dem unten beschriebenen Schema. Ereignisse erscheinen typischerweise 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.

Erforderliche APIs aktivieren

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.

Ein Dienstkonto erstellen

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 Dienstkontoname 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-Bearbeiter: Ermöglicht Pushwoosh das Erstellen der Tabelle und das Anhängen von Zeilen.
   • BigQuery-Nutzer: Ermöglicht Pushwoosh die Verwendung der Storage Write API.
   

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.

Einen JSON-Schlüssel erstellen

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 mit dieser Datei kann in Ihr BigQuery-Projekt schreiben. Committen Sie sie nicht in Git und teilen Sie sie nicht über den Chat. Pushwoosh speichert den Schlüssel im Ruhezustand verschlüsselt und gibt ihn nach dem Hochladen nicht über die Benutzeroberfläche preis.

Ein Dataset erstellen

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 Datenstandort die Region des Datasets aus.

6. Klicken Sie auf Dataset erstellen.

Konfigurieren der 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 von Google Cloud heruntergeladen haben.
• Dataset-ID: Sobald GCP-Projekt-ID und Dienstkonto-JSON ausgefüllt sind, ruft Pushwoosh die Datasets ab, auf die Ihr Dienstkonto zugreifen kann. Wählen Sie das Ziel-Dataset 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 aus.
• 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 unterbrechen, ohne die Konfiguration zu löschen.

4. Klicken Sie auf Verbindung testen.

Pushwoosh validiert die Anmeldeinformationen gegen 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 wurde 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 ihrer Verwendung. Danach beginnen die ausgewählten Ereignisse mit dem Streaming zu BigQuery.

Überprüfen der 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, wird 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 erzeugt 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.

Abfrageeigenschaften

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 Ereigniszählungen 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, das 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 Ziel-Datasets 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 gesamte 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. Dataset-IDs sind case-sensitiv. Wählen Sie das Dataset aus dem Dropdown-Menü aus, um Tippfehler zu vermeiden.
Verbindungstest schlägt mit missing_permission fehl	Dem Dienstkonto fehlen die Rollen BigQuery-Daten-Bearbeiter oder BigQuery-Nutzer. Weisen Sie beide Rollen auf Projektebene zu oder für einen restriktiveren Zugriff auf Dataset-Ebene.
Verbindungstest erfolgreich, aber keine Zeilen erscheinen in BigQuery	Warten Sie mindestens 30 Sekunden. Überprüfen Sie, ob die Art des Ereignisses, das Sie senden, 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. Die Guthaben der kostenlosen Testversion reichen aus, um diese Integration bei typischen Volumen 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 beendet 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 nachgetragen, 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 Schritt für Push-Klicks ist nicht verfügbar. E-Mail und SMS haben ihre eigenen Lebenszyklusereignisse.