Katalogdaten synchronisieren und löschen

Diese Seite beschreibt, wie Sie Katalogdaten synchronisieren können.

Schritt 1: Neuen Katalog erstellen

Bevor Sie eine neue Cloud-Datenaufnahme-Integration (CDI) für Kataloge erstellen, müssen Sie einen neuen Katalog erstellen oder einen bestehenden Katalog identifizieren, den Sie für die Integration verwenden möchten. Es gibt mehrere Möglichkeiten, einen neuen Katalog zu erstellen, und alle funktionieren für die CDI-Integration:

• Laden Sie eine CSV-Datei hoch
• Erstellen Sie einen Katalog im Braze-Dashboard oder während der CDI-Einrichtung.
• Erstellen Sie einen Katalog über den Endpunkt „Katalog erstellen“

Alle Änderungen am Katalogschema (z. B. das Hinzufügen neuer Felder oder das Ändern des Feldtyps) müssen über das Katalog-Dashboard vorgenommen werden, bevor aktualisierte Daten über CDI synchronisiert werden. Wir empfehlen, diese Aktualisierungen durchzuführen, wenn die Synchronisierung pausiert ist oder nicht planmäßig ausgeführt wird, um Konflikte zwischen Ihren Data-Warehouse-Daten und dem Schema in Braze zu vermeiden.

Schritt 2: Cloud-Datenaufnahme mit Katalogdaten integrieren

Die Einrichtung einer Katalogsynchronisierung folgt weitgehend dem Prozess für Nutzer:innendaten-CDI-Integrationen.

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric
• s3

1. Richten Sie eine Quelltabelle in Snowflake ein. Sie können die Namen im folgenden Beispiel verwenden oder eigene Datenbank-, Schema- und Tabellennamen wählen. Anstelle einer Tabelle können Sie auch eine View oder eine Materialized View verwenden.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   
    CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
    CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
    CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
         UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
         --ID of the catalog item to be created or updated
         ID VARCHAR(16777216) NOT NULL,
         --Catalog fields and values that should be added or updated
         PAYLOAD VARCHAR(16777216) NOT NULL,
         --The catalog item associated with this ID should be deleted
         DELETED BOOLEAN
    );
   
   

2. Richten Sie eine Rolle, ein Warehouse und eine/n Nutzer:in ein und vergeben Sie die entsprechenden Berechtigungen. Falls Sie bereits Zugangsdaten von einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden – stellen Sie jedoch sicher, dass der Zugriff auf die Katalogquelltabelle erweitert wird.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   
    CREATE ROLE BRAZE_INGESTION_ROLE;
   
    GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
    GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
    GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC TO ROLE BRAZE_INGESTION_ROLE;
   
    CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
    GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;
   
    CREATE USER BRAZE_INGESTION_USER;
    GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;
   
   

3. Falls Ihr Snowflake-Konto Netzwerkrichtlinien hat, setzen Sie die Braze-IPs auf die Allowlist, damit der CDI-Dienst eine Verbindung herstellen kann. Eine Liste der IPs finden Sie unter Cloud-Datenaufnahme.
4. Navigieren Sie im Braze-Dashboard zu Technologie-Partner > Snowflake und erstellen Sie eine neue Synchronisierung.
5. Geben Sie die Verbindungsdetails ein (oder verwenden Sie vorhandene Zugangsdaten) sowie die Quelltabelle.
6. Fahren Sie mit Schritt 2 des Einrichtungsablaufs fort, wählen Sie den Synchronisierungstyp „Catalogs“ und geben Sie den Integrationsnamen und den Zeitplan ein. Beachten Sie, dass der Name der Integration exakt mit dem Namen des zuvor erstellten Katalogs übereinstimmen muss.
7. Wählen Sie eine Synchronisierungsfrequenz und fahren Sie mit dem nächsten Schritt fort.
8. Fügen Sie den im Dashboard angezeigten Public Key dem/der Nutzer:in hinzu, den/die Sie für die Verbindung von Braze mit Snowflake erstellt haben. Um diesen Schritt abzuschließen, benötigen Sie eine Person mit SECURITYADMIN-Zugriff oder höher in Snowflake.
9. Wählen Sie Verbindung testen, um sicherzustellen, dass alles wie erwartet funktioniert.
10. Speichern Sie die Synchronisierung und verwenden Sie die synchronisierten Katalogdaten für all Ihre Personalisierungs-Anwendungsfälle.

1. Richten Sie eine Quelltabelle in Redshift ein. Sie können die Namen im folgenden Beispiel verwenden oder eigene Datenbank-, Schema- und Tabellennamen wählen. Anstelle einer Tabelle können Sie auch eine View oder eine Materialized View verwenden.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   
    CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
    CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
    CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
       updated_at timestamptz default sysdate not null,
       --ID of the catalog item to be created or updated
       id varchar not null,
       --Catalog fields and values that should be added or updated
       payload varchar(max),
       --The catalog item associated with this ID should be deleted
       deleted boolean
    )
   
   

2. Richten Sie eine/n Nutzer:in ein und vergeben Sie die entsprechenden Berechtigungen. Falls Sie bereits Zugangsdaten von einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden – stellen Sie jedoch sicher, dass der Zugriff auf die Katalogquelltabelle erweitert wird.

   
   1
   2
   3
   
    CREATE USER braze_user PASSWORD '{password}';
    GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
    GRANT SELECT ON TABLE CATALOGS_SYNC TO braze_user;
   
   

3. Falls Sie eine Firewall oder andere Netzwerkrichtlinien haben, müssen Sie Braze Netzwerkzugriff auf Ihre Redshift-Instanz gewähren. Erlauben Sie den Zugriff von den folgenden IPs entsprechend der Region Ihres Braze-Dashboards. Eine Liste der IPs finden Sie unter Cloud-Datenaufnahme.

1. Optional können Sie ein neues Projekt oder Dataset für Ihre Quelltabelle einrichten.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Erstellen Sie eine oder mehrere Tabellen für Ihre CDI-Integration mit den folgenden Feldern:

1
2
3
4
5
6
7

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

2. Richten Sie eine/n Nutzer:in ein und vergeben Sie die entsprechenden Berechtigungen. Falls Sie bereits Zugangsdaten von einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden – stellen Sie jedoch sicher, dass der Zugriff auf die Katalogquelltabelle erweitert wird. Das Dienstkonto sollte die folgenden Berechtigungen haben:
   • BigQuery Connection User: Ermöglicht es Braze, Verbindungen herzustellen.
   • BigQuery User: Ermöglicht Braze den Zugriff zum Ausführen von Abfragen, Lesen von Dataset-Metadaten und Auflisten von Tabellen.
   • BigQuery Data Viewer: Ermöglicht Braze den Zugriff zum Anzeigen von Datasets und deren Inhalten.
   • BigQuery Job User: Ermöglicht Braze den Zugriff zum Ausführen von Jobs.
     
     Nachdem Sie das Dienstkonto erstellt und die Berechtigungen vergeben haben, richten Sie ein, wie sich Braze als Dienstkonto authentifiziert. Verwenden Sie Workload Identity Federation, damit Sie keinen Schlüssel erstellen müssen, oder generieren Sie einen JSON-Schlüssel. Weitere Informationen zu JSON-Schlüsseln finden Sie unter Keys create and delete. Falls Sie einen JSON-Schlüssel generieren, laden Sie ihn später im Braze-Dashboard hoch.

3. Falls Sie Netzwerkrichtlinien eingerichtet haben, müssen Sie Braze Netzwerkzugriff auf Ihre BigQuery-Instanz gewähren. Eine Liste der IPs finden Sie unter Cloud-Datenaufnahme.

1. Richten Sie eine Quelltabelle in Databricks ein. Sie können die Namen im folgenden Beispiel verwenden oder eigene Katalog-, Schema- und Tabellennamen wählen. Anstelle einer Tabelle können Sie auch eine View oder eine Materialized View verwenden.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

1
2
3
4
5
6
7

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, or MAP	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	NULLABLE

2. Erstellen Sie Zugangsdaten für Braze. Braze empfiehlt OAuth Machine-to-Machine (M2M) mit einem Dienstprinzipal, Sie können aber auch ein persönliches Zugriffstoken verwenden. Falls Sie bereits Zugangsdaten von einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden – stellen Sie jedoch sicher, dass der Zugriff auf die Katalogquelltabelle erweitert wird.

OAuth M2M: Erstellen Sie einen Dienstprinzipal, generieren Sie ein Client-Secret, gewähren Sie dem Dienstprinzipal die Berechtigung Can use für Ihr SQL Warehouse und gewähren Sie SELECT auf die Katalogquelltabelle. Die Schritte finden Sie unter Zugangsdaten für Braze erstellen.

Persönliches Zugriffstoken:

• a. Wählen Sie Ihren Databricks-Benutzernamen und dann User Settings aus dem Dropdown-Menü.
• b. Wählen Sie auf dem Tab Access tokens die Option Generate new token.
• c. Geben Sie einen Kommentar ein, der Ihnen hilft, dieses Token zu identifizieren, z. B. „Braze CDI“.
• d. Ändern Sie die Lebensdauer des Tokens auf unbegrenzt, indem Sie das Feld Lifetime (days) leer lassen. Wählen Sie Generate.
• e. Kopieren Sie das angezeigte Token und wählen Sie dann Done.
• f. Bewahren Sie das Token an einem sicheren Ort auf, bis Sie es im Schritt zur Erstellung der Zugangsdaten im Braze-Dashboard eingeben müssen.

3. Falls Sie Netzwerkrichtlinien eingerichtet haben, müssen Sie Braze Netzwerkzugriff auf Ihre Databricks-Instanz gewähren. Eine Liste der IPs finden Sie auf der Seite Cloud-Datenaufnahme.

Erstellen Sie eine oder mehrere Tabellen für Ihre CDI-Integration mit den folgenden Feldern:

1
2
3
4
5
6
7
8

CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PAYLOAD VARCHAR NOT NULL,
  ID VARCHAR NOT NULL,
  DELETED BIT
)
GO

2. Richten Sie einen Dienstprinzipal ein und vergeben Sie die entsprechenden Berechtigungen. Falls Sie bereits Zugangsdaten von einer bestehenden Synchronisierung haben, können Sie diese wiederverwenden – stellen Sie jedoch sicher, dass der Zugriff auf die Katalogquelltabelle erweitert wird. Weitere Informationen zum Erstellen eines neuen Dienstprinzipals und von Zugangsdaten finden Sie auf der Seite Cloud-Datenaufnahme.

3. Falls Sie Netzwerkrichtlinien eingerichtet haben, müssen Sie Braze Netzwerkzugriff auf Ihre Microsoft Fabric-Instanz gewähren. Eine Liste der IPs finden Sie unter Cloud-Datenaufnahme.

Erstellen Sie Quelldateien in S3 im JSON- oder CSV-Format. Jede Datei muss die folgenden Felder enthalten:

Feld	Erforderlich?	Beschreibung
ID	Ja	Die ID des Katalogartikels, der erstellt oder aktualisiert werden soll.
PAYLOAD	Ja	Ein JSON-String der Felder, die mit dem Katalogartikel in Braze synchronisiert werden sollen.
DELETED	Optional	Bei true wird der entsprechende Katalogartikel aus dem Katalog entfernt.
UPDATED_AT	Nicht unterstützt	Dateispeicher unterstützt keine UPDATED_AT-Spalten.

Hinweis

Dateinamen müssen den AWS-Regeln entsprechen und eindeutig sein. Fügen Sie Zeitstempel hinzu, um die Eindeutigkeit sicherzustellen.

Die vollständige S3-Einrichtung erfordert einen S3-Bucket, eine Amazon SQS-Warteschlange sowie eine AWS IAM-Rolle und -Richtlinie. Braze verarbeitet nur Dateien, die nach dem Erstellen der Synchronisierung hochgeladen werden. Laden Sie daher vorhandene Dateien erneut hoch, die Sie aufnehmen möchten.

Den vollständigen S3-Einrichtungsablauf finden Sie unter Dateispeicher-Integrationen, insbesondere:

• Cloud-Datenaufnahme in AWS einrichten
• Cloud-Datenaufnahme in Braze einrichten
• Fehlerbehebung

Bei häufigen AWS-seitigen Benachrichtigungs- und Berechtigungsproblemen lesen Sie Granting permissions to publish event notification messages to a destination.

Die folgenden Beispiele zeigen gültige JSON- und CSV-Formate für die Synchronisierung von Katalogdaten aus dem Dateispeicher.

• json catalogs
• csv catalogs with delete
• csv catalogs without delete

{"id":"85","payload":"{\"product_name\":\"Product 85\",\"price\":85.85}"}
{"id":"86","payload":"{\"product_name\":\"Product 86\",\"price\":86.86}"}
{"id":"1","payload":"{\"product_name\":\"Product 1\",\"price\":1.01}","deleted":true}

Wichtig

Jede Zeile in Ihrer Quelldatei muss gültiges JSON enthalten, andernfalls wird die Datei übersprungen.

1
2
3
4

ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
86,"{""product_name"": ""Product 86"", ""price"": 86.86}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

1
2
3

ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"

Weitere Dateibeispiele finden Sie unter Dateispeicher-Integrationen.

So funktioniert die Integration

Hinweis

Die Synchronisierungsansichten in diesem Abschnitt gelten nur für Data-Warehouse-Integrationen. Bei S3-Dateispeicher verarbeitet Braze neue Dateien, sobald sie in Ihren Bucket hochgeladen werden. Weitere Informationen finden Sie unter Dateispeicher-Integrationen.

Bei jeder Synchronisierung ruft Braze alle Zeilen ab, bei denen UPDATED_AT später als der zuletzt synchronisierte Wert ist. Zeilen am exakten Grenz-Zeitstempel können erneut synchronisiert werden, wenn neue Zeilen denselben Zeitstempel aufweisen. Wir empfehlen, in Ihrem Data Warehouse eine Ansicht (View) aus Ihren Katalogdaten zu erstellen, um eine Quelltabelle einzurichten, die bei jeder Synchronisierung vollständig aktualisiert wird. Mit Ansichten müssen Sie die Abfrage nicht jedes Mal neu schreiben.

Wenn Sie beispielsweise eine Tabelle mit Produktdaten (product_catalog_1) mit product_id und drei zusätzlichen Attributen haben, könnten Sie die folgende Ansicht synchronisieren:

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE VIEW BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    product_id as id,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    )as PAYLOAD FROM "product_catalog_1";

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    Product_id as id,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    ) as PAYLOAD FROM "product_catalog_1";

1
2
3
4
5
6
7
8
9
10
11

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`);

1
2
3
4
5
6
7
8
9
10
11

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`);

1
2
3
4
5
6
7

CREATE VIEW [braze].[user_update_example]
AS SELECT
    id as ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[product_catalog] ;

• Die von der Integration abgerufenen Daten werden verwendet, um Artikel im Zielkatalog basierend auf der angegebenen id zu erstellen oder zu aktualisieren.
• Wenn DELETED auf true gesetzt ist, wird der entsprechende Katalogartikel gelöscht.
• Die Synchronisierung protokolliert keine Datenpunkte, aber alle synchronisierten Daten werden auf Ihre gesamte Katalognutzung angerechnet. Diese Nutzung wird anhand der insgesamt gespeicherten Daten gemessen, sodass Sie sich keine Gedanken darüber machen müssen, nur geänderte Daten zu synchronisieren.