Cloud Data Ingestion für Google BigQuery
Auf dieser Seite finden Sie alles, was Sie zum Synchronisieren von Daten aus Google BigQuery mit Braze über Cloud Data Ingestion (CDI) benötigen: die Ressourcen, die Sie in Google Cloud erstellen müssen, wie Sie die Quelle verbinden und eine Synchronisierung in Braze erstellen, die Quelltabelle für jeden Datentyp sowie BigQuery-spezifische Fehlerbehebung.
Überblick über die Einrichtung
- Richten Sie in Ihrem BigQuery-Konto die Tabellen oder Ansichten ein, die Sie mit Braze synchronisieren möchten.
- Erstellen Sie ein Dienstkonto. Erteilen Sie ihm die Berechtigung, Abfrage-Jobs auszuführen, sowie Lesezugriff auf die Datensätze, die die zu synchronisierenden Daten enthalten. Wenn sich das Dienstkonto und Ihre Daten in unterschiedlichen Projekten befinden, werden diese Berechtigungen in unterschiedlichen Projekten erteilt. Details dazu finden Sie unter Wo die einzelnen Berechtigungen erteilt werden.
- Legen Sie fest, wie Braze auf das Dienstkonto zugreift, und verwenden Sie dafür eine der unterstützten Authentifizierungsmethoden.
- Erstellen Sie im Braze-Dashboard eine neue Quelle und Synchronisierung.
- Validieren Sie die Integration und starten Sie die Synchronisierung.
Schritt 1: Quelltabelle einrichten
Mit den Schritten in diesem Abschnitt erstellen Sie eine Tabelle mit einer PAYLOAD-Spalte. Wenn Sie Ihre Daten stattdessen im Schritt Datendefinition strukturieren möchten, können Sie eine bestehende Tabelle oder View verwenden. Überspringen Sie in diesem Fall die Tabellenerstellung und gewähren Sie Braze Lesezugriff auf die Tabellen oder Views, die Sie synchronisieren möchten. Einen Vergleich der Optionen finden Sie unter Datendefinitionsoption auswählen.
Sie können Projekt, Datensatz und Tabelle beliebig benennen, die Spaltennamen sollten jedoch den Definitionen in den folgenden Tabs entsprechen. Statt einer Tabelle können Sie auch eine View oder eine materialisierte View verwenden.
Optional können Sie ein neues Projekt oder einen neuen Datensatz für Ihre Quelltabelle einrichten:
CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Wenn Sie eine PAYLOAD-Spalte verwenden, kann Ihre Quelltabelle oder View auch Spalten enthalten, die in den folgenden Tabs nicht aufgeführt sind (zum Beispiel für Auditing oder Hashing). Braze liest nur die in diesen Tabs beschriebenen Spalten; andere Spalten werden bei Synchronisierungen über Cloud Data Ingestion nicht verwendet.
Wählen Sie den Tab für den Datentyp aus, den Sie synchronisieren möchten.
Nutzerattribute, angepasste Events und Kauf-Events verwenden alle dieselbe Struktur der Quelltabelle. Nur der Inhalt von PAYLOAD unterscheidet sich.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
--At least one of external_id, alias_name and alias_label, or braze_id is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
--braze_id can only be used to update existing users created through the Braze SDK
braze_id STRING,
--If you include both email and phone, email is used as the primary identifier
email STRING,
phone STRING,
payload JSON
);
| Feldname | Typ | Modus |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
PAYLOAD |
JSON | REQUIRED |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
BRAZE_ID |
STRING | NULLABLE |
EMAIL |
STRING | NULLABLE |
PHONE |
STRING | NULLABLE |
UPDATED_AT– Der Zeitpunkt, zu dem diese Zeile in der Tabelle aktualisiert oder ihr hinzugefügt wurde. Braze synchronisiert Zeilen, bei denenUPDATED_ATspäter als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenz-Zeitstempel werden möglicherweise erneut synchronisiert, wenn neue Zeilen denselben Zeitstempel haben.- Spalten für Nutzer-Bezeichner – Ihre Tabelle kann eine oder mehrere Spalten für Nutzer-Bezeichner enthalten. Jede Zeile sollte nur einen Bezeichner enthalten (entweder
external_id, die Kombination ausalias_nameundalias_label,braze_id,emailoderphone). Eine Quelltabelle kann Spalten für einen, zwei, drei, vier oder alle fünf Bezeichnertypen enthalten.EXTERNAL_ID– Hiermit wird die Nutzer:in identifiziert, die Sie aktualisieren möchten. Dieser Wert sollte mit dem in Braze verwendetenexternal_id-Wert übereinstimmen.ALIAS_NAMEundALIAS_LABEL– Diese beiden Spalten erstellen ein Nutzer-Alias-Objekt.alias_namesollte ein eindeutiger Bezeichner sein, undalias_labelgibt den Typ des Alias an. Nutzer:innen können mehrere Aliasse mit unterschiedlichen Labels haben, aber nur einenalias_nameproalias_label.BRAZE_ID– Der Braze-Nutzer-Bezeichner. Er wird vom Braze SDK generiert. Über Cloud Data Ingestion können keine neuen Nutzer:innen mit einer Braze-ID erstellt werden. Um neue Nutzer:innen zu erstellen, geben Sie eine externe Nutzer-ID oder einen Nutzer-Alias an.EMAIL– Die E-Mail-Adresse der Nutzer:in. Wenn mehrere Profile mit derselben E-Mail-Adresse existieren, wird bei Updates das zuletzt aktualisierte Profil priorisiert. Wenn Sie sowohl E-Mail-Adresse als auch Telefonnummer angeben, wird die E-Mail-Adresse als primärer Bezeichner verwendet.PHONE– Die Telefonnummer der Nutzer:in. Wenn mehrere Profile mit derselben Telefonnummer existieren, wird bei Updates das zuletzt aktualisierte Profil priorisiert.
PAYLOAD– Ein JSON-String mit den Feldern, die Sie mit dem Nutzerprofil in Braze synchronisieren möchten.
Bei Attribut-Synchronisierungen folgt PAYLOAD dem Format des Nutzerattribut-Objekts. Sie können verschachtelte angepasste Attribute, Arrays von Objekten und Abo-Gruppenstatus einschließen. Payload-Beispiele finden Sie unter Tabelleneinrichtung.

BigQuery-Partitionierung
CDI unterstützt Partitionen für BigQuery. Wenn Sie nach einer Funktion von UPDATED_AT partitionieren (zum Beispiel mit der Granularität Tag, Woche oder Stunde, je nach Größe Ihres Datensatzes), kann BigQuery die zu scannenden Daten reduzieren. Das verbessert Performance und Effizienz bei sehr großen Tabellen.
Partitionieren Sie nicht nach anderen Feldern. Testen Sie verschiedene Konfigurationen, um die beste Einrichtung für Ihre spezifischen Daten zu finden.
Alle CDI-Abfragen filtern nach UPDATED_AT, dieses Verhalten kann sich jedoch ändern. Gestalten Sie Ihr Tabellenschema so, dass Abfragen diese Klausel nicht enthalten müssen.
Weitere Informationen finden Sie in der BigQuery-Dokumentation zur Partitionierung.
Angepasste Events verwenden dieselbe Quelltabelle wie Nutzerattribute. Erstellen Sie die im Tab Nutzerattribute gezeigte Tabelle und befüllen Sie PAYLOAD anschließend mit einem Event-Objekt.
Für die Synchronisierung von Events ist ein Event-Name erforderlich. Formatieren Sie das Feld time als ISO-8601-String oder im Format yyyy-MM-dd'T'HH:mm:ss:SSSZ. Ist das Feld time nicht vorhanden, verwendet Braze den Wert der Spalte UPDATED_AT als Event-Zeitpunkt. Andere Felder, darunter app_id und properties, sind optional.
Sie können ein Event pro Zeile synchronisieren.
{
"app_id" : "your-app-id",
"name" : "rented_movie",
"time" : "2013-07-16T19:20:45+01:00",
"properties": {
"movie": "The Sad Egg",
"director": "Alex Smith"
}
}
Kauf-Events verwenden dieselbe Quelltabelle wie Nutzerattribute. Erstellen Sie die im Tab Nutzerattribute gezeigte Tabelle und befüllen Sie PAYLOAD anschließend mit einem Kauf-Objekt.
Für die Synchronisierung von Kauf-Events sind product_id, currency und price erforderlich. Formatieren Sie das optionale Feld time als ISO-8601-String oder im Format yyyy-MM-dd'T'HH:mm:ss:SSSZ. Ist das Feld time nicht vorhanden, verwendet Braze den Wert der Spalte UPDATED_AT als Event-Zeitpunkt. Andere Felder, darunter app_id, quantity und properties, sind optional.
Sie können ein Kauf-Event pro Zeile synchronisieren.
{
"app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
"product_id" : "Completed Order",
"currency" : "USD",
"price" : 219.98,
"time" : "2013-07-16T19:20:30+01:00",
"properties" : {
"products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
{ "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
]
}
}
Bevor Sie eine Katalog-Synchronisierung erstellen, legen Sie den Zielkatalog in Braze an. Den vollständigen Katalog-Workflow finden Sie unter Katalogdaten synchronisieren und löschen.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CATALOGS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
id STRING,
payload JSON,
deleted BOOLEAN
);
| Feldname | Typ | Modus |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
PAYLOAD |
JSON | REQUIRED |
ID |
STRING | REQUIRED |
DELETED |
BOOLEAN | OPTIONAL |
Der Name der Integration muss exakt mit dem Namen des Katalogs übereinstimmen, den Sie in Braze erstellt haben.
Braze empfiehlt, eine View aus Ihren Katalogdaten zu erstellen, damit die Quelltabelle bei jeder Synchronisierung vollständig aktualisiert wird. Wenn Sie zum Beispiel eine Tabelle mit Produktdaten (product_catalog_1) mit product_id und drei weiteren Attributen haben, könnten Sie die folgende View synchronisieren:
CREATE view IF NOT EXISTS BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS (SELECT
last_updated as UPDATED_AT,
product_id as ID,
TO_JSON(
STRUCT(
attribute_1,
attribute_2,
attribute_3,
)
) as PAYLOAD
FROM `BRAZE_CLOUD_PRODUCTION.INGESTION.product_catalog_1`);
Bevor Sie eine Datenobjekt-Synchronisierung erstellen, legen Sie den Datenobjekttyp und seine Felder in Braze an. Den vollständigen Workflow finden Sie unter Datenobjekte synchronisieren.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.ACCOUNTS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
object_id STRING,
payload JSON,
deleted BOOLEAN
);
| Feldname | Typ | Erforderlich? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Ja |
OBJECT_ID |
STRING | Ja |
PAYLOAD |
JSON | Ja |
DELETED |
BOOLEAN | OPTIONAL |
UPDATED_AT– Der Zeitpunkt, zu dem diese Zeile in der Tabelle aktualisiert oder hinzugefügt wurde. Braze synchronisiert Zeilen, bei denenUPDATED_ATspäter als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenzzeitstempel werden möglicherweise erneut synchronisiert, wenn neue Zeilen denselben Zeitstempel haben.OBJECT_ID– Der Bezeichner des Datenobjekt-Datensatzes. Dieser muss mit demobject_id-Wert übereinstimmen, der in Braze für diesen Datenobjekttyp verwendet wird.PAYLOAD– Ein JSON-String mit den zu synchronisierenden Feldern und Werten. Jeder Schlüssel muss einem Feld entsprechen, das für den Datenobjekttyp in Braze definiert ist.DELETED– Beitruelöscht Braze den Datensatz, anstatt ihn zu aktualisieren. Lassen Sie diesen Wert für Zeilen, die Sie erstellen oder aktualisieren möchten, leer (null) oder setzen Sie ihn auffalse.
Bei Feldnamen innerhalb von PAYLOAD wird zwischen Groß- und Kleinschreibung unterschieden. Ein Schlüssel namens NAME entspricht nicht einem Feld namens name. Wenn die Schreibweise nicht übereinstimmt, meldet die Validierung den Schlüssel als undefiniertes Feld und das Feld, das damit befüllt werden sollte, als fehlend. Benennen Sie Ihre Schlüssel genau so, wie die Felder unter Dateneinstellungen > Datenobjekte angezeigt werden.
Braze erstellt oder ändert während einer Synchronisierung keine Datenobjekttypen. Definieren Sie den Typ und alle seine Felder in Braze, bevor Sie die Synchronisierung erstellen. Wenn Sie später ein Feld hinzufügen möchten, fügen Sie es zuerst dem Typ hinzu und aktualisieren Sie anschließend Ihre Quelltabelle oder Abfrage.
Ein PAYLOAD-Wert für einen Account mit den Feldern name und team_id sieht zum Beispiel so aus:
{"name": "Acme Corp", "team_id": 42}
Wählen Sie im Schritt Datendefinition den Datentyp Datenobjekte aus und wählen Sie dann Ihren Datenobjekttyp. Datenobjekt-Synchronisierungen unterstützen Tabelle und SQL.
Mit dieser Synchronisierung verbinden Sie Nutzer:innen mit Datenobjekt-Datensätzen, zum Beispiel um Nutzer:innen mit den Accounts zu verknüpfen, zu denen sie gehören. Erstellen Sie die Beziehung in Braze, bevor Sie sie synchronisieren.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.ACCOUNT_USERS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
object_id STRING,
--At least one of external_id, alias_name and alias_label, email, or phone is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
email STRING,
phone STRING,
payload JSON,
deleted BOOLEAN
);
| Feldname | Typ | Erforderlich? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Ja |
OBJECT_ID |
STRING | Ja |
EXTERNAL_ID |
STRING | OPTIONAL |
ALIAS_NAME |
STRING | OPTIONAL |
ALIAS_LABEL |
STRING | OPTIONAL |
EMAIL |
STRING | OPTIONAL |
PHONE |
STRING | OPTIONAL |
PAYLOAD |
JSON | OPTIONAL |
DELETED |
BOOLEAN | OPTIONAL |
Jede Zeile benötigt OBJECT_ID sowie mindestens einen Nutzer-Bezeichner: EXTERNAL_ID, die Kombination aus ALIAS_NAME und ALIAS_LABEL, EMAIL oder PHONE. Verwenden Sie PAYLOAD für alle Felder, die für die Beziehung selbst definiert sind.

Anders als bei Synchronisierungen von Nutzerattributen wird BRAZE_ID bei Synchronisierungen von Nutzerbeziehungen nicht unterstützt. Verwenden Sie einen der oben aufgeführten Bezeichner.
UPDATED_AT– Der Zeitpunkt, zu dem diese Zeile in der Tabelle aktualisiert oder hinzugefügt wurde. Braze synchronisiert Zeilen, bei denenUPDATED_ATspäter als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenzzeitstempel werden möglicherweise erneut synchronisiert, wenn neue Zeilen denselben Zeitstempel haben.OBJECT_ID– Der Bezeichner des Datenobjekt-Datensatzes. Dieser muss mit demobject_id-Wert übereinstimmen, der in Braze für diesen Datenobjekttyp verwendet wird.PAYLOAD– Ein JSON-String mit den zu synchronisierenden Feldern und Werten. Jeder Schlüssel muss einem Feld entsprechen, das für den Datenobjekttyp in Braze definiert ist.DELETED– Beitruelöscht Braze den Datensatz, anstatt ihn zu aktualisieren. Lassen Sie diesen Wert für Zeilen, die Sie erstellen oder aktualisieren möchten, leer (null) oder setzen Sie ihn auffalse.
Bei Feldnamen innerhalb von PAYLOAD wird zwischen Groß- und Kleinschreibung unterschieden. Ein Schlüssel namens NAME entspricht nicht einem Feld namens name. Wenn die Schreibweise nicht übereinstimmt, meldet die Validierung den Schlüssel als undefiniertes Feld und das Feld, das damit befüllt werden sollte, als fehlend. Benennen Sie Ihre Schlüssel genau so, wie die Felder unter Dateneinstellungen > Datenobjekte angezeigt werden.
Braze erstellt oder ändert während einer Synchronisierung keine Datenobjekttypen. Definieren Sie den Typ und alle seine Felder in Braze, bevor Sie die Synchronisierung erstellen. Wenn Sie später ein Feld hinzufügen möchten, fügen Sie es zuerst dem Typ hinzu und aktualisieren Sie anschließend Ihre Quelltabelle oder Abfrage.
Wählen Sie im Schritt Datendefinition den Datentyp Datenobjekt-Nutzerbeziehungen aus und wählen Sie dann einen Beziehungsnamen, zum Beispiel User (Account-User).
Mit dieser Synchronisierung verbinden Sie Datenobjekt-Datensätze miteinander, zum Beispiel um Accounts mit ihren übergeordneten Accounts zu verknüpfen. Erstellen Sie die Beziehung in Braze, bevor Sie sie synchronisieren.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.ACCOUNT_SUBACCOUNTS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
object_id STRING,
related_object_id STRING,
payload JSON,
deleted BOOLEAN
);
| Feldname | Typ | Erforderlich? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Ja |
OBJECT_ID |
STRING | Ja |
RELATED_OBJECT_ID |
STRING | Ja |
PAYLOAD |
JSON | OPTIONAL |
DELETED |
BOOLEAN | OPTIONAL |
OBJECT_ID ist der Datensatz, von dem die Beziehung ausgeht, und RELATED_OBJECT_ID ist der Datensatz, auf den sie verweist. Beide sind in jeder Zeile erforderlich. Verwenden Sie PAYLOAD für alle Felder, die für die Beziehung selbst definiert sind.
UPDATED_AT– Der Zeitpunkt, zu dem diese Zeile in der Tabelle aktualisiert oder hinzugefügt wurde. Braze synchronisiert Zeilen, bei denenUPDATED_ATspäter als der zuletzt synchronisierte Wert ist. Zeilen mit genau dem Grenzzeitstempel werden möglicherweise erneut synchronisiert, wenn neue Zeilen denselben Zeitstempel haben.OBJECT_ID– Der Bezeichner des Datenobjekt-Datensatzes. Dieser muss mit demobject_id-Wert übereinstimmen, der in Braze für diesen Datenobjekttyp verwendet wird.PAYLOAD– Ein JSON-String mit den zu synchronisierenden Feldern und Werten. Jeder Schlüssel muss einem Feld entsprechen, das für den Datenobjekttyp in Braze definiert ist.DELETED– Beitruelöscht Braze den Datensatz, anstatt ihn zu aktualisieren. Lassen Sie diesen Wert für Zeilen, die Sie erstellen oder aktualisieren möchten, leer (null) oder setzen Sie ihn auffalse.
Bei Feldnamen innerhalb von PAYLOAD wird zwischen Groß- und Kleinschreibung unterschieden. Ein Schlüssel namens NAME entspricht nicht einem Feld namens name. Wenn die Schreibweise nicht übereinstimmt, meldet die Validierung den Schlüssel als undefiniertes Feld und das Feld, das damit befüllt werden sollte, als fehlend. Benennen Sie Ihre Schlüssel genau so, wie die Felder unter Dateneinstellungen > Datenobjekte angezeigt werden.
Braze erstellt oder ändert während einer Synchronisierung keine Datenobjekttypen. Definieren Sie den Typ und alle seine Felder in Braze, bevor Sie die Synchronisierung erstellen. Wenn Sie später ein Feld hinzufügen möchten, fügen Sie es zuerst dem Typ hinzu und aktualisieren Sie anschließend Ihre Quelltabelle oder Abfrage.
Wählen Sie im Schritt Datendefinition den Datentyp Datenobjekt-Beziehungen aus und wählen Sie dann einen Beziehungsnamen, zum Beispiel Subaccount (Account-Account).
Canvas-Trigger ermöglichen Zero-Copy-Personalisierung. Informationen zur Einrichtung des Ziel-Canvas und zu wichtigen Hinweisen finden Sie unter Zero-Copy-Personalisierung.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
--At least one of external_id or alias_name and alias_label is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
properties JSON
);
| Feldname | Typ | Erforderlich? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Ja |
PROPERTIES |
JSON | Ja |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
Canvas-Trigger-Synchronisierungen unterscheiden sich in drei Punkten von anderen Synchronisierungen von Nutzerdaten:
- Es werden nur externe IDs oder Nutzer-Aliase als Bezeichner unterstützt. E-Mail-Adressen und Telefonnummern werden als Bezeichner nicht unterstützt.
- Es können nur bestehende Braze-Nutzer:innen synchronisiert werden. Neue Nutzer:innen können nicht angelegt werden.
PROPERTIESersetzt die SpaltePAYLOAD. Dabei handelt es sich um einen JSON-String mit den Feldern, die Sie als Canvas-Entry-Eigenschaften für die Personalisierung verwenden möchten.
Ihre Canvas-Trigger-Tabelle benötigt die folgenden Spalten:
UPDATED_AT– Der Zeitpunkt, zu dem diese Zeile aktualisiert oder der Tabelle hinzugefügt wurde. Braze synchronisiert Zeilen, derenUPDATED_ATspäter als der zuletzt synchronisierte Wert liegt. Zeilen mit genau dem Grenz-Zeitstempel können erneut synchronisiert werden, wenn neue Zeilen denselben Zeitstempel haben.- Entweder
EXTERNAL_IDoderALIAS_NAMEundALIAS_LABELals Spalte für den Nutzer-Bezeichner. Diese identifizieren die Nutzer:innen, für die Sie Canvas-Messaging triggern möchten.EXTERNAL_ID– Identifiziert die Nutzer:innen, die in das Canvas eintreten sollen. Dieser Wert sollte mit dem in Braze verwendeten Wertexternal_idübereinstimmen.ALIAS_NAMEundALIAS_LABEL– Diese Spalten erstellen ein Nutzer-Alias-Objekt.alias_namesollte ein eindeutiger Bezeichner sein, undalias_labelgibt den Typ des Alias an. Nutzer:innen können mehrere Aliase mit unterschiedlichen Labels haben, aber nur einenalias_nameproalias_label.
PROPERTIES– Ein JSON-String mit Feldern, die in Ihrem Canvas als Eigenschaften für die Personalisierung verfügbar sein sollen. Er sollte nutzerspezifische Informationen enthalten.

Eigenschaften sind nicht für jede Zeile oder jede:n Nutzer:in erforderlich. Die Werte der Eigenschaften müssen jedoch ein gültiger JSON-String sein. Geben Sie einen leeren String {} ein, wenn es für die Zeile keine Eigenschaften gibt.
Wählen Sie zum Einstieg beim Erstellen einer neuen Synchronisierung den Datentyp Canvas-Trigger aus.
Quelltabellen für das Löschen von Nutzer:innen sollten einen oder mehrere Nutzer-Bezeichnertypen und einen UPDATED_AT-Zeitstempel enthalten. Payload-Spalten werden für Daten zum Löschen von Nutzer:innen nicht unterstützt.
UPDATED_AT– Der Zeitpunkt, zu dem diese Zeile aktualisiert oder der Tabelle hinzugefügt wurde. Braze synchronisiert Zeilen, derenUPDATED_ATnach dem zuletzt synchronisierten Wert liegt. Zeilen mit exakt dem Grenzzeitstempel werden möglicherweise erneut synchronisiert, wenn neue Zeilen denselben Zeitstempel haben.- Spalten für Nutzer-Bezeichner – Jede Zeile sollte nur einen Bezeichner enthalten: entweder
external_id, die Kombination ausalias_nameundalias_labeloderbraze_id. Eine Quelltabelle kann Spalten für einen, zwei oder alle drei Bezeichnertypen enthalten.EXTERNAL_ID– Dieser Wert identifiziert die Nutzer:in, die Sie aktualisieren möchten. Er sollte dem in Braze verwendetenexternal_id-Wert entsprechen.ALIAS_NAMEundALIAS_LABEL– Diese beiden Spalten erstellen ein Nutzer-Alias-Objekt.alias_namesollte ein eindeutiger Bezeichner sein, undalias_labelgibt den Typ des Alias an. Nutzer:innen können mehrere Aliasse mit unterschiedlichen Labels haben, aber nur einenalias_nameproalias_label.BRAZE_ID– Der Braze-Nutzer-Bezeichner. Er wird vom Braze SDK generiert. Über Cloud Data Ingestion können keine neuen Nutzer:innen mit einer Braze-ID erstellt werden. Um neue Nutzer:innen zu erstellen, geben Sie eine externe Nutzer-ID oder einen Nutzer-Alias an.

Fügen Sie Ihrer Tabelle zum Entfernen von Nutzer:innen keine PAYLOAD-Spalte hinzu. Um ein versehentliches, dauerhaftes Entfernen von Nutzer:innen zu verhindern, schlägt eine Synchronisierung fehl, wenn die Quelltabelle eine Payload-Spalte enthält. Alle anderen Spalten sind zulässig, werden von Braze jedoch ignoriert.
Erstellen Sie eine Tabelle mit den folgenden Feldern:
| Feldname | Typ | Modus |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
BRAZE_ID |
STRING | NULLABLE |
Setzen Sie auf der Seite Import-Synchronisierung erstellen den Datentyp auf Nutzer:innen löschen, damit während der Integrationsausführung die richtigen Aktionen durchgeführt werden. Weitere Informationen finden Sie unter Nutzer:innen mit Cloud Data Ingestion löschen.

Das Löschen von Nutzerprofilen kann nicht rückgängig gemacht werden. Die Löschaktion entfernt Nutzer:innen dauerhaft, was zu Abweichungen in Ihren Daten führen kann. Details finden Sie unter Auswirkungen des Löschens von Nutzerprofilen.
Schritt 2: Dienstkonto erstellen und Berechtigungen erteilen
Erstellen Sie in GCP ein Dienstkonto, über das Braze eine Verbindung herstellt und Daten aus Ihren Tabellen liest. Das Dienstkonto benötigt die folgenden Berechtigungen:
- BigQuery Connection User: Ermöglicht Braze, Verbindungen herzustellen.
- BigQuery User: Gewährt Braze Zugriff, um Abfragen auszuführen, Metadaten von Datensätzen zu lesen und Tabellen aufzulisten.
- BigQuery Data Viewer: Gewährt Braze Zugriff, um Datensätze und deren Inhalte anzuzeigen.
- BigQuery Job User: Gewährt Braze Zugriff, um Jobs auszuführen.
Wo Sie die einzelnen Berechtigungen erteilen
Jede BigQuery-Abfrage wird als Job in einem Projekt ausgeführt und kann Tabellen in anderen Projekten lesen. BigQuery prüft jede Berechtigung in ihrem jeweiligen Projekt. Wenn sich Ihr Dienstkonto und Ihre Daten im selben Projekt befinden, erteilen Sie alle Rollen in diesem Projekt. Andernfalls erteilen Sie jede Rolle in dem Projekt, das in der folgenden Tabelle angegeben ist.
| Rolle | Wo Sie sie erteilen |
|---|---|
| BigQuery Job User BigQuery User BigQuery Connection User |
Abhängig von Ihrer Authentifizierungsmethode: Dienstkontoschlüssel: Das Projekt, in dem das Dienstkonto erstellt wurde. Dies ist der Wert project_id in der JSON-Schlüsseldatei und kann sich vom Projekt unterscheiden, das Sie in Braze eingeben.Workload Identity Federation: Das Projekt, das Sie im Feld Projekt Ihrer Braze-Quelle eingeben. Braze führt Abfrage-Jobs in diesem Projekt aus, und BigQuery stellt die Abfragen diesem Projekt in Rechnung. |
| BigQuery Data Viewer | Die Datensätze oder Tabellen, die Sie synchronisieren, in dem Projekt, das Sie im Feld Projekt Ihrer Braze-Quelle eingeben. Wenn Sie eine View synchronisieren oder eine SQL-Abfrage verwenden, die aus anderen Datensätzen liest, erteilen Sie diese Rolle auch für diese Datensätze. |

Wenn Sie sich mit einem Dienstkontoschlüssel authentifizieren und Ihr Dienstkonto in einem anderen Projekt als Ihre Daten erstellt wurde, erteilen Sie BigQuery Job User im Projekt des Dienstkontos und BigQuery Data Viewer für die Datensätze, die Sie synchronisieren. Wenn das Dienstkonto in seinem eigenen Projekt nicht über bigquery.jobs.create verfügt, schlagen Synchronisierungen mit dem Fehler 403 Access Denied fehl.
Schritt 3: Authentifizierung einrichten
Braze kann mit einer der folgenden Authentifizierungsmethoden auf das Dienstkonto zugreifen:
| Methode | So authentifiziert Braze | Was Sie in Braze eingeben |
|---|---|---|
| Workload Identity Federation | Braze impersonates your service account with a short-lived identity, so you don’t create or upload a key. | Project number, Workload identity pool ID, Provider ID, and Service account email |
| Service account key | Braze authenticates with a JSON key that you create for your service account. | JSON key file for the service account |
Workload Identity Federation
Mit Workload Identity Federation (WIF) authentifiziert sich Braze bei Google Cloud mit einer kurzlebigen Identität aus der eigenen AWS-Umgebung und nimmt dann die Identität des für Braze erstellten Dienstkontos an. Sie konfigurieren Ihr Projekt so, dass es dieser Identität nur für Ihren Workspace vertraut. Sie erstellen oder teilen keinen Dienstkontoschlüssel.
Sie richten WIF einmal pro Google-Cloud-Projekt ein. Eine WIF-Zugangsberechtigung bedient sowohl BigQuery- als auch Google Cloud Storage-Quellen. Wenn Sie diese Schritte bereits für eine Google Cloud Storage-Quelle abgeschlossen haben, gewähren Sie dem vorhandenen Dienstkonto die Berechtigungen für diese Quelle und überspringen den Rest dieses Abschnitts.
Voraussetzungen
Um diese Schritte in der Google Cloud Console auszuführen, benötigen Sie die Berechtigung, Workload Identity Pools zu erstellen und IAM-Richtlinien (Identity and Access Management) für das Dienstkonto und Ihre Daten zu verwalten. Sie können zum Beispiel die Rollen Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) und Service Account Admin (roles/iam.serviceAccountAdmin) verwenden.
Nur dem Principal Ihres Workspace vertrauen

Gewähren Sie den Zugriff für den vollständigen Amazon Resource Name (ARN) des Braze-Principals aus Ihrem Formular für die Zugangsdaten. Gewähren Sie keinen Zugriff für die AWS-Rolle oder das AWS-Konto von Braze. Eine Freigabe auf Rollen- oder Kontoebene ermöglicht es anderen Braze-Kund:innen, Ihre Daten zu lesen.
Jeder Braze-Workspace auf derselben Braze-Instanz verwendet dieselbe AWS-Rolle. Nur der Sitzungsname am Ende des Principal-ARN, also Ihre Workspace-ID, ist eindeutig für Sie.
Die Standard-Attributabbildung von Google für AWS-Anbieter setzt aws_role auf den Rollen-ARN ohne den Sitzungsnamen. Wenn Sie also Identitäten Zugriff gewähren, die einem aws_role-Wert entsprechen, wie etwa principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, vertrauen Sie jedem Braze-Workspace auf Ihrer Instanz, einschließlich Ihres eigenen.
So beschränken Sie Ihre Daten auf Ihren Workspace:
- Gewähren Sie nur Identitäten Zugriff, deren
subjectIhr vollständiger Braze-Principal-ARN ist. Das ist der Principalprincipal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN. - Gewähren Sie keinen Zugriff für All identities in the pool oder für Identitäten, die nach
aws_roleoderaccountgefiltert sind. - Schreiben Sie keine Attributbedingung, die nur das AWS-Konto oder die AWS-Rolle prüft.
- Behalten Sie die Standard-Attributabbildung für
google.subjectbei, alsoassertion.arn.
Der Braze-Principal-ARN unterscheidet sich je nach Workspace und Braze-Instanz, und Braze verwendet für Google-Quellen eine andere AWS-Rolle als für andere Quellen wie Snowflake. Kopieren Sie den Wert immer aus einem BigQuery- oder Google-Cloud-Storage-Formular für Zugangsdaten in dem Workspace, den Sie verbinden.
Braze-Principal-ARN kopieren
Beginnen Sie in Braze mit dem Erstellen Ihrer BigQuery-Quelle und wählen Sie Workload Identity Federation als Authentifizierungsmethode aus. Kopieren Sie den Wert aus Schritt 1 des Formulars für die Zugangsdaten, Copy the Braze principal ARN, und lassen Sie das Formular geöffnet.
Wenn das Feld Unavailable anzeigt, ist WIF für Ihre Braze-Instanz nicht verfügbar. Verwenden Sie stattdessen einen Dienstkontoschlüssel.
Erforderliche APIs aktivieren
Gehen Sie in der Google Cloud Console zu APIs & Services > Library und aktivieren Sie die folgenden APIs für Ihr Projekt:
- IAM Service Account Credentials API
- Security Token Service API
- Identity and Access Management (IAM) API
Workload Identity Pool und Anbieter erstellen
- Gehen Sie zu IAM & Admin > Workload Identity Federation und wählen Sie dann Create pool aus.
- Geben Sie einen Namen für den Pool ein, etwa „Braze CDI“. Notieren Sie sich die Pool ID und wählen Sie dann Continue aus.
- Wählen Sie unter Select a provider die Option AWS aus.
- Geben Sie einen Anbieternamen ein, etwa „Braze AWS“, und notieren Sie sich die Provider ID.
- Geben Sie unter AWS account ID die 12-stellige Zahl ein, die im Braze-Principal-ARN auf
arn:aws:sts::folgt, und wählen Sie dann Continue aus. - Behalten Sie unter Configure provider attributes die Standardabbildung bei, einschließlich
google.subject=assertion.arn. - Wählen Sie Save aus.
Pool- und Anbieter-IDs müssen 4 bis 32 Zeichen lang sein und dürfen nur Kleinbuchstaben, Zahlen und Bindestriche enthalten.
Anbieter auf Ihren Principal beschränken (optional)
Für zusätzliche Sicherheit (Defense in Depth) können Sie eine Attributbedingung hinzufügen, sodass der Anbieter nur den Principal Ihres Workspace akzeptiert. Google lehnt dann jede andere Identität bereits beim Token-Austausch ab, bevor Google Berechtigungen für Dienstkonten prüft.
- Wählen Sie im Pool den Anbieter und dann Edit aus.
- Wählen Sie unter Attribute conditions die Option Add condition aus.
-
Geben Sie die folgende Bedingung ein und ersetzen Sie
BRAZE_PRINCIPAL_ARNdurch den vollständigen Wert, den Sie aus dem Formular für die Zugangsdaten kopiert haben:assertion.arn == 'BRAZE_PRINCIPAL_ARN'
- Wählen Sie Save aus.
Diese Bedingung bindet den Anbieter an einen einzigen Braze-Workspace. Um einen weiteren Workspace zu verbinden, erstellen Sie dafür einen separaten Anbieter oder listen Sie beide Principals auf, etwa assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].
Braze-Principal an das Dienstkonto binden
Gewähren Sie dem Principal Ihres Workspace die Berechtigung, die Identität des Dienstkontos anzunehmen:
- Gehen Sie zu IAM & Admin > Workload Identity Federation und wählen Sie dann Ihren Pool aus.
- Wählen Sie Grant access und dann Grant access using service account impersonation aus.
- Wählen Sie unter Service account das Dienstkonto aus, das Sie für Braze erstellt haben.
- Wählen Sie unter Select principals die Option Only identities matching the filter aus.
- Wählen Sie unter Attribute name die Option subject aus. Fügen Sie unter Attribute value den vollständigen Braze-Principal-ARN aus dem Formular für die Zugangsdaten ein.
- Wählen Sie Save aus. Wenn Google anbietet, eine Konfigurationsdatei für die Client-Bibliothek herunterzuladen, wählen Sie Dismiss aus. Braze benötigt sie nicht.
Damit wird die Rolle Workload Identity User (roles/iam.workloadIdentityUser) für das Dienstkonto einem Principal in dieser Form gewährt:
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN
Zur Bestätigung öffnen Sie das Dienstkonto und wählen den Tab Permissions aus. Die Rolle Workload Identity User sollte diesen Principal auflisten, der mit Ihrem vollständigen Braze-Principal-ARN endet.

Wählen Sie nicht All identities in the pool aus und filtern Sie nicht nach aws_role. Beide Optionen treffen auf jeden Braze-Workspace auf Ihrer Braze-Instanz zu, da alle dieselbe AWS-Rolle verwenden. Weitere Informationen finden Sie unter Nur dem Principal Ihres Workspace vertrauen.
Gewähren Sie diese Rolle nur für das Dienstkonto. Eine Freigabe auf Projektebene ermöglicht es dem Principal, die Identität jedes Dienstkontos im Projekt anzunehmen.
IAM-Änderungen können einige Minuten dauern, bis sie wirksam werden. Wenn ein Verbindungstest direkt nach dem Gewähren des Zugriffs fehlschlägt, warten Sie einige Minuten und versuchen Sie es erneut.
Das Dienstkonto benötigt außerdem Zugriff auf Ihre Daten. Stellen Sie sicher, dass Sie ihm die Berechtigungen für diese Quelle gewährt haben. Wenn Sie eine Zugangsberechtigung sowohl für BigQuery als auch für Google Cloud Storage verwenden, gewähren Sie beide Berechtigungssätze demselben Dienstkonto.
Werte in Braze eingeben
Kehren Sie zum Formular für die Zugangsdaten in Braze zurück und geben Sie die folgenden Werte aus der Google Cloud Console ein:
| Braze-Feld | Wo Sie den Wert finden |
|---|---|
| Project number | Die Karte Project info im Dashboard der Console. Verwenden Sie die numerische Projektnummer, nicht die Projekt-ID. |
| Workload identity pool ID | Die Pool ID des Pools, den Sie erstellt haben |
| Provider ID | Die Provider ID des Anbieters, den Sie erstellt haben |
| Service account email | Die Email des Dienstkontos auf der Seite Service Accounts |
Braze kombiniert Projektnummer, Pool-ID und Anbieter-ID zur Zielgruppe (Audience), die Google mitteilt, welcher Anbieter die Anfrage von Braze validiert. Standardmäßig akzeptiert ein Anbieter seinen eigenen Ressourcennamen als Zielgruppe. Wenn Sie für Ihren Anbieter angepasste zulässige Zielgruppen festlegen, nehmen Sie den vollständigen Ressourcennamen des Anbieters auf.
So testet Braze die Verbindung
Wenn Sie die Verbindung in Braze testen, prüft Braze auch, ob Ihre Konfiguration nur Ihrem Workspace vertraut. Während des Tests versucht Braze denselben Austausch mit einem Test-Sitzungsnamen, der nur aus Nullen besteht, in dieser Form:
assumed-role/cdi-gcs-bigquery-sync-<deployment>/000000000000000000000000
Ihre Konfiguration muss diese Identität ablehnen, entweder beim Token-Austausch oder beim Versuch, die Identität Ihres Dienstkontos anzunehmen. Wenn beide Schritte erfolgreich sind, schlägt der Test fehl, da Ihre Konfiguration auch anderen Identitäten als dem Principal Ihres Workspace vertraut. Informationen zur Behebung finden Sie unter Ihre Konfiguration vertraut anderen Identitäten als Ihrem Workspace.
Wenn Sie die optionale Attributbedingung festgelegt haben, lehnt Google die Testidentität beim Token-Austausch ab. Andernfalls lehnt Google die Testidentität ab, wenn diese versucht, die Identität Ihres Dienstkontos anzunehmen. In beiden Fällen ist der Test erfolgreich.
Dieser abgelehnte Versuch kann bei jedem Verbindungstest in Ihren Google-Cloud-Audit-Logs erscheinen. Dieses Verhalten ist zu erwarten. Der Versuch stammt von der Braze-Prüfung und gewährt niemandem Zugriff auf Ihre Daten.
Fügen Sie keine Bedingung hinzu, die nur diese Testsitzung ablehnt. Eine solche Bedingung besteht den Test, während Ihre Konfiguration weiterhin anderen Braze-Workspaces vertraut.
Zugriff von Braze entfernen
Um Braze den Zugriff auf Ihre Daten zu entziehen, entfernen Sie die Rolle Workload Identity User für den Braze-Principal im Tab Permissions des Dienstkontos oder löschen Sie den Anbieter.
Einrichtung mit der gcloud CLI
Wenn Sie die Befehlszeile bevorzugen, aktivieren die folgenden Befehle die APIs, erstellen den Pool und den Anbieter und binden den Braze-Principal an Ihr Dienstkonto. Ersetzen Sie die Werte im ersten Block und fügen Sie den Braze-Principal-ARN genau so ein, wie Sie ihn kopiert haben.
PROJECT_ID="YOUR-PROJECT-ID"
POOL_ID="braze-cdi"
PROVIDER_ID="braze-aws"
SA_EMAIL="YOUR-SERVICE-ACCOUNT-EMAIL"
BRAZE_PRINCIPAL_ARN="PASTE-THE-BRAZE-PRINCIPAL-ARN-FROM-YOUR-CREDENTIAL-FORM"
PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
BRAZE_AWS_ACCOUNT_ID="$(echo "$BRAZE_PRINCIPAL_ARN" | cut -d: -f5)"
gcloud services enable iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
--project="$PROJECT_ID"
gcloud iam workload-identity-pools create "$POOL_ID" \
--project="$PROJECT_ID" --location="global" --display-name="Braze CDI"
gcloud iam workload-identity-pools providers create-aws "$PROVIDER_ID" \
--project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
--account-id="$BRAZE_AWS_ACCOUNT_ID"
# Optional: restrict the provider to your principal
gcloud iam workload-identity-pools providers update-aws "$PROVIDER_ID" \
--project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
--attribute-condition="assertion.arn == '${BRAZE_PRINCIPAL_ARN}'"
gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
--project="$PROJECT_ID" \
--role="roles/iam.workloadIdentityUser" \
--member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${BRAZE_PRINCIPAL_ARN}"
Service account key
Braze authentifiziert sich mit einem JSON-Schlüssel für Ihr Dienstkonto. Bestehende Zugangsdaten mit Dienstkontoschlüssel funktionieren weiterhin und müssen nicht migriert werden.
Öffnen Sie in der Google Cloud Console das Dienstkonto, gehen Sie zu Schlüssel > Schlüssel hinzufügen > Neuen Schlüssel erstellen und wählen Sie JSON aus. Laden Sie die Schlüsseldatei herunter. Diese laden Sie beim Erstellen der Quelle in Braze hoch.
Alternativ können Sie gcloud verwenden:
gcloud iam service-accounts keys create braze-cdi-key.json \
--iam-account=SERVICE_ACCOUNT_EMAIL
Ersetzen Sie SERVICE_ACCOUNT_EMAIL durch die E-Mail-Adresse des Dienstkontos. Weitere Informationen finden Sie unter Dienstkontoschlüssel erstellen und löschen.
Schritt 4: Zugriff für Braze-IPs zulassen
Wenn Sie Netzwerkrichtlinien eingerichtet haben, müssen Sie Braze Netzwerkzugriff auf Ihre BigQuery-Instanz gewähren. Lassen Sie den Zugriff von den folgenden IPs zu, die der Region Ihres Braze-Dashboards entsprechen.
Für die Instanzen US-01, US-02, US-03, US-04, US-05, US-06, US-07 sind dies die relevanten IP-Adressen:
23.21.118.19134.206.23.17350.16.249.952.4.160.21454.87.8.3454.156.35.25152.54.89.23818.205.178.15
Für die Instanz US-08 sind dies die relevanten IP-Adressen:
52.151.246.5152.170.163.18240.76.166.15740.76.166.17040.76.166.16740.76.166.16140.76.166.15640.76.166.16640.76.166.16040.88.51.7452.154.67.1740.76.166.8040.76.166.8440.76.166.8540.76.166.8140.76.166.7140.76.166.14440.76.166.145
Für die Instanz US-10 sind dies die relevanten IP-Adressen:
100.25.232.16435.168.86.17952.7.44.1173.92.153.1835.172.3.12950.19.162.19
Für die Instanzen EU-01 und EU-02 sind dies die relevanten IP-Adressen:
52.58.142.24252.29.193.12135.158.29.22818.157.135.973.123.166.463.64.27.363.65.88.253.68.144.1883.70.107.88
Für die Instanz AU-01 sind dies die relevanten IP-Adressen:
13.210.1.14513.211.70.15913.238.45.5452.65.73.16754.153.242.23954.206.45.213
Für die Instanz ID-01 sind dies die relevanten IP-Adressen:
108.136.157.246108.137.30.20716.78.128.7116.78.14.13416.78.162.20843.218.73.35
Für die Instanz JP-01 sind dies die relevanten IP-Adressen:
13.159.155.21254.199.221.24113.192.23.1654.250.120.13918.181.114.2323.114.38.100
Für die Instanz KR-01 sind dies die relevanten IP-Adressen:
43.200.215.452.79.67.17552.79.113.603.34.212.9254.116.134.2313.37.197.225
Schritt 5: Eine neue Quelle im Braze-Dashboard erstellen
Gehen Sie im Braze-Dashboard zu Dateneinstellungen > Cloud-Datenaufnahme > Quellen, wählen Sie Datenquelle hinzufügen und dann Google BigQuery aus.
Schritt 5.1: BigQuery-Verbindungsinformationen und Quelltabelle hinzufügen
Geben Sie einen Namen für Ihre Quelle ein. Geben Sie anschließend Ihre BigQuery-Zugangsdaten und die Konfiguration ein:
- Geben Sie unter Name der Zugangsdaten eine Bezeichnung ein, an der Sie diese Zugangsdaten in Braze wiedererkennen.
- Wählen Sie als Authentifizierungsmethode die Methode aus, die Sie in Schritt 3 eingerichtet haben, und geben Sie die zugehörigen Zugangsdaten ein. Geben Sie für Workload Identity Federation Folgendes ein: Project number, Workload identity pool ID, Provider ID, and Service account email. Geben Sie für Service account key Folgendes ein: JSON key file for the service account.
Füllen Sie danach die übrigen Konfigurationsfelder aus.
Schritt 5.2: Verbindung testen und mit der Quelle verbinden
Wählen Sie als Nächstes Verbindung testen aus. Wenn der Test erfolgreich ist, schließen Sie die übrigen Einstellungen ab und klicken Sie auf Mit Quelle verbinden. Schlägt die Verbindung fehl, erscheint eine Fehlermeldung, die Ihnen bei der Fehlerbehebung hilft.
Schritt 6: Eine neue Synchronisierung im Braze-Dashboard erstellen
Gehen Sie zu Dateneinstellungen > Cloud Data Ingestion > Synchronisierungen und wählen Sie Datensynchronisierung erstellen.
Details der Synchronisierung konfigurieren und Ihre Daten definieren
Geben Sie einen Namen für Ihre Synchronisierung ein. Wählen Sie dann eine aktive Quelle und einen Datentyp für die Synchronisierung aus. Wählen Sie anschließend einen Synchronisierungsmodus und definieren Sie Ihre Daten. Wählen Sie dann Vorschau und validieren.
Nach erfolgreicher Validierung wird eine Vorschau der Daten angezeigt. Wählen Sie Weiter: Benachrichtigungen, um fortzufahren. Wenn die Validierung fehlschlägt, wird eine Fehlermeldung angezeigt, die Ihnen bei der Fehlerbehebung hilft.

Sie müssen eine Synchronisierung erfolgreich validieren, bevor Sie mit den nächsten Schritten fortfahren können. Wenn Sie die Seite zur Erstellung der Synchronisierung schließen müssen, wählen Sie Als Entwurf speichern, um Ihren Arbeitsstand zu sichern.
Benachrichtigungseinstellungen hinzufügen
Geben Sie eine oder mehrere Kontakt-E-Mail-Adressen für Benachrichtigungen über Synchronisierungsfehler ein. Braze verwendet diese Kontaktinformationen, um Benachrichtigungen über Integrationsfehler zu versenden, etwa bei einem unerwarteten Verlust des Tabellenzugriffs.
Kontakt-E-Mail-Adressen erhalten nur Benachrichtigungen über globale Fehler oder Fehler auf Synchronisierungsebene, etwa fehlende Tabellen, fehlende Berechtigungen und Ähnliches. Probleme auf Zeilenebene werden nicht gemeldet. Globale Fehler weisen auf kritische Probleme mit der Verbindung hin, die die Ausführung von Synchronisierungen verhindern.
Zu solchen Problemen gehören unter anderem:
- Verbindungsprobleme
- Fehlende Ressourcen
- Probleme mit Berechtigungen
- Kein freier Speicherplatz in der Katalogstufe (nur Katalog-Synchronisierungen)
Zeitplan festlegen
Konfigurieren Sie Ihre Synchronisierung abschließend als einmalig oder wiederkehrend.
Einmalige Synchronisierungen werden nur ausgeführt, wenn Sie im Dashboard Jetzt synchronisieren auswählen oder den Endpunkt Synchronisierung triggern aufrufen.
Wiederkehrende Synchronisierungen lassen sich in Intervallen von 5 Minuten bis zu einem Monat ausführen. Standardmäßig beträgt das kürzeste Intervall, das Sie im Dashboard festlegen können, 15 Minuten. So lassen sich die Rechenkosten Ihres Data Warehouse und das Anfragevolumen besser steuern. Wenn Sie in Abständen von nur 5 Minuten synchronisieren möchten, wenden Sie sich an den Braze-Support oder Ihren Customer-Success-Manager. Braze plant wiederkehrende Synchronisierungen in UTC.

Sie müssen eine Integration erfolgreich validieren, bevor sie vom Status „Entwurf“ in den Status „Aktiv“ wechseln kann. Wenn Sie die Erstellungsseite schließen, wird Ihre Integration gespeichert, und Sie können die Detailseite erneut aufrufen, um Änderungen vorzunehmen und die Integration zu validieren.
Synchronisierung ausführen
Nach der Aktivierung wird Ihre Synchronisierung nach dem Zeitplan ausgeführt, den Sie bei der Einrichtung konfiguriert haben. Wenn Sie die Synchronisierung außerhalb des Zeitplans ausführen oder die neuesten Daten abrufen möchten, wählen Sie Jetzt synchronisieren. Dieser Lauf hat keine Auswirkungen auf regelmäßig geplante zukünftige Synchronisierungen. Um eine Synchronisierung automatisch zu starten, sobald Ihre Daten aktualisiert werden, rufen Sie den Endpunkt Synchronisierung triggern aus Ihrer Pipeline auf.
Zusätzliche Integrationen oder Nutzer:innen einrichten (optional)
Sie können mehrere Integrationen mit Braze einrichten. Wenn Sie weitere Synchronisierungen erstellen, können Sie vorhandene Zugangsdaten wiederverwenden, sofern Sie sich mit demselben BigQuery-Konto verbinden.
Wenn Sie dieselbe:denselben Nutzer:in für mehrere Integrationen wiederverwenden, können Sie diese:n Nutzer:in im Braze-Dashboard erst löschen, wenn sie:er aus allen aktiven Synchronisierungen entfernt wurde.
BigQuery als verbundene Quelle verwenden
Eine verbundene Quelle ist eine Zero-Copy-Alternative zur Synchronisierung von Daten in Braze. Braze fragt Ihre BigQuery-Instanz direkt ab, um CDI-Segmente zu erstellen, ohne die zugrunde liegenden Daten zu kopieren. Informationen zu Konzepten, Einschränkungen und Kostenauswirkungen finden Sie unter Verbundene Quellen.
Schritt 1: Dienstkonto erstellen und Berechtigungen erteilen
Erstellen Sie in GCP ein Dienstkonto, über das Braze eine Verbindung herstellt und Daten aus Ihren Tabellen liest. Das Dienstkonto benötigt die folgenden Berechtigungen:
- BigQuery Connection User: Ermöglicht Braze, Verbindungen herzustellen.
- BigQuery User: Gewährt Braze Zugriff, um Abfragen auszuführen, Metadaten von Datensätzen zu lesen und Tabellen aufzulisten.
- BigQuery Data Viewer: Gewährt Braze Zugriff, um Datensätze und deren Inhalte anzuzeigen.
- BigQuery Job User: Gewährt Braze Zugriff, um Jobs auszuführen.
- bigquery.tables.create: Gewährt Braze Zugriff, um beim Aktualisieren von Segmenten temporäre Tabellen zu erstellen.
Erteilen Sie diese Rollen in den Projekten, die unter Wo die einzelnen Berechtigungen erteilt werden beschrieben sind. Erteilen Sie bigquery.tables.create im selben Projekt wie BigQuery Job User.
Mit diesem Dienstkonto wird die Liste der Tabellen erstellt, die in Ihren CDI-Segmenterweiterungen verfügbar sind, und es werden Quelltabellen abgefragt, um neue Segmente zu erstellen. Nachdem die verbundene Quelle erstellt wurde, ermittelt Braze die Namen und Beschreibungen aller Tabellen, die für die Nutzer:in im Quellschema verfügbar sind.
Sie können Zugriff auf alle Tabellen eines Datensatzes oder nur Berechtigungen für bestimmte Tabellen erteilen. Alle Tabellen, auf die die Braze-Rolle Zugriff hat, können in der CDI-Segmenterweiterung abgefragt werden.
Die Berechtigung create table ist erforderlich, damit Braze eine Tabelle mit den Abfrageergebnissen Ihrer CDI-Segmenterweiterung erstellen kann, bevor das Segment in Braze aktualisiert wird. Braze erstellt pro Segment eine temporäre Tabelle, die nur so lange bestehen bleibt, wie Braze das Segment aktualisiert.
Nachdem Sie das Dienstkonto erstellt und die Berechtigungen erteilt haben, legen Sie mit einer der Methoden unter Schritt 3: Authentifizierung einrichten fest, wie Braze darauf zugreift. Wenn Sie für dieses Projekt bereits Workload Identity Federation eingerichtet haben, können Sie diese wiederverwenden. Erteilen Sie dem vorhandenen Dienstkonto die Berechtigungen aus diesem Schritt.
Die Einrichtung des Netzwerkzugriffs entspricht Schritt 4.
Schritt 2: Verbundene Quelle in Braze erstellen
Gehen Sie zu Dateneinstellungen > Cloud-Datenaufnahme > Verbundene Quellen, wählen Sie Datenquelle hinzufügen und dann Google BigQuery aus.
Geben Sie unter Quelle einrichten Folgendes ein:
- Zugangsdaten: Name der Zugangsdaten und die Felder für Ihre Authentifizierungsmethode. Geben Sie für Workload Identity Federation Folgendes ein: Project number, Workload identity pool ID, Provider ID, and Service account email. Geben Sie für Service account key Folgendes ein: JSON key file for the service account.
- Konfiguration: Projekt und Datensatz
Wählen Sie einen Namen für die verbundene Quelle. Dieser Name erscheint in der Liste der verfügbaren Quellen, wenn Sie eine neue CDI-Segmenterweiterung erstellen.
Konfigurieren Sie eine maximale Laufzeit für diese Quelle. Braze bricht alle Abfragen, die die maximale Laufzeit überschreiten, automatisch ab. Die maximal zulässige Laufzeit beträgt 60 Minuten; eine kürzere Laufzeit senkt die Kosten, die in Ihrem BigQuery-Konto anfallen. Diese Einstellung gilt für alle Abfragen, die über diese Quelle ausgeführt werden, einschließlich Synchronisierungen und CDI-Segmenterweiterungen, die sie verwenden.
Wählen Sie Verbindung testen aus, um zu überprüfen, ob die Liste der für die Nutzer:in sichtbaren Tabellen Ihren Erwartungen entspricht, und wählen Sie dann Fertig aus. Ihre verbundene Quelle ist nun erstellt und kann in CDI-Segmenterweiterungen verwendet werden.
Sie können mehrere verbundene Quellen in Braze einrichten, aber jede Quelle sollte so konfiguriert sein, dass sie sich mit einem anderen Datensatz verbindet. Wenn Sie weitere Quellen erstellen, können Sie vorhandene Zugangsdaten wiederverwenden, sofern Sie sich mit demselben BigQuery-Konto verbinden.
Eine Payload aus vorhandenen Spalten formatieren
Wenn Sie jedes Attribut intern lieber in einer eigenen Spalte speichern, müssen Sie diese Spalten in einen JSON-String konvertieren, um die Synchronisierung mit Braze zu befüllen. Verwenden Sie diese Abfrage in BigQuery, um Quellspalten in CDI-Felder zu formatieren.
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
attribute_2 STRING,
attribute_3 NUMERIC,
my_user_id STRING);
SELECT
CURRENT_TIMESTAMP as UPDATED_AT,
my_user_id as EXTERNAL_ID,
TO_JSON(
STRUCT(
'attribute_1' AS attribute_1,
'attribute_2'AS attribute_2,
'yet_another_attribute'AS attribute_3
)
) as PAYLOAD
FROM BRAZE.EXAMPLE_USER_DATA;
Weitere Hinweise zur Optimierung finden Sie unter Best Practices für Cloud Data Ingestion.
Fehlerbehebung
Test Connection läuft langsam
Test Connection wird in Ihrem Data Warehouse ausgeführt. Wenn Sie die Kapazität Ihres Warehouse erhöhen, kann das die Geschwindigkeit verbessern. Eine serverlose SQL-Instanz verkürzt die Aufwärmzeit und verbessert den Abfragedurchsatz, kann aber zu etwas höheren Integrationskosten führen.
Nutzer:in hat keine Berechtigung, die Tabelle abzufragen
Wenn Sie diesen Fehler erhalten, fügen Sie Nutzerberechtigungen hinzu, damit die Tabelle abgefragt werden kann.
Nutzer:in hat im Projekt keine Berechtigung bigquery.jobs.create
Wenn Sie diesen Fehler erhalten, kann das Dienstkonto in dem im Fehler genannten Projekt keine Abfrage-Jobs ausführen. Weisen Sie dem Dienstkonto in diesem Projekt die Rolle BigQuery Job User zu. Wenn Sie sich mit einem Dienstkonto-Schlüssel authentifizieren, ist dies das Projekt, in dem das Dienstkonto erstellt wurde. Es kann sich von dem Projekt unterscheiden, das Ihre Daten enthält. Weitere Informationen finden Sie unter Wo die einzelnen Berechtigungen erteilt werden.
Ihre Nutzung hat das angepasste Kontingent überschritten
Wenn Sie diesen Fehler erhalten, muss Ihr Kontingent aktualisiert werden, damit Sie die Synchronisierung mit Ihrer aktuellen Rate fortsetzen können.
Tabelle wurde am Standort {region} nicht gefunden
Wenn Sie diesen Fehler erhalten, überprüfen Sie, ob sich Ihre Tabelle im richtigen Projekt und Datensatz befindet.
Ungültige JWT-Signatur
Wenn Sie diesen Fehler erhalten, überprüfen Sie, ob der BigQuery-API-Dienst für Ihr Konto aktiviert ist.
Ihre Konfiguration vertraut anderen Identitäten als Ihrem Workspace
Wenn Sie Workload Identity Federation verwenden, kann der Verbindungstest mit folgendem Fehler fehlschlagen:
Your workload identity pool trusts every Braze customer, not only this workspace. Braze authenticated against it with a test identity (000000000000000000000000) that belongs to no Braze workspace, and your Google Cloud project accepted it, so another Braze customer could read this data. Grant the Workload Identity User role on your service account to the full Braze principal shown on the credential screen (principal://…/subject/<full ARN>) rather than to the role (principalSet://…/attribute.aws_role/…); restricting the pool provider’s attribute condition to that same principal works as well. Then test the connection again.
Das bedeutet, dass Google die Braze-Testidentität sowohl beim Token-Austausch als auch beim Identitätswechsel des Dienstkontos akzeptiert hat, wie unter So testet Braze die Verbindung beschrieben. Dieser Fehler tritt in der Regel auf, wenn das Dienstkonto allen Identitäten im Pool oder nach aws_role gefilterten Identitäten Zugriff gewährt.
So beheben Sie diesen Fehler:
- Öffnen Sie in der Google Cloud Console das Dienstkonto und wählen Sie den Tab Berechtigungen aus.
- Suchen Sie alle Principals mit der Rolle „Workload Identity User“, die mit
principalSet://beginnen und auf Ihren Pool verweisen. Entfernen Sie die Rolle bei jedem dieser Principals. - Stellen Sie sicher, dass Ihr vollständiger Principal die Rolle besitzt, wie unter Braze-Principal an das Dienstkonto binden beschrieben.
- Gehen Sie zu IAM & Admin > IAM und prüfen Sie, ob es auf Projektebene Zuweisungen der Rolle „Workload Identity User“ für Ihren Pool gibt. Entfernen Sie diese.
- Testen Sie die Verbindung erneut.
Alternativ können Sie die Attributbedingung des Anbieters auf Ihren vollständigen Principal beschränken, wie unter Anbieter auf Ihren Principal beschränken (optional) beschrieben. Google lehnt dann beim Token-Austausch jede andere Identität ab. Wir empfehlen dennoch, den Zugriff ausschließlich Ihrem vollständigen Principal zu gewähren.
Braze konnte nicht bestätigen, dass Ihr Pool nur diesem Workspace vertraut
Wenn Sie Workload Identity Federation verwenden, kann der Verbindungstest mit folgendem Fehler fehlschlagen:
Braze could not confirm that your workload identity pool trusts only this workspace. The check needs Google to explicitly refuse an identity that is not yours, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.
Die unter So testet Braze die Verbindung beschriebene Prüfung von Braze kam zu keinem Ergebnis. Beispielsweise hat ein Netzwerkfehler oder ein vorübergehender Google-Cloud-Fehler die Prüfung unterbrochen. Dieser Fehler bedeutet nicht, dass Ihre Konfiguration zu weit gefasst ist. Testen Sie die Verbindung erneut. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Braze-Support.
Berechtigung verweigert, wenn Braze die Identität des Dienstkontos annimmt
Wenn Sie Workload Identity Federation verwenden und der Verbindungstest mit einem Berechtigungsfehler bei iam.serviceAccounts.getAccessToken fehlschlägt, überprüfen Sie Folgendes:
- Der Tab Berechtigungen des Dienstkontos listet die Rolle „Workload Identity User“ für einen Principal auf, der mit Ihrem vollständigen Braze-Principal-ARN endet – kopiert aus einem BigQuery- oder Google-Cloud-Storage-Formular für Zugangsdaten im selben Workspace.
- Die IAM Service Account Credentials API ist aktiviert.
- Seit der Zugriffsgewährung sind einige Minuten vergangen.
Der Token-Austausch wird abgelehnt
Wenn Sie Workload Identity Federation verwenden und der Verbindungstest beim Token-Austausch über den Google Security Token Service fehlschlägt, überprüfen Sie Folgendes:
- Die Projektnummer, die Pool-ID und die Anbieter-ID, die Sie in Braze eingegeben haben, stimmen mit Ihrer Google-Cloud-Konfiguration überein.
- Die AWS-Konto-ID des Anbieters stimmt mit der Konto-ID im Braze-Principal-ARN überein.
- Wenn Sie eine Attributbedingung festgelegt haben, enthält sie Ihren vollständigen Principal-ARN genau so, wie Sie ihn kopiert haben.
- Wenn Sie angepasste zulässige Zielgruppen festgelegt haben, enthalten diese den vollständigen Ressourcennamen des Anbieters.
- Der Pool und der Anbieter sind aktiviert.
Wo SQL-Prüfungen ausgeführt werden
Führen Sie Validierungsprüfungen direkt im SQL-Workspace von BigQuery Studio aus, und zwar für dieselbe Tabelle oder View, die Ihre CDI-Integration verwendet. Weitere Informationen finden Sie in der Einführung in BigQuery Studio.
Verwandte Seiten
- Tabellen-Setup für erforderliche Spalten und die Formatierung von Payloads
- Best Practices für die Planung von Synchronisierungen und eine effiziente Nutzung von Datenpunkten
- Synchronisierungsprotokolle und Beobachtbarkeit für das Monitoring von Synchronisierungsläufen
- FAQ für häufige Fragen zu allen Quellen