Zum Inhalt springen

Cloud Data Ingestion für Databricks

Diese Seite enthält alles, was Sie brauchen, um Daten mit Cloud Data Ingestion (CDI) von Databricks mit Braze zu synchronisieren. Sie erfahren, welche Ressourcen Sie in Databricks erstellen, wie Sie in Braze die Quelle verbinden und eine Synchronisierung erstellen und wie die Quelltabelle für jeden Datentyp aussieht. Außerdem finden Sie Databricks-spezifische Hinweise zur Fehlerbehebung.

Übersicht über die Einrichtung

  1. Richten Sie in Ihrem Databricks-Konto die Tabellen oder Ansichten ein, die Sie mit Braze synchronisieren möchten.
  2. Erstellen Sie Zugangsdaten für Braze mit einer der unterstützten Authentifizierungsmethoden und gewähren Sie Zugriff auf die Databricks-Kataloge und -Schemas, die die zu synchronisierenden Daten enthalten.
  3. Erstellen Sie im Braze-Dashboard eine neue Quelle und Synchronisierung.
  4. Validieren Sie die Integration und starten Sie die Synchronisierung.

Schritt 1: Richten Sie Ihre Quelltabelle ein

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 vorhandene 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 Option für die Datendefinition auswählen.

Sie können Schema und Tabelle beliebig benennen, die Spaltennamen sollten jedoch den Definitionen in den folgenden Tabs entsprechen. Anstelle einer Tabelle können Sie auch eine View oder eine materialisierte View verwenden.

Optional können Sie einen neuen Katalog oder ein neues Schema für Ihre Quelltabelle einrichten:

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

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 STRING, STRUCT, or MAP
);
Feldname Typ Modus
UPDATED_AT TIMESTAMP REQUIRED
PAYLOAD STRING, STRUCT oder MAP 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 denen UPDATED_AT spä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 aus alias_name und alias_label, braze_id, email oder phone). 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 verwendeten external_id-Wert übereinstimmen.
    • ALIAS_NAME und ALIAS_LABEL – Diese beiden Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliasse mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_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 – Dies ist ein String oder Struct 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 einbeziehen. Payload-Beispiele finden Sie unter Tabellen-Setup.

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.

Um Events zu synchronisieren, 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. Wenn das Feld time fehlt, 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.

Um Kauf-Events zu synchronisieren, 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. Wenn das Feld time fehlt, 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,
  deleted BOOLEAN,
  payload STRING, STRUCT, or MAP
);
Feldname Typ Modus
UPDATED_AT TIMESTAMP REQUIRED
PAYLOAD STRING, STRUCT oder MAP REQUIRED
ID STRING REQUIRED
DELETED BOOLEAN NULLABLE

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 beispielsweise 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 STRING,
  deleted BOOLEAN
);
Feldname Typ Modus
UPDATED_AT TIMESTAMP REQUIRED
OBJECT_ID STRING REQUIRED
PAYLOAD STRING REQUIRED
DELETED BOOLEAN NULLABLE
  • UPDATED_AT – Der Zeitpunkt, zu dem diese Zeile in der Tabelle aktualisiert oder hinzugefügt wurde. Braze synchronisiert Zeilen, bei denen UPDATED_AT spä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 dem object_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 – Bei true lö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 auf false.

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 ein Konto mit den Feldern name und team_id sieht beispielsweise 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.

Verwenden Sie diese Synchronisierung, um Nutzer:innen mit Datenobjekt-Datensätzen zu verknüpfen, zum Beispiel um Nutzer:innen den Konten zuzuordnen, 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 STRING,
  deleted BOOLEAN
);
Feldname Typ Modus
UPDATED_AT TIMESTAMP REQUIRED
OBJECT_ID STRING REQUIRED
EXTERNAL_ID STRING NULLABLE
ALIAS_NAME STRING NULLABLE
ALIAS_LABEL STRING NULLABLE
EMAIL STRING NULLABLE
PHONE STRING NULLABLE
PAYLOAD STRING NULLABLE
DELETED BOOLEAN NULLABLE

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.

  • UPDATED_AT – Der Zeitpunkt, zu dem diese Zeile in der Tabelle aktualisiert oder hinzugefügt wurde. Braze synchronisiert Zeilen, bei denen UPDATED_AT spä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 dem object_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 – Bei true lö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 auf false.

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 Nutzerbeziehungen von Datenobjekten aus und wählen Sie dann einen Beziehungsnamen, zum Beispiel User (Account-User).

Verwenden Sie diese Synchronisierung, um Datenobjekt-Datensätze miteinander zu verknüpfen, zum Beispiel um Konten ihren übergeordneten Konten zuzuordnen. 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 STRING,
  deleted BOOLEAN
);
Feldname Typ Modus
UPDATED_AT TIMESTAMP REQUIRED
OBJECT_ID STRING REQUIRED
RELATED_OBJECT_ID STRING REQUIRED
PAYLOAD STRING NULLABLE
DELETED BOOLEAN NULLABLE

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 denen UPDATED_AT spä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 dem object_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 – Bei true lö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 auf false.

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 Beziehungen zwischen Datenobjekten aus und wählen Sie dann einen Beziehungsnamen, zum Beispiel Subaccount (Account-Account).

Canvas-Trigger ermöglichen Zero-Copy-Personalisierung. Informationen zum Setup 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 STRING, STRUCT, or MAP
);
Feldname Typ Erforderlich
UPDATED_AT TIMESTAMP Ja
PROPERTIES STRING, STRUCT oder MAP 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.
  • PROPERTIES ersetzt die Spalte PAYLOAD. 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, deren UPDATED_AT spä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_ID oder ALIAS_NAME und ALIAS_LABEL als 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 Wert external_id übereinstimmen.
    • ALIAS_NAME und ALIAS_LABEL – Diese Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliase mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_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.

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, deren UPDATED_AT nach 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 aus alias_name und alias_label oder braze_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 verwendeten external_id-Wert entsprechen.
    • ALIAS_NAME und ALIAS_LABEL – Diese beiden Spalten erstellen ein Nutzer-Alias-Objekt. alias_name sollte ein eindeutiger Bezeichner sein, und alias_label gibt den Typ des Alias an. Nutzer:innen können mehrere Aliasse mit unterschiedlichen Labels haben, aber nur einen alias_name pro alias_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.

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 beim Ausführen der Integration die richtigen Aktionen durchgeführt werden. Weitere Informationen finden Sie unter Nutzer:innen mit Cloud Data Ingestion löschen.

Schritt 2: Authentifizierung einrichten

Braze kann mit jeder der folgenden Authentifizierungsmethoden eine Verbindung zu Databricks herstellen:

Methode So authentifiziert Braze Was Sie in Braze eingeben
OAuth M2M (empfohlen) Braze authenticates as a Databricks service principal using OAuth machine-to-machine (M2M) authentication. Client ID and Client secret
Personal access token Braze authenticates with a token generated in your Databricks workspace. Access token

OAuth M2M

Braze verbindet sich mit Ihrem Databricks-Workspace als Service Principal über OAuth-Machine-to-Machine-Authentifizierung (M2M). Databricks empfiehlt OAuth M2M für unbeaufsichtigte Verbindungen wie Cloud Data Ingestion. Erstellen Sie einen neuen Service Principal für Braze und gewähren Sie ihm Zugriff auf Ihr SQL Warehouse und Ihre Quelltabellen. Braze benötigt für die Verbindung die folgenden Angaben:

  • Client-ID (auch Anwendungs-ID genannt) des Service Principals
  • Client Secret, mit dem sich Braze authentifiziert

Service Principal erstellen

  1. Wählen Sie in Ihrem Databricks-Workspace in der oberen Leiste Ihren Nutzernamen und dann Settings aus.
  2. Gehen Sie zu Identity and access und wählen Sie dann neben Service principals die Option Manage aus.
  3. Wählen Sie Add service principal > Add new aus.
  4. Geben Sie einen Namen ein, an dem Sie den Service Principal erkennen, zum Beispiel „Braze CDI“, und wählen Sie dann Add aus.
  5. Wählen Sie den erstellten Service Principal aus. Stellen Sie im Tab Configurations sicher, dass Databricks SQL access ausgewählt ist.

Client Secret generieren

  1. Wählen Sie auf der Seite des Service Principals den Tab Secrets und dann Generate secret aus.
  2. Geben Sie eine Lifetime für das Secret in Tagen ein. Databricks erlaubt eine maximale Lifetime von 730 Tagen.
  3. Wählen Sie Generate aus.
  4. Kopieren Sie die Werte für Secret und Client ID und wählen Sie dann Done aus.

Bewahren Sie Client-ID und Secret sicher auf, bis Sie sie beim Erstellen der Zugangsdaten im Braze-Dashboard eingeben. Databricks zeigt das Secret nur einmal an.

Zugriff auf das SQL Warehouse gewähren

Braze benötigt die Berechtigung, Abfragen in Ihrem SQL Warehouse auszuführen, aber keinen Admin-Zugriff auf den Workspace.

  1. Wählen Sie in der Seitenleiste SQL Warehouses und dann das Warehouse aus, das Braze verwenden soll.
  2. Wählen Sie Permissions aus.
  3. Suchen Sie nach dem erstellten Service Principal und wählen Sie ihn aus.
  4. Wählen Sie im Dropdown-Menü für Berechtigungen Can use und dann Add aus.

Zugriff auf die Quelltabellen gewähren

Gewähren Sie dem Service Principal Lesezugriff auf den Katalog, das Schema und die Tabellen, die Sie in Schritt 1 eingerichtet haben. Verwenden Sie die Anwendungs-ID des Service Principals (derselbe Wert wie die Client-ID) als Empfänger der Berechtigung.

GRANT USE CATALOG ON CATALOG `BRAZE-CLOUD-PRODUCTION` TO `APPLICATION_ID`;
GRANT USE SCHEMA ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
GRANT SELECT ON TABLE `BRAZE-CLOUD-PRODUCTION`.INGESTION.USERS_ATTRIBUTES_SYNC TO `APPLICATION_ID`;

Ersetzen Sie APPLICATION_ID durch die Anwendungs-ID Ihres Service Principals. Passen Sie die übrigen Namen nach Bedarf an, die Berechtigungen sollten jedoch dem obigen Beispiel entsprechen.

Client Secret aktualisieren

Braze speichert ein Client Secret pro Zugangsdaten-Eintrag. Wenn Sie es aktualisieren, verwenden alle Quellen und Synchronisierungen, die diese Zugangsdaten nutzen, das neue Secret. So ersetzen Sie das Secret:

  1. Generieren Sie in Databricks ein neues Secret für den Service Principal, indem Sie die Schritte unter Client Secret generieren befolgen. Behalten Sie das alte Secret bis Schritt 6.
  2. Gehen Sie im Braze-Dashboard zu Dateneinstellungen > Cloud Data Ingestion > Zugangsdaten und wählen Sie dann Ihre OAuth-M2M-Zugangsdaten aus. Im Abschnitt Verwendet von werden alle Quellen und Synchronisierungen aufgeführt, die diese Zugangsdaten nutzen.
  3. Pausieren Sie die Synchronisierungen, die diese Zugangsdaten verwenden, oder planen Sie das Update für einen Zeitpunkt, zu dem keine davon laufen soll. So verhindern Sie, dass eine Synchronisierung startet, während Sie die Zugangsdaten aktualisieren.
  4. Wählen Sie Zugangsdaten bearbeiten aus, geben Sie das neue Client Secret ein und wählen Sie dann Speichern aus. Die Änderung gilt für alle Quellen und Synchronisierungen, die diese Zugangsdaten verwenden.
  5. Setzen Sie alle pausierten Synchronisierungen fort.
  6. Nachdem Braze das neue Secret gespeichert hat, löschen Sie das alte Secret in Databricks.

Personal access token

Braze authentifiziert sich mit einem persönlichen Zugriffstoken, das in Ihrem Databricks-Workspace generiert wird. Bestehende Zugangsdaten mit persönlichem Zugriffstoken funktionieren weiterhin, und Sie müssen sie nicht migrieren. Persönliche Zugriffstoken laufen jedoch häufig nach einem Zeitplan ab, den Ihr Workspace-Admin festlegt, und Synchronisierungen werden gestoppt, sobald das Token abläuft. Um eine bestehende Quelle auf OAuth M2M umzustellen, erstellen Sie OAuth-M2M-Zugangsdaten und wählen Sie diese beim Bearbeiten der Quelle aus.

So erstellen Sie ein persönliches Zugriffstoken:

  1. Wählen Sie in Ihrem Databricks-Workspace in der oberen Leiste Ihren Databricks-Nutzernamen aus und wählen Sie dann im Dropdown-Menü User Settings aus.
  2. Wählen Sie im Tab Access tokens die Option Generate new token aus.
  3. Geben Sie einen Kommentar ein, anhand dessen Sie dieses Token identifizieren können, zum Beispiel „Braze CDI“, und setzen Sie die Lifetime des Tokens auf unbegrenzt, indem Sie das Feld Lifetime (days) leer lassen.
  4. Wählen Sie Generate aus.
  5. Kopieren Sie das angezeigte Token und wählen Sie dann Done aus.

Bewahren Sie das Token an einem sicheren Ort auf, bis Sie es beim Erstellen der Zugangsdaten im Braze-Dashboard eingeben müssen.

Schritt 3: Zugriff für Braze-IPs zulassen

Wenn Sie Netzwerkrichtlinien verwenden, müssen Sie Braze Netzwerkzugriff auf Ihre Databricks-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.191
  • 34.206.23.173
  • 50.16.249.9
  • 52.4.160.214
  • 54.87.8.34
  • 54.156.35.251
  • 52.54.89.238
  • 18.205.178.15

Für die Instanz US-08 sind dies die relevanten IP-Adressen:

  • 52.151.246.51
  • 52.170.163.182
  • 40.76.166.157
  • 40.76.166.170
  • 40.76.166.167
  • 40.76.166.161
  • 40.76.166.156
  • 40.76.166.166
  • 40.76.166.160
  • 40.88.51.74
  • 52.154.67.17
  • 40.76.166.80
  • 40.76.166.84
  • 40.76.166.85
  • 40.76.166.81
  • 40.76.166.71
  • 40.76.166.144
  • 40.76.166.145

Für die Instanz US-10 sind dies die relevanten IP-Adressen:

  • 100.25.232.164
  • 35.168.86.179
  • 52.7.44.117
  • 3.92.153.18
  • 35.172.3.129
  • 50.19.162.19

Für die Instanzen EU-01 und EU-02 sind dies die relevanten IP-Adressen:

  • 52.58.142.242
  • 52.29.193.121
  • 35.158.29.228
  • 18.157.135.97
  • 3.123.166.46
  • 3.64.27.36
  • 3.65.88.25
  • 3.68.144.188
  • 3.70.107.88

Für die Instanz AU-01 sind dies die relevanten IP-Adressen:

  • 13.210.1.145
  • 13.211.70.159
  • 13.238.45.54
  • 52.65.73.167
  • 54.153.242.239
  • 54.206.45.213

Für die Instanz ID-01 sind dies die relevanten IP-Adressen:

  • 108.136.157.246
  • 108.137.30.207
  • 16.78.128.71
  • 16.78.14.134
  • 16.78.162.208
  • 43.218.73.35

Für die Instanz JP-01 sind dies die relevanten IP-Adressen:

  • 13.159.155.212
  • 54.199.221.241
  • 13.192.23.16
  • 54.250.120.139
  • 18.181.114.232
  • 3.114.38.100

Für die Instanz KR-01 sind dies die relevanten IP-Adressen:

  • 43.200.215.4
  • 52.79.67.175
  • 52.79.113.60
  • 3.34.212.92
  • 54.116.134.231
  • 3.37.197.225

Schritt 4: 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 Databricks aus.

Schritt 4.1: Databricks-Verbindungsinformationen und Quelltabelle hinzufügen

Geben Sie einen Namen für Ihre Quelle ein und anschließend Ihre Databricks-Zugangsdaten und -Konfiguration:

  • Geben Sie unter Name der Zugangsdaten eine Bezeichnung ein, anhand derer Sie diese Zugangsdaten in Braze erkennen.
  • Wählen Sie unter Authentifizierungsmethode die Methode aus, die Sie in Schritt 2 eingerichtet haben, und geben Sie die zugehörigen Zugangsdaten ein. Geben Sie für OAuth M2M Folgendes ein: Client ID and Client secret. Geben Sie für Personal access token Folgendes ein: Access token.

Fahren Sie dann mit dem nächsten Schritt fort.

Schritt 4.2: Verbindung testen und mit der Quelle verbinden

Wählen Sie als Nächstes Verbindung testen aus. Nach erfolgreichem Test schließen Sie die übrigen Einstellungen ab und klicken auf Mit Quelle verbinden. Schlägt die Verbindung fehl, wird eine Fehlermeldung angezeigt, die Ihnen bei der Fehlerbehebung hilft.

Schritt 5: Eine neue Synchronisierung im Braze-Dashboard erstellen

Gehen Sie zu Dateneinstellungen > Cloud-Datenaufnahme > Synchronisierungen und wählen Sie Datensynchronisierung erstellen.

Synchronisierungsdetails konfigurieren und Daten definieren

Geben Sie einen Namen für Ihre Synchronisierung ein. Wählen Sie anschließend eine aktive Quelle und einen Synchronisierungsdatentyp aus. Wählen Sie dann einen Synchronisierungsmodus aus und definieren Sie Ihre Daten. Wählen Sie danach Vorschau und Validierung.

Nach erfolgreicher Validierung wird eine Vorschau der Daten angezeigt. Wählen Sie Weiter: Benachrichtigungen, um fortzufahren. Schlägt die Validierung fehl, erscheint eine Fehlermeldung, die Ihnen bei der Fehlerbehebung hilft.

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.

Synchronisierung ausführen

Nach der Aktivierung läuft Ihre Synchronisierung nach dem Zeitplan, 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. Diese Ausführung wirkt sich nicht auf künftige, regelmäßig geplante Synchronisierungen aus. 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 bestehende Zugangsdaten wiederverwenden, sofern Sie sich mit demselben Databricks-Konto verbinden.

Wenn Sie dieselbe Nutzer:in für mehrere Integrationen verwenden, können Sie diese Nutzer:in im Braze-Dashboard erst löschen, wenn sie aus allen aktiven Synchronisierungen entfernt wurde.

Databricks als verbundene Quelle verwenden

Eine verbundene Quelle ist eine Zero-Copy-Alternative zur Synchronisierung von Daten in Braze. Braze fragt Ihre Databricks-Instanz direkt ab, um CDI-Segmente zu erstellen, ohne die zugrunde liegenden Daten zu kopieren. Informationen zu Konzepten, Einschränkungen und Kosten finden Sie unter Verbundene Quellen.

Schritt 1: Authentifizierung einrichten und Berechtigungen erteilen

Richten Sie Zugangsdaten für Braze mit einer der Methoden aus Schritt 2: Authentifizierung einrichten ein. Unabhängig von der gewählten Methode verwendet Braze diese Zugangsdaten, um die Liste der in Ihren CDI-Segmenterweiterungen verfügbaren Tabellen zu erstellen und Quelltabellen abzufragen, 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 in einem Schema gewähren oder Berechtigungen nur 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.

  • OAuth M2M: Gewähren Sie dem Service Principal Zugriff auf das Schema, das für die verbundene Quelle verwendet wird, einschließlich CREATE TABLE. Verwenden Sie die Anwendungs-ID des Service Principals (derselbe Wert wie die Client-ID) als Berechtigungsempfänger.

      GRANT USE CATALOG ON CATALOG `BRAZE-CLOUD-PRODUCTION` TO `APPLICATION_ID`;
      GRANT USE SCHEMA, CREATE TABLE ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
      GRANT SELECT ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
    

    Ersetzen Sie APPLICATION_ID durch die Anwendungs-ID Ihres Service Principals.

  • Persönliches Zugriffstoken: Stellen Sie sicher, dass das Dienstkonto über CREATE TABLE-Berechtigungen für das Schema verfügt, das für die verbundene Quelle verwendet wird.

Die Einrichtung des Netzwerkzugriffs entspricht Schritt 3.

Schritt 2: Verbundene Quelle in Braze erstellen

Gehen Sie zu Dateneinstellungen > Cloud-Datenaufnahme > Verbundene Quellen, wählen Sie Datenquelle hinzufügen und dann Databricks aus.

Geben Sie unter Quelle einrichten Folgendes ein:

  • Zugangsdaten: Name der Zugangsdaten, Authentifizierungsmethode, Hostname, HTTP-Pfad sowie die Felder für Ihre Authentifizierungsmethode. Geben Sie für OAuth M2M Folgendes ein: Client ID and Client secret. Geben Sie für Personal access token Folgendes ein: Access token.
  • Konfiguration: Katalog und Schema

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 automatisch alle Abfragen ab, die die maximale Laufzeit überschreiten. Die maximal zulässige Laufzeit beträgt 60 Minuten; eine kürzere Laufzeit senkt die Kosten in Ihrem Databricks-Konto. Diese Einstellung gilt für Abfragen, die über diese Quelle ausgeführt werden, einschließlich Synchronisierungen und CDI-Segmenterweiterungen, die sie verwenden.

Wählen Sie Verbindung testen, um zu überprüfen, ob die Liste der für die Nutzer:in sichtbaren Tabellen Ihren Erwartungen entspricht, und wählen Sie dann Fertig. Ihre verbundene Quelle ist nun erstellt und kann in CDI-Segmenterweiterungen verwendet werden.

Sie können mehrere verbundene Quellen mit Braze einrichten, aber jede Quelle sollte so konfiguriert sein, dass sie ein anderes Schema verbindet. Wenn Sie zusätzliche Quellen erstellen, können Sie vorhandene Zugangsdaten wiederverwenden, sofern Sie sich mit demselben Databricks-Konto verbinden.

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 Databricks, 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,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

Weitere Hinweise zur Optimierung finden Sie unter Best Practices für Cloud Data Ingestion.

Fehlerbehebung

Verbindungstest läuft langsam

Der Verbindungstest wird in Ihrem Data Warehouse ausgeführt. Eine Erhöhung der Warehouse-Kapazität kann daher die Geschwindigkeit verbessern. Bei Databricks kann es zwei bis fünf Minuten Aufwärmzeit geben, wenn Braze sich mit Classic- und Pro-SQL-Instanzen verbindet. Das führt zu Verzögerungen bei der Einrichtung und beim Testen der Verbindung sowie zu Beginn geplanter Synchronisierungen. Eine serverlose SQL-Instanz minimiert die Aufwärmzeit und verbessert den Abfragedurchsatz, kann aber etwas höhere Integrationskosten verursachen.

Befehl fehlgeschlagen, weil das Warehouse gestoppt wurde

Wenn Sie diesen Fehler erhalten, stellen Sie sicher, dass das Databricks-Warehouse läuft.

Service: Amazon S3; Status Code: 403; Error Code: 403 Forbidden

Wenn Sie diesen Fehler erhalten, lesen Sie Databricks: Forbidden-Fehler beim Zugriff auf S3-Daten.

Wo SQL-Prüfungen ausgeführt werden

Führen Sie Validierungsprüfungen direkt im Databricks-SQL-Editor auf einem SQL-Warehouse aus, und zwar für dieselbe Tabelle oder View, die Ihre CDI-Integration verwendet. Weitere Informationen finden Sie unter Databricks-SQL-Editor.

New Stuff!