Integrationen in die Dateiablage

Auf dieser Seite erfahren Sie, wie Sie die Cloud-Datenaufnahme einrichten, um Daten von Amazon S3, Google Cloud Storage oder Azure Blob Storage mit Braze zu synchronisieren.

So funktioniert es

Sie können Cloud Data Ingestion (CDI) verwenden, um einen oder mehrere Storage-Buckets in Ihrem Cloud-Konto direkt mit Braze zu integrieren. Wenn Sie eine neue Datei zu einem Bucket hinzufügen, veröffentlicht Ihr Cloud-Anbieter eine Benachrichtigung, und Braze Cloud Data Ingestion synchronisiert die Daten.

Der Benachrichtigungsmechanismus hängt von Ihrem Anbieter ab:

• Amazon S3: Wenn neue Dateien in S3 veröffentlicht werden, wird eine Nachricht an eine Amazon Simple Queue Service (SQS)-Warteschlange gesendet, und Braze verarbeitet diese Nachricht, um die neue Datei aufzunehmen.
• Google Cloud Storage (GCS): Wenn neue Dateien im Bucket finalisiert werden, veröffentlicht GCS eine OBJECT_FINALIZE-Benachrichtigung an ein Pub/Sub-Topic. Braze verarbeitet diese Benachrichtigungen über ein Pub/Sub-Abo, um die neue Datei aufzunehmen.
• Azure Blob Storage: Wenn neue Dateien im Container erstellt werden, veröffentlicht ein Event-Abo in Azure Event Grid ein Blob Created-Ereignis an eine Azure Storage-Warteschlange. Braze liest diese Nachrichten aus der Warteschlange, um die neue Datei aufzunehmen.

Cloud Data Ingestion unterstützt Folgendes:

• JSON-Dateien
• CSV-Dateien
• Parquet-Dateien
• Attribut-, angepasste Event-, Kauf-Event-, Nutzer:innen-Lösch- und Katalogdaten

Cloud-Datenaufnahme einrichten

Die Einrichtungsschritte hängen von Ihrem Dateispeicheranbieter ab. Wählen Sie den Tab für Ihren Anbieter und führen Sie dann die gemeinsame Konfiguration in den folgenden Abschnitten durch.

• amazon s3
• google cloud storage
• azure blob

Die Integration erfordert die folgenden Ressourcen:

• S3-Bucket für die Datenspeicherung
• SQS-Warteschlange für Benachrichtigungen über neue Dateien
• IAM-Rolle für den Braze-Zugriff

AWS-Definitionen

Begriff	Definition
Amazon Resource Name (ARN)	Der ARN ist ein eindeutiger Bezeichner für AWS-Ressourcen.
Identity and Access Management (IAM)	IAM ist ein Webdienst, mit dem Sie den Zugriff auf AWS-Ressourcen sicher steuern können. In diesem Tutorial erstellen Sie eine IAM-Richtlinie und weisen sie einer IAM-Rolle zu, um Ihren S3-Bucket mit der Cloud-Datenaufnahme von Braze zu integrieren.
Amazon Simple Queue Service (SQS)	SQS ist eine gehostete Warteschlange, mit der Sie verteilte Software-Systeme und Komponenten integrieren können.

Cloud-Datenaufnahme in AWS einrichten

Schritt 1: Quell-Bucket erstellen

Erstellen Sie einen S3-Allzweck-Bucket mit Standardeinstellungen in Ihrem AWS-Konto. S3-Buckets können über mehrere Synchronisierungen hinweg wiederverwendet werden, solange der Ordner eindeutig ist.

Die Standardeinstellungen sind:

• ACLs deaktiviert
• Gesamten öffentlichen Zugriff blockieren
• Bucket-Versionierung deaktivieren
• SSE-S3-Verschlüsselung
  • SSE-S3 ist der einzige unterstützte serverseitige Verschlüsselungstyp. Amazon-KMS-Verschlüsselung wird nicht unterstützt.

Notieren Sie sich die Region, in der Sie den Bucket erstellt haben. Sie werden im nächsten Schritt eine SQS-Warteschlange in derselben Region erstellen.

Schritt 2: SQS-Warteschlange erstellen

Erstellen Sie eine SQS-Warteschlange, um nachzuverfolgen, wann Objekte zum erstellten Bucket hinzugefügt werden. Verwenden Sie vorerst die Standardkonfigurationseinstellungen.

Eine SQS-Warteschlange muss global eindeutig sein (es kann beispielsweise nur eine für eine CDI-Synchronisierung verwendet werden und sie kann nicht in einem anderen Workspace wiederverwendet werden).

Wichtig

Stellen Sie sicher, dass Sie diese SQS in derselben Region erstellen, in der Sie den Bucket erstellt haben.

Notieren Sie sich den ARN und die URL der SQS-Warteschlange. Sie werden sie während dieser Konfiguration häufig benötigen.

Schritt 3: Zugriffsrichtlinie einrichten

Um die Zugriffsrichtlinie einzurichten, wählen Sie Advanced options.

Fügen Sie die folgende Anweisung an die Zugriffsrichtlinie der Warteschlange an und ersetzen Sie dabei YOUR-BUCKET-NAME-HERE durch Ihren Bucket-Namen, YOUR-SQS-ARN durch Ihren SQS-Warteschlangen-ARN und YOUR-AWS-ACCOUNT-ID durch Ihre AWS-Konto-ID:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "Sid": "braze-cdi-s3-sqs-publish",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "YOUR-SQS-ARN",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "YOUR-AWS-ACCOUNT-ID"
    },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
    }
  }
}

Schritt 4: Event-Benachrichtigung zum S3-Bucket hinzufügen

1. Gehen Sie im in Schritt 1 erstellten Bucket zu Properties > Event notifications.
2. Geben Sie der Konfiguration einen Namen. Optional können Sie ein Präfix oder Suffix angeben, wenn nur eine Teilmenge der Dateien von Braze aufgenommen werden soll.
3. Wählen Sie unter Destination die Option SQS queue und geben Sie den ARN der in Schritt 2 erstellten SQS an.

Hinweis

Wenn Sie Ihre Dateien in den Stammordner eines S3-Buckets hochladen und dann einige der Dateien in einen bestimmten Ordner im Bucket verschieben, kann ein unerwarteter Fehler auftreten. Stattdessen können Sie die Event-Benachrichtigungen so konfigurieren, dass sie nur für Dateien im Präfix gesendet werden, keine Dateien außerhalb dieses Präfixes im S3-Bucket ablegen oder die Integration ohne Präfix aktualisieren, wodurch dann alle Dateien aufgenommen werden.

Schritt 5: IAM-Richtlinie erstellen

Erstellen Sie eine IAM-Richtlinie, um Braze die Interaktion mit Ihrem Quell-Bucket zu ermöglichen. Melden Sie sich zunächst als Kontoadministrator:in bei der AWS-Managementkonsole an.

1. Gehen Sie zum IAM-Bereich der AWS-Konsole, wählen Sie Policies in der Navigationsleiste und dann Create Policy.
   
   
   
   

2. Öffnen Sie den Tab JSON und geben Sie den folgenden Code-Snippet in den Abschnitt Policy Document ein. Ersetzen Sie dabei YOUR-BUCKET-NAME-HERE durch Ihren Bucket-Namen und YOUR-SQS-ARN-HERE durch den Namen Ihrer SQS-Warteschlange:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:GetQueueUrl",
                "sqs:ReceiveMessage",
                "sqs:GetQueueAttributes"
            ],
            "Resource": "YOUR-SQS-ARN-HERE"
        }
    ]
}

3. Wählen Sie Review Policy, wenn Sie fertig sind.

4. Geben Sie der Richtlinie einen Namen und eine Beschreibung und wählen Sie dann Create Policy.

Schritt 6: IAM-Rolle erstellen

Um die Einrichtung in AWS abzuschließen, erstellen Sie eine IAM-Rolle und hängen Sie die IAM-Richtlinie aus Schritt 5 daran an.

1. Gehen Sie im selben IAM-Bereich der Konsole, in dem Sie die IAM-Richtlinie erstellt haben, zu Roles > Create Role.

2. Wählen Sie in AWS Another AWS Account als Typ der vertrauenswürdigen Entität. Geben Sie Ihre Braze-Konto-ID ein. Aktivieren Sie das Kontrollkästchen Require external ID.
3. Gehen Sie in Braze zu Data Settings > Cloud Data Ingestion > Sources, wählen Sie Add data source und dann Amazon S3 im Abschnitt für Dateiquellen.
4. Kopieren Sie die automatisch generierte Braze Account ID.

6. Fügen Sie in AWS die Konto-ID ein und wählen Sie dann Next.

7. Hängen Sie die in Schritt 4 erstellte Richtlinie an die Rolle an. Suchen Sie die Richtlinie in der Suchleiste und setzen Sie ein Häkchen neben der Richtlinie, um sie anzuhängen. Wählen Sie Next, wenn Sie fertig sind.

Geben Sie der Rolle einen Namen und eine Beschreibung und wählen Sie Create Role.

8. Notieren Sie sich den ARN der erstellten Rolle und die generierte externe ID, da Sie diese für die Erstellung der Cloud-Datenaufnahme-Integration benötigen.

Cloud-Datenaufnahme in Braze einrichten

1. Erstellen Sie zunächst eine neue Quelle im Braze-Dashboard. Gehen Sie zu Data Settings > Cloud Data Ingestion > Sources, wählen Sie Add data source und dann Amazon S3.
2. Geben Sie Ihrer Quelle einen Namen und geben Sie die Informationen aus dem AWS-Einrichtungsprozess ein, um eine neue Quelle zu erstellen. Geben Sie Folgendes an:

• Role ARN
• External ID
• Bucket-Name
• Region

3. Wählen Sie Test connection, um zu bestätigen, dass Braze auf Ihren Bucket zugreifen kann. Nach einem erfolgreichen Test wählen Sie Connect to Source. Wenn die Verbindung fehlschlägt, wird eine Fehlermeldung angezeigt, die bei der Fehlerbehebung hilft.

4. Erstellen Sie als Nächstes eine neue Synchronisierung. Gehen Sie zu Data Settings > Cloud Data Ingestion > Syncs und wählen Sie Create data sync.

5. Geben Sie Ihrer Synchronisierung einen Namen. Wählen Sie dann eine aktive S3-Quelle aus und geben Sie Ihre Quelltabelle für die Synchronisierung ein. Wählen Sie einen Datentyp und wählen Sie Test Connection.

1. Geben Sie die restlichen Informationen aus dem AWS-Einrichtungsprozess ein. Geben Sie Folgendes an:
   • SQS-URL (muss für jede neue Integration eindeutig sein)
   • Ordnerpfad (optional, muss über alle Synchronisierungen in einem Workspace hinweg eindeutig sein)
2. Wählen Sie einen Datentyp und wählen Sie Test Connection, um zu bestätigen, dass Braze die zur Aufnahme verfügbaren Dateien auflisten kann (nicht die Daten in diesen Dateien). Nach Erfolg wählen Sie Next: Notifications.
3. Fügen Sie Kontakt-E-Mail-Adressen für Benachrichtigungen hinzu, falls die Synchronisierung aufgrund von Zugriffs- oder Berechtigungsproblemen unterbrochen wird. Optional können Sie Benachrichtigungen für Fehler auf Nutzer:innenebene und erfolgreiche Synchronisierungen aktivieren.
4. Erstellen Sie die Synchronisierung.

Die Integration erfordert die folgenden Ressourcen:

• Einen Cloud-Storage-Bucket für die Datenspeicherung
• Ein Pub/Sub-Topic und ein Abo für Benachrichtigungen über neue Dateien
• Ein Dienstkonto, auf das Braze über Workload Identity Federation zugreift, oder einen JSON-Schlüssel, den Sie in Braze hochladen

GCP-Definitionen

Begriff	Definition
Google-Cloud-Projekt	Ein Projekt organisiert alle Ihre Google-Cloud-Ressourcen und wird durch eine eindeutige Projekt-ID und Projektnummer identifiziert.
Cloud-Storage-Bucket	Ein Bucket ist der Container, der die Datendateien enthält, die Braze aufnehmen soll.
Pub/Sub-Topic	Ein Topic ist die benannte Ressource, die Benachrichtigungen über neue Dateien von Ihrem Cloud-Storage-Bucket empfängt.
Pub/Sub-Abo	Ein Abo ist an ein Topic angehängt und stellt dessen Nachrichten zu. Braze konsumiert Benachrichtigungen über neue Dateien aus einem Pull-Abo.
Dienstkonto	Ein Dienstkonto ist eine nicht-menschliche Identität, die Braze verwendet, um auf Ihren Bucket und Ihr Abo zuzugreifen. Braze gibt sich über Workload Identity Federation als dieses Konto aus oder verwendet einen JSON-Schlüssel, den Sie hochladen.
Workload Identity Federation	Workload Identity Federation (WIF) ermöglicht es Braze, sich mit einer kurzlebigen Identität als Ihr Dienstkonto auszugeben, sodass Sie keinen Schlüssel erstellen oder hochladen müssen.
IAM-Rolle	Eine Identity-and-Access-Management-Rolle (IAM-Rolle) ist eine Sammlung von Berechtigungen, die Sie dem Dienstkonto für Ihren Bucket und Ihr Abo zuweisen.

Cloud-Datenaufnahme in Google Cloud einrichten

Schritt 1: Cloud-Storage-Bucket erstellen

Gehen Sie in der Google-Cloud-Konsole zu Cloud Storage > Buckets > Create. Notieren Sie sich die Projekt-ID und den Bucket-Namen. Sie benötigen beides, wenn Sie die Quelle in Braze konfigurieren. Wir empfehlen, einheitlichen Zugriff auf Bucket-Ebene zu aktivieren, damit Berechtigungen über IAM verwaltet werden.

Alternativ können Sie den Bucket mit gcloud erstellen:

1
2
3
4

gcloud storage buckets create gs://YOUR-BUCKET-NAME \
  --project=YOUR-PROJECT-ID \
  --location=YOUR-REGION \
  --uniform-bucket-level-access

Schritt 2: Pub/Sub-Topic und Abo erstellen

Gehen Sie in der Google-Cloud-Konsole zu Pub/Sub > Topics > Create topic. Sie können Google ein Standardabo erstellen lassen oder eines separat erstellen. Erstellen Sie dann ein Pull-Abo für dieses Topic.

Alternativ können Sie gcloud verwenden:

1
2
3

gcloud pubsub topics create YOUR-TOPIC --project=YOUR-PROJECT-ID
gcloud pubsub subscriptions create YOUR-SUBSCRIPTION \
  --topic=YOUR-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60

Notieren Sie sich die Abo-ID. Braze benötigt das Abo (nicht das Topic), wenn Sie die Synchronisierung erstellen. Das Abo muss ein Pull-Abo sein.

Warnung

Konfigurieren Sie keine Dead-Letter-Warteschlange für dieses Abo. Braze unterstützt keine Dead-Letter-Warteschlangen für Cloud-Datenaufnahme-Abos. Weitere Informationen finden Sie unter Dead-letter topics in der Google-Cloud-Dokumentation.

Schritt 3: Bucket-Benachrichtigungen an das Topic senden

Wichtig

Das Erstellen einer Cloud-Storage-zu-Pub/Sub-Benachrichtigung ist in der Google-Cloud-Konsole nicht verfügbar. Sie müssen gcloud (hier gezeigt), Terraform oder die JSON-API verwenden. Weitere Informationen finden Sie unter Configure Pub/Sub notifications for Cloud Storage in der Google-Cloud-Dokumentation.

Weisen Sie zunächst dem Cloud-Storage-Dienstagenten die Berechtigung zu, im Topic zu veröffentlichen, und erstellen Sie dann die Benachrichtigung für OBJECT_FINALIZE. Das OBJECT_FINALIZE-Ereignis wird ausgelöst, wenn ein neues Objekt im Bucket erstellt oder finalisiert wird.

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

# Get the Cloud Storage service agent for your project
gcloud storage service-agent --project=YOUR-PROJECT-ID

# Assign it Pub/Sub Publisher on the topic
gcloud pubsub topics add-iam-policy-binding YOUR-TOPIC \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

# Create the OBJECT_FINALIZE notification (optionally scope to a folder with --object-prefix)
gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
  --topic=YOUR-TOPIC \
  --event-types=OBJECT_FINALIZE \
  --payload-format=json

Ersetzen Sie die folgenden Platzhalter in diesen Befehlen:

• YOUR-PROJECT-ID: Ihre Google-Cloud-Projekt-ID, der für Menschen lesbare Bezeichner (zum Beispiel my-gcp-project).
• YOUR-TOPIC: Das Pub/Sub-Topic, das Sie in Schritt 2 erstellt haben.
• YOUR-BUCKET-NAME: Ihr Cloud-Storage-Bucket-Name.
• YOUR-PROJECT-NUMBER: Ihre Projektnummer, der numerische Bezeichner, der in der E-Mail-Adresse des Cloud-Storage-Dienstagenten verwendet wird. Diese unterscheidet sich von der Projekt-ID. Sie finden sie im Dashboard der Google-Cloud-Konsole oder können folgenden Befehl ausführen:

1

gcloud projects describe YOUR-PROJECT-ID --format="value(projectNumber)"

Schritt 4: Dienstkonto erstellen

Gehen Sie in der Google-Cloud-Konsole zu IAM & Admin > Service Accounts > Create service account.

Alternativ können Sie gcloud verwenden:

1
2
3

gcloud iam service-accounts create braze-cdi-gcs \
  --project=YOUR-PROJECT-ID \
  --display-name="Braze CDI GCS"

Schritt 5: Berechtigungen zuweisen

Der Konnektor benötigt genau diese Berechtigungen: storage.buckets.get, storage.objects.get und storage.objects.list auf dem Bucket sowie pubsub.subscriptions.consume auf dem Abo. Sie können diese mit einer benutzerdefinierten Rolle oder vordefinierten Rollen zuweisen.

Benutzerdefinierte Rolle: Erstellen Sie eine benutzerdefinierte Rolle mit genau diesen Berechtigungen und binden Sie sie an den Bucket und das Abo:

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

gcloud iam roles create brazeCdiGcs --project=YOUR-PROJECT-ID \
  --title="Braze CDI GCS" \
  --permissions=storage.buckets.get,storage.objects.get,storage.objects.list,pubsub.subscriptions.consume \
  --stage=GA

gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

Vordefinierte Rollen: Weisen Sie roles/storage.objectViewer und roles/storage.legacyBucketReader auf dem Bucket sowie roles/pubsub.subscriber auf dem Abo zu. Die Rolle objectViewer bietet storage.objects.get und storage.objects.list, und legacyBucketReader bietet storage.buckets.get:

1
2
3
4
5
6
7
8
9
10

gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectViewer"
gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.legacyBucketReader"
gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="roles/pubsub.subscriber"

Schritt 6: Authentifizierung einrichten

Braze kann über Workload Identity Federation oder einen Dienstkontoschlüssel auf das Dienstkonto zugreifen. Vorhandene Dienstkontoschlüssel-Zugangsdaten funktionieren weiterhin, und Sie müssen sie nicht migrieren. Eine Workload-Identity-Federation-Berechtigung kann sowohl für Google Cloud Storage- als auch BigQuery-Quellen verwendet werden.

• workload identity federation
• dienstkontoschlüssel

Richten Sie einen Workload-Identity-Pool und -Anbieter ein und binden Sie den Braze-Prinzipal an das Dienstkonto aus Schritt 4. Anleitungen finden Sie unter Google Cloud für Workload Identity Federation konfigurieren. Verwenden Sie das Dienstkonto, das Sie in Schritt 4 erstellt haben, und überspringen Sie den Schritt zur Erstellung des Dienstkontos in der Anleitung.

Wenn Sie Workload Identity Federation bereits für eine andere Google Cloud Storage- oder BigQuery-Quelle eingerichtet haben, müssen Sie diesen Vorgang nicht wiederholen. Gewähren Sie dem vorhandenen Dienstkonto die Berechtigungen in Schritt 5.

Öffnen Sie in der Google-Cloud-Konsole das Dienstkonto, gehen Sie zu Keys > Add key > Create new key und wählen Sie JSON.

Alternativ können Sie gcloud verwenden:

1
2

gcloud iam service-accounts keys create braze-cdi-gcs-key.json \
  --iam-account=[email protected]

Cloud-Datenaufnahme in Braze einrichten

1. Gehen Sie in Braze zu Data Settings > Cloud Data Ingestion > Sources, wählen Sie Add data source und dann Google Cloud Storage.

2. Füllen Sie die Quellenfelder aus:
   • Bucket: Ihr Bucket-Name
   • Project ID: Ihre GCP-Projekt-ID
   • Credential: Geben Sie den Zugangsdaten einen Namen und wählen Sie die Authentifizierungsmethode aus Schritt 6. Für Workload Identity Federation geben Sie die Project number, Workload identity pool ID, Provider ID und Service account email ein. Für Service Account Key laden Sie die JSON-Schlüsseldatei hoch.

3. Wählen Sie Test connection und dann Connect to Source.
4. Erstellen Sie eine Synchronisierung. Gehen Sie zu Data Settings > Cloud Data Ingestion > Syncs und wählen Sie Create data sync. Geben Sie einen Synchronisierungsnamen und einen Data Type an (z. B. User Attributes, Custom Events, Purchase Events, Catalog oder Delete Users) und wählen Sie dann Next.
5. Wählen Sie im Schritt Data definition Ihre GCS-Quelle aus und geben Sie dann Folgendes an:
   • Pub/Sub subscription ID: die Abo-ID aus Schritt 2 (nicht das Topic)
   • Folder path (optional): ein Pfadpräfix innerhalb des Buckets (siehe Einen Ordner in einem gemeinsam genutzten Bucket synchronisieren)

6. Wählen Sie Preview and validate, um zu bestätigen, dass Braze das Abo erreichen und die zur Aufnahme verfügbaren Dateien auflisten kann. Ein erfolgreicher Test listet vorhandene Dateien im Bucket auf, aber diese Dateien werden nicht automatisch synchronisiert.
7. Fügen Sie Kontakt-E-Mail-Adressen für Fehlerbenachrichtigungen hinzu. Google-Cloud-Storage-Synchronisierungen sind ereignisgesteuert, sodass kein Zeitplan erforderlich ist. Braze nimmt neue Dateien auf, sobald sie hochgeladen werden. Überprüfen Sie die Zusammenfassung und wählen Sie dann Create sync.

Einen Ordner in einem gemeinsam genutzten Bucket synchronisieren

Sie können einen Bucket über mehrere Synchronisierungen hinweg wiederverwenden, aber jede Synchronisierung muss einen eigenen Ordner und ein eigenes dediziertes Pub/Sub-Abo verwenden.

Wichtig

Der Ordnerpfad und das Abo müssen beide über alle Synchronisierungen in einem Workspace hinweg eindeutig sein, wenn mehrere Synchronisierungen denselben Quell-Bucket nutzen. Wie in Schritt 2 beschrieben, konfigurieren Sie keine Dead-Letter-Warteschlange für diese Abos.

Für jeden Ordner, den Sie in einem gemeinsam genutzten Bucket synchronisieren möchten:

1. Setzen Sie das Feld Folder der Synchronisierung auf das Pfadpräfix (zum Beispiel attributes/). Braze listet und nimmt nur Objekte auf, deren Pfad mit diesem Präfix beginnt.

2. Erstellen Sie ein dediziertes Topic und eine präfixbezogene Benachrichtigung für diesen Ordner und erstellen Sie dann ein Abo für dieses Topic:

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   
    # One topic per folder
    gcloud pubsub topics create YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID
   
    # Assign the Cloud Storage service agent publisher on the topic
    gcloud pubsub topics add-iam-policy-binding YOUR-ATTRIBUTES-TOPIC \
      --project=YOUR-PROJECT-ID \
      --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
      --role="roles/pubsub.publisher"
   
    # Notification scoped to the folder with --object-prefix
    gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
      --topic=YOUR-ATTRIBUTES-TOPIC --event-types=OBJECT_FINALIZE \
      --payload-format=json --object-prefix=attributes/
   
    # One subscription per sync
    gcloud pubsub subscriptions create YOUR-ATTRIBUTES-SUBSCRIPTION \
      --topic=YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60
   
   

3. Weisen Sie dem Braze-Dienstkonto die Consume-Berechtigung für dieses Abo zu, wie in Schritt 5:

   
   1
   2
   3
   4
   
    gcloud pubsub subscriptions add-iam-policy-binding YOUR-ATTRIBUTES-SUBSCRIPTION \
      --project=YOUR-PROJECT-ID \
      --member="serviceAccount:[email protected]" \
      --role="roles/pubsub.subscriber"
   
   

   Wenn Sie die benutzerdefinierte Rolle in Schritt 5 erstellt haben, verwenden Sie stattdessen --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs".

4. Wenn Sie die Synchronisierung in Braze erstellen, geben Sie die neue Pub/Sub subscription ID und den Folder path dieses Ordners ein, damit die Synchronisierung nur die Dateien dieses Ordners aufnimmt.

Die Integration erfordert die folgenden Ressourcen:

• Ein Speicherkonto mit einem Blob-Container für die Datenspeicherung
• Eine Azure-Storage-Warteschlange und ein Ereignisabo für Benachrichtigungen über neue Dateien
• Einen Microsoft-Entra-ID-Dienstprinzipal, den CDI zum Lesen des Containers und der Warteschlange verwendet

Azure-Definitionen

Begriff	Definition
Speicherkonto	Ein Speicherkonto ist die übergeordnete Azure-Ressource, die sowohl den Container, aus dem CDI Dateien liest, als auch die Warteschlange, aus der CDI Benachrichtigungen liest, enthält.
Container	Ein Container enthält die Datendateien, die CDI aufnehmen soll. Container befinden sich innerhalb eines Speicherkontos.
Azure-Storage-Warteschlange	Eine Warteschlange empfängt Benachrichtigungen über neue Dateien aus Ihrem Container. CDI liest und bestätigt Nachrichten aus dieser Warteschlange, um zu wissen, welche Dateien aufgenommen werden sollen.
Ereignisabo	Ein Ereignisabo leitet Ereignisse von Ihrem Speicherkonto an ein Ziel weiter, wobei der Azure-Event-Grid-Dienst verwendet wird. Sie konfigurieren es so, dass Blob Created-Ereignisse an Ihre Warteschlange gesendet werden.
Systemtopic	Ein Systemtopic repräsentiert die Quelle der Ereignisse. Event Grid erstellt eines für Ihr Speicherkonto, wenn Sie das erste Ereignisabo hinzufügen.
Dienstprinzipal	Ein Dienstprinzipal ist eine Microsoft-Entra-ID-Identität, als die sich CDI authentifiziert. Sie erstellen ihn über eine App-Registrierung und geben seine Zugangsdaten in Braze ein.
Azure-Rollenzuweisung	Eine Rollenzuweisung gewährt einem Dienstprinzipal eine Reihe von Berechtigungen in einem bestimmten Bereich. Sie weisen dem Braze-Dienstprinzipal drei integrierte Rollen für Ihr Speicherkonto zu.

Cloud-Datenaufnahme in Azure einrichten

Schritt 1: Container erstellen

Der Container und die Warteschlange müssen sich im selben Speicherkonto befinden. Sie können ein vorhandenes Speicherkonto wiederverwenden. Falls Sie noch keines haben, gehen Sie im Azure-Portal zu Storage accounts > + Create, um eines zu erstellen.

1. Gehen Sie im Azure-Portal zu Ihrem Speicherkonto und dann zu Data storage > Containers.
2. Wählen Sie + Add container und geben Sie einen Namen ein.

Notieren Sie sich den Namen des Speicherkontos und den Containernamen. Sie benötigen beides, wenn Sie die Quelle in Braze konfigurieren.

Schritt 2: Warteschlange erstellen

1. Gehen Sie im selben Speicherkonto zu Data storage > Queues.
2. Wählen Sie + Queue und geben Sie einen Namen ein.

Notieren Sie sich den Warteschlangennamen. Sie benötigen ihn, wenn Sie die Synchronisierung erstellen, und jede Synchronisierung benötigt ihre eigene Warteschlange.

Schritt 3: Ereignisabo erstellen

Erstellen Sie ein Ereignisabo, damit Ihr Container die Warteschlange benachrichtigt, wenn eine Datei eintrifft.

1. Gehen Sie im selben Speicherkonto zu Events und wählen Sie dann + Event Subscription.
2. Geben Sie unter Event Subscription Details einen Name ein und setzen Sie Event Schema auf Event Grid Schema.
3. Überprüfen Sie unter Topic Details den System Topic Name. Wenn Ihr Speicherkonto noch kein Systemtopic hat, geben Sie einen Namen ein, um eines zu erstellen. Falls bereits eines vorhanden ist, zeigt das Feld diesen Namen an und er kann nicht geändert werden. Alle Ereignisabos eines Speicherkontos verwenden dasselbe Systemtopic.
4. Setzen Sie unter Event Types den Wert Filter to Event Types auf nur Blob Created. Blob Deleted ist standardmäßig ebenfalls ausgewählt – entfernen Sie diese Auswahl.
5. Setzen Sie unter Endpoint Details den Endpoint Type auf Storage Queue. Der Link Configure an endpoint erscheint, nachdem Sie einen Endpunkttyp ausgewählt haben.
6. Wählen Sie Configure an endpoint und wählen Sie dann das Speicherkonto aus, in dem Sie arbeiten.
7. Wählen Sie Select existing queue und wählen Sie die Warteschlange aus, die Sie in Schritt 2 erstellt haben.
8. Wählen Sie Select, um den Endpunkt zu bestätigen.
9. Wählen Sie Create.

Schritt 4: Dienstprinzipal erstellen

CDI verbindet sich über einen Dienstprinzipal mit Microsoft-Entra-ID-Authentifizierung mit Ihrem Speicherkonto. Braze benötigt die folgenden Angaben für die Verbindung:

• Mandanten-ID (auch als Verzeichnis bezeichnet) für Ihr Azure-Konto
• Prinzipal-ID (auch als Anwendungs-ID bezeichnet) für den Dienstprinzipal
• Client-Secret für die Authentifizierung durch Braze

Zum Registrieren einer Anwendung ist die Berechtigung zum Erstellen von App-Registrierungen in Microsoft Entra ID erforderlich. Falls Sie diese Berechtigung nicht haben, bitten Sie eine:n Entra-Administrator:in, diesen Schritt durchzuführen und die Zugangsdaten mit Ihnen zu teilen.

1. Navigieren Sie im Azure-Portal zum Microsoft Entra Admin Center und dann zu App Registrations.
2. Wählen Sie + New registration unter Identity > Applications > App registrations aus.
3. Geben Sie einen Namen ein und wählen Sie Accounts in this organizational directory only als unterstützten Kontotyp aus. Wählen Sie dann Register aus.
4. Wählen Sie die soeben erstellte Anwendung (Dienstprinzipal) aus und navigieren Sie dann zu Certificates & secrets > + New client secret.
5. Geben Sie eine Beschreibung für das Secret ein und legen Sie einen Ablaufzeitraum für das Secret fest. Wählen Sie dann Add aus.
6. Notieren Sie sich das erstellte Client-Secret, um es bei der Braze-Einrichtung zu verwenden.

Hinweis

Azure erlaubt keine unbegrenzte Gültigkeitsdauer für Dienstprinzipal-Secrets. Denken Sie daran, die Zugangsdaten vor ihrem Ablauf zu aktualisieren, um den Datenfluss zu Braze aufrechtzuerhalten.

Wir empfehlen, einen Dienstprinzipal zu erstellen, der ausschließlich für CDI verwendet wird, damit sein Zugriff auf den Container und die Warteschlange beschränkt bleibt, die Sie synchronisieren. Wenn Sie bereits einen für eine Microsoft-Fabric-Quelle eingerichtet haben, können Sie ihn wiederverwenden, aber dann hat er Zugriff auf beide. In beiden Fällen benötigt er die Rollenzuweisungen im nächsten Schritt.

Schritt 5: Berechtigungen für den Dienstprinzipal zuweisen

CDI benötigt nur genügend Zugriff, um Ihre Dateien zu lesen und Warteschlangennachrichten zu verarbeiten. Weisen Sie diese drei integrierten Rollen auf dem Speicherkonto selbst zu – nicht auf Abonnement- oder Ressourcengruppenebene, da Rollenzuweisungen nach unten vererbt werden. Weisen Sie keine umfassenderen Rollen wie „Storage Blob Data Contributor“, „Storage Account Contributor“ oder „Owner“ zu, die Schreib- und Verwaltungsberechtigungen gewähren, die CDI nicht benötigt.

1. Gehen Sie zu Ihrem Speicherkonto und dann zu Access Control (IAM).
2. Wählen Sie Add > Add role assignment.
3. Suchen Sie den Dienstprinzipal, den Sie in Schritt 4 erstellt haben, nach Name.
4. Weisen Sie ihm die folgenden integrierten Rollen zu:
   • Storage Blob Data Reader: ermöglicht CDI das Lesen der Dateien in Ihrem Container.
   • Storage Queue Data Reader: ermöglicht CDI das Lesen der Warteschlange selbst, um die benannte Warteschlange in der Synchronisierung zu finden und ihre Eigenschaften zu prüfen.
   • Storage Queue Data Message Processor: ermöglicht CDI das Einsehen, Abrufen und Löschen von Nachrichten in Ihrer Warteschlange.

Sie können auch eine benutzerdefinierte Rolle verwenden, sofern sie nur Lesezugriff auf Blobs im Container, Lesezugriff auf die Warteschlange und die Möglichkeit zum Empfangen und Löschen von Nachrichten in der Warteschlange gewährt.

Hinweis

Wenn Add role assignment ausgegraut ist, kann Ihr Konto auf diesem Speicherkonto keine Rollen zuweisen. Dafür ist eine Rolle wie „Owner“ oder „User Access Administrator“ erforderlich. Bitten Sie eine:n Azure-Administrator:in, diesen Schritt durchzuführen.

Cloud-Datenaufnahme in Braze einrichten

1. Gehen Sie in Braze zu Data Settings > Cloud Data Ingestion > Sources, wählen Sie Add data source und dann Azure Blob.

2. Füllen Sie die Felder unter Azure Blob Connection Details aus:
   • Credentials: Tenant ID, Principal ID und Client Secret
   • Configuration: Storage account und Container

3. Wählen Sie Test connection und dann Connect to Source.
4. Erstellen Sie eine Synchronisierung. Gehen Sie zu Data Settings > Cloud Data Ingestion > Syncs und wählen Sie Create data sync.
5. Wählen Sie unter Configurations einen Synchronisierungsnamen, wählen Sie Ihre Azure-Blob-Quelle aus und wählen Sie einen Data Type (z. B. User Attributes, Custom Events, Purchase Events, Catalog oder Delete Users).
6. Geben Sie unter Data definition Folgendes an:
   • Storage queue name: die Warteschlange, die Sie in Schritt 2 erstellt haben. Jede Synchronisierung benötigt ihre eigene Warteschlange (siehe Einen Ordner in einem gemeinsam genutzten Container synchronisieren).
   • Folder path (Optional): ein Pfadpräfix innerhalb des Containers

7. Wählen Sie Preview and validate, um zu bestätigen, dass CDI die Warteschlange erreichen und die zur Aufnahme verfügbaren Dateien auflisten kann. Ein erfolgreicher Test listet vorhandene Dateien im Container auf, aber diese Dateien werden nicht automatisch synchronisiert. Die Synchronisierung wird erst aktiv, wenn die Verbindung erfolgreich validiert wurde.
8. Fügen Sie unter Notifications Kontakt-E-Mail-Adressen für Fehlerbenachrichtigungen hinzu.
9. Schedule bietet keine Optionen für Dateispeicher-Synchronisierungen. Azure-Blob-Storage-Synchronisierungen sind ereignisgesteuert, sodass CDI neue Dateien aufnimmt, sobald sie hochgeladen werden.
10. Überprüfen Sie die Summary und wählen Sie dann Create sync.

Einen Ordner in einem gemeinsam genutzten Container synchronisieren

Sie können einen Container über mehrere Synchronisierungen hinweg wiederverwenden, aber jede Synchronisierung benötigt ihre eigene Speicherwarteschlange und ihren eigenen Ordner.

Wichtig

Zwei Synchronisierungen können nicht dieselbe Speicherwarteschlange verwenden. Wenn Sie eine Warteschlange eingeben, die bereits von einer anderen Synchronisierung verwendet wird, kennzeichnet CDI dies und verlinkt auf die bestehende Synchronisierung.

Für jeden Ordner, den Sie in einem gemeinsam genutzten Container synchronisieren möchten:

1. Erstellen Sie eine Warteschlange für diesen Ordner, wie in Schritt 2.
2. Erstellen Sie ein Ereignisabo, das die Blob Created-Ereignisse des Containers an diese Warteschlange sendet, wie in Schritt 3.
3. Wenn Sie die Synchronisierung in Braze erstellen, geben Sie den Storage queue name dieses Ordners ein und setzen Sie Folder path (Optional) auf das Ordnerpräfix, z. B. attributes/. CDI nimmt nur Dateien auf, deren Pfad mit diesem Präfix beginnt.

Erforderliche Dateiformate

Die erforderlichen Dateiformate sind für Amazon S3, Google Cloud Storage und Azure Blob Storage identisch. Cloud Data Ingestion unterstützt JSON-, CSV- und Parquet-Dateien. Die erforderlichen Spalten hängen vom Datentyp ab:

• Nutzerdaten (Attribute, angepasste Events, Kauf-Events) verwenden Nutzer-Bezeichner und eine Payload
• Katalogdaten verwenden Katalog-Bezeichner

Wenn Sie File Storage für Katalogdaten verwenden, nutzen Sie diese Seite zusammen mit Katalogdaten synchronisieren und löschen für katalogspezifische Anforderungen und Verhaltensweisen.

Braze erzwingt keine zusätzlichen Anforderungen an Dateinamen über die hinaus, die von Ihrem File-Storage-Anbieter vorgegeben werden. Dateinamen sollten eindeutig sein. Das Anhängen eines Zeitstempels hilft, Eindeutigkeit sicherzustellen.

Beispiele für alle unterstützten Dateitypen (Attribute, angepasste Events, Käufe, Kataloge und Nutzer-Löschungen) finden Sie in den Beispieldateien unter braze-examples.

Nutzer-Bezeichner

Für Nutzerdaten-Syncs (Attribute, angepasste Events, Kauf-Events) erfordert jede Zeile in Ihrer Quelldatei genau einen Nutzer-Bezeichner und eine PAYLOAD-Spalte. Eine Quelldatei kann Zeilen mit verschiedenen Bezeichnertypen enthalten, aber jede einzelne Zeile sollte nur einen verwenden.

Zusätzlich zu einem Bezeichner muss jede Zeile eine PAYLOAD-Spalte enthalten, die einen JSON-String mit den Feldern enthält, die Sie mit der Nutzer:in in Braze synchronisieren möchten.

Hinweis

Anders als bei Data-Warehouse-Quellen ist die Spalte UPDATED_AT für File-Storage-Syncs weder erforderlich noch unterstützt.

Katalog-Bezeichner

Für Katalog-Syncs muss Ihre Quelldatei die folgenden Spalten enthalten. Katalogdateien verwenden andere Bezeichner als Nutzerdatendateien.

Beispiele

• json attributes
• json custom events
• json purchase events
• csv attributes
• csv catalogs

1
2
3
4
5
6
7

{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}
{"external_id":"s3-qa-3","payload":"{\"name\": \"5P44M\", \"age\": 15, \"subscriber\": true, \"retention\": {\"previous_purchases\": 7, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600838\"}"}
{"external_id":"s3-qa-4","payload":"{\"name\": \"WMYS7\", \"age\": 11, \"subscriber\": true, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600844\"}"}
{"external_id":"s3-qa-5","payload":"{\"name\": \"KCBLK\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 11, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600850\"}"}
{"external_id":"s3-qa-6","payload":"{\"name\": \"T93MJ\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 10, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600856\"}"}

Wichtig

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

1
2

{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}

Wichtig

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

1
2

{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}

Wichtig

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

1
2
3
4

external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"
s3-qa-load-2-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""EP1U0"", ""age"": 99, ""subscriber"": false, ""retention"": {""previous_purchases"": 23, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598822""}"

1
2
3

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

Fügen Sie eine optionale DELETED-Spalte hinzu. Wenn DELETED den Wert true hat, wird der entsprechende Katalogartikel aus dem Katalog in Braze entfernt. Die vollständige Liste der erforderlichen Spalten finden Sie unter Katalog-Bezeichner. Informationen zum Löschverhalten finden Sie unter Katalogartikel löschen. Einen End-to-End-Katalog-Einrichtungsablauf (einschließlich Erstellung des Zielkatalogs und Sync-Verhalten) finden Sie unter Katalogdaten synchronisieren und löschen.

Daten löschen

Cloud-Datenaufnahme für Dateispeicher unterstützt das Löschen von Nutzer:innen und Katalogartikeln über Datei-Uploads. Verwenden Sie für jeden Vorgang separate Syncs und Dateiformate.

• Nutzer:innen löschen – Erstellen Sie einen Sync mit dem Datentyp Delete Users und laden Sie Dateien hoch, die nur Nutzer-Bezeichner enthalten (keine Payload).
• Katalogartikel löschen – Verwenden Sie Ihren bestehenden Katalog-Sync und fügen Sie eine Spalte deleted (oder DELETED) hinzu, um Artikel zur Entfernung zu markieren.

Nutzer:innen löschen

So löschen Sie Nutzerprofile in Braze mithilfe von Dateien in Ihrem Quell-Bucket:

1. Erstellen Sie einen neuen Cloud-Datenaufnahme-Sync (gleiche Einrichtung wie für andere Syncs).
2. Setzen Sie beim Konfigurieren des Syncs in Braze den Data Type auf Delete Users.
3. Laden Sie Dateien in Ihren Quell-Bucket hoch, die nur Spalten mit Nutzer-Bezeichnern enthalten. Fügen Sie keine PAYLOAD-Spalte hinzu – der Sync schlägt fehl, wenn eine Payload vorhanden ist, um versehentliche Löschungen zu vermeiden.

Jede Zeile in der Datei muss genau eine:n Nutzer:in über eine der folgenden Optionen identifizieren:

Wichtig

Das Löschen von Nutzer:innen ist dauerhaft und kann nicht rückgängig gemacht werden. Nehmen Sie nur Nutzer:innen auf, die Sie tatsächlich entfernen möchten. Weitere Informationen finden Sie unter Nutzer:innen mit Cloud-Datenaufnahme löschen.

Beispiel – JSON (Nutzer:innen löschen):

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

Beispiel – CSV (Nutzer:innen löschen):

1
2
3

external_id
user-to-delete-001
user-to-delete-002

Wenn der Sync ausgeführt wird, verarbeitet Braze neue Dateien im Bucket und löscht die entsprechenden Nutzerprofile.

Katalogartikel löschen

So entfernen Sie Artikel aus einem Katalog mithilfe von Dateispeicher:

1. Verwenden Sie denselben Sync, den Sie zum Synchronisieren von Katalogdaten verwenden (Datentyp Catalogs).
2. Fügen Sie in Ihren CSV- oder JSON-Dateien eine optionale Spalte deleted (oder DELETED) hinzu.
3. Setzen Sie deleted auf true für jeden Katalogartikel, den Sie aus dem Katalog in Braze entfernen möchten.

Jede Zeile benötigt weiterhin ID und PAYLOAD. Für Zeilen, die zum Löschen markiert sind, kann die Payload minimal sein; Braze entfernt den Artikel anhand der ID.

Beispiel – JSON (Katalogartikel löschen):

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

Beispiel – CSV (Katalogartikel löschen):

1
2
3

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

Wenn der Sync ausgeführt wird, bewirken Zeilen mit deleted: true, dass der entsprechende Katalogartikel in Braze gelöscht wird. Informationen zum vollständigen Synchronisierungs- und Löschverhalten für Kataloge finden Sie unter Katalogdaten synchronisieren und löschen.

Wissenswertes

• Dateien, die dem Quell-Bucket oder -Container hinzugefügt werden, sollten 512 MB nicht überschreiten. Dieses Limit gilt für Amazon S3, Google Cloud Storage und Azure Blob Storage. Dateien, die größer als 512 MB sind, führen zu einem Fehler und werden nicht mit Braze synchronisiert. Azure Blob Storage selbst erlaubt wesentlich größere Dateien, aber CDI wendet dasselbe Limit von 512 MB auf alle Dateispeicherquellen an.
• Es gibt zwar kein zusätzliches Limit für die Anzahl der Zeilen pro Datei, wir empfehlen jedoch die Verwendung kleinerer Dateien, um die Geschwindigkeit Ihrer Synchronisierungen zu verbessern. Beispielsweise würde die Aufnahme einer 500 MB-Datei erheblich länger dauern als die von fünf separaten 100 MB-Dateien.
• Es gibt kein zusätzliches Limit für die Anzahl der Dateien, die in einem bestimmten Zeitraum hochgeladen werden.
• Eine Reihenfolge wird weder innerhalb von Dateien noch zwischen Dateien unterstützt. Wir empfehlen, Updates in regelmäßigen Abständen als Batch zu verarbeiten, wenn Sie auf erwartete Race-Conditions achten.

Fehlerbehebung

Dateien hochladen und verarbeiten

CDI verarbeitet nur Dateien, die nach der Erstellung der Synchronisierung hinzugefügt werden. In diesem Prozess sucht Braze nach neu hinzugefügten Dateien, die eine neue Benachrichtigung auslösen. Dadurch wird eine neue Synchronisierung gestartet, um die neue Datei zu verarbeiten. Bei Amazon S3 ist die Benachrichtigung eine Nachricht an SQS. Bei Google Cloud Storage handelt es sich um eine OBJECT_FINALIZE-Nachricht an Pub/Sub. Bei Azure Blob Storage ist es ein Blob Created-Ereignis, das an eine Azure Storage-Warteschlange übermittelt wird.

Sie können vorhandene Dateien verwenden, um zu überprüfen, ob Braze auf Ihren Bucket zugreifen und zu importierende Dateien erkennen kann. Diese werden jedoch nicht mit Braze synchronisiert. Damit CDI sie verarbeiten kann, müssen Sie alle vorhandenen Dateien, die synchronisiert werden sollen, erneut in den Quell-Bucket hochladen.

Unerwartete Dateifehler behandeln (Amazon S3)

Wenn Sie eine hohe Anzahl an Fehlern oder fehlgeschlagenen Dateien beobachten, fügt möglicherweise ein anderer Prozess Dateien zum S3-Bucket in einem anderen Ordner als dem Zielordner für CDI hinzu.

Wenn Dateien in den Quell-Bucket, aber nicht in den Quellordner hochgeladen werden, verarbeitet CDI die SQS-Benachrichtigung, führt jedoch keine Aktion für die Datei aus. Dies kann daher als Fehler erscheinen.

Wenn Ihr Problem mit S3-Benachrichtigungen oder SQS-Zielberechtigungen zusammenhängt (z. B. Fehler bei der Zielvalidierung), lesen Sie die AWS-Dokumentation:

• Aktivieren und Konfigurieren von Ereignisbenachrichtigungen über die Amazon-S3-Konsole
• Berechtigungen zum Veröffentlichen von Ereignisbenachrichtigungen an ein Ziel erteilen
• Fehlerbehebung bei Problemen in Amazon SQS

Unerwartete Dateifehler behandeln (Google Cloud Storage)

Wie bei Amazon S3 verarbeitet CDI nur Dateien, die nach der Erstellung der Synchronisierung hochgeladen werden. Jedes neue Objekt löst eine OBJECT_FINALIZE-Nachricht an Ihr Pub/Sub-Topic aus. Um bereits im Bucket vorhandene Dateien aufzunehmen, laden Sie sie erneut hoch.

Wenn Dateien nicht aufgenommen werden, überprüfen Sie Folgendes:

• Die Bucket-Benachrichtigung existiert. Listen Sie die Benachrichtigungen des Buckets mit gcloud storage buckets notifications list gs://YOUR-BUCKET-NAME auf.
• Der Cloud-Storage-Dienstagent hat roles/pubsub.publisher für das Topic.
• Das Braze-Dienstkonto hat Verbrauchsberechtigung für das Abonnement (pubsub.subscriptions.consume, zugewiesen entweder über die benutzerdefinierte Rolle oder roles/pubsub.subscriber).
• Für das Abonnement ist keine Dead-Letter-Warteschlange konfiguriert. Braze unterstützt keine Dead-Letter-Warteschlangen für Cloud-Data-Ingestion-Abonnements.

Weitere Informationen finden Sie unter Pub/Sub-Benachrichtigungen für Cloud Storage in der Google-Cloud-Dokumentation.

Unerwartete Dateifehler behandeln (Azure Blob Storage)

Wie bei Amazon S3 und Google Cloud Storage verarbeitet CDI nur Dateien, die nach der Erstellung der Synchronisierung hochgeladen werden. Jedes neue Blob löst ein Blob Created-Ereignis in Ihrer Warteschlange aus. Um bereits im Container vorhandene Dateien aufzunehmen, laden Sie sie erneut hoch.

Wenn Dateien nicht aufgenommen werden, überprüfen Sie Folgendes:

• Das Ereignisabonnement existiert im Speicherkonto und ist auf Blob Created gefiltert.
• Das Ereignisabonnement verwendet Event Grid Schema. CDI kann keine Ereignisse lesen, die in einem anderen Schema übermittelt werden.
• Der Endpunkt des Ereignisabonnements zeigt auf die Warteschlange, die in der Synchronisierung konfiguriert ist, nicht auf eine andere Warteschlange.
• Der Braze-Dienstprinzipal hat Storage Blob Data Reader, Storage Queue Data Reader und Storage Queue Data Message Processor für das Speicherkonto.
• Das Client-Secret des Dienstprinzipals ist nicht abgelaufen. Azure erzwingt einen Ablauf für Client-Secrets, und ein abgelaufenes Secret stoppt die Synchronisierung.

Weitere Informationen finden Sie unter Azure Blob Storage als Event-Grid-Quelle in der Microsoft-Dokumentation.