Zum Inhalt springen

Datenobjekt-Endpunkte

Verwenden Sie diese Endpunkte, um Datenobjekttypen aufzulisten, Datenobjektdatensätze zu verwalten und Objekt- sowie Nutzer:innenbeziehungen zu verwalten.

Objekt-Endpunkte

Objektbeziehungs-Endpunkte

Nutzer:innenbeziehungs-Endpunkte

Basis-URL und Authentifizierung

Verwenden Sie den REST-Endpunkt Ihres Workspace und senden Sie Authorization: Bearer YOUR_REST_API_KEY. In diesem Abschnitt erfahren Sie, wo die Endpunkte für Datenobjekte gehostet werden und wie Anfragen authentifiziert werden.

  • Informationen zu den Endpunkt-Hosts finden Sie in der Braze API-Übersicht.
  • Alle Anfrage- und Antwort-Payloads sind im JSON-Format.
  • Anfragen gelten nur für den Workspace, dem der API-Schlüssel gehört.
  • Wenn für den Schlüssel eine IP-Allowlist eingerichtet ist, geben Anfragen von nicht freigegebenen IP-Adressen 403 zurück.

API-Schlüssel-Berechtigungen

In diesem Abschnitt wird jedem Endpunkt die erforderliche Berechtigung zugeordnet, damit Sie den Geltungsbereich von API-Schlüsseln sicher festlegen können.

Berechtigung Endpunktgruppe
data_objects.read Lesen von Typen und Objekten sowie Lesen von Objektbeziehungen
data_objects.create Objekt erstellen
data_objects.update Objekt ersetzen und aktualisieren
data_objects.delete Objekt löschen
data_objects.user_relationships.read Lesen von Nutzerbeziehungen
data_objects.user_relationships.create Nutzerbeziehung erstellen
data_objects.user_relationships.update Nutzerbeziehung ersetzen und aktualisieren
data_objects.user_relationships.delete Nutzerbeziehung löschen
data_objects.object_relationships.create Objektbeziehung erstellen
data_objects.object_relationships.update Objektbeziehung ersetzen und aktualisieren
data_objects.object_relationships.delete Objektbeziehung löschen
data_objects.bulk_upsert Objekte stapelweise erstellen oder ersetzen
data_objects.bulk_delete Objekte stapelweise löschen
data_objects.object_relationships.bulk_upsert Objektbeziehungen stapelweise erstellen oder ersetzen
data_objects.object_relationships.bulk_delete Objektbeziehungen stapelweise löschen
data_objects.user_relationships.bulk_upsert Nutzerbeziehungen stapelweise erstellen oder ersetzen
data_objects.user_relationships.bulk_delete Nutzerbeziehungen stapelweise löschen

Rate-Limits

In diesem Abschnitt werden die Standardkontingente für Anfragen und die Antwort-Header für Lese- und Schreibzugriffe erläutert.

Bucket Standardlimit
Lesezugriffe auf Datenobjekte 1.000 Anfragen pro Minute
Schreibzugriffe auf Datenobjekte 1.000 Anfragen pro Minute
Bulk-Schreibzugriffe auf Datenobjekte 1.000 Anfragen pro Minute, gemeinsam genutzt von den sechs Bulk-Endpunkten und den Synchronisierungen von Datenobjekten über Cloud Data Ingestion

Das Limit für Bulk-Schreibzugriffe gilt pro Workspace und ist unabhängig vom Schreiblimit für einzelne Datensätze.

Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.

Bei gedrosselten Anfragen gibt Braze 429 und einen Fehler-Payload mit id und message zurück.

{
  "errors": [
    {
      "id": "rate-limit-exceeded",
      "message": "You have exceeded your limit of 1000 requests per minute."
    }
  ]
}

Produktlimits

In diesem Abschnitt finden Sie die Limits, die Braze für Datenobjekte durchsetzt, und was Sie erwartet, wenn Sie ein Limit erreichen. Wie diese Limits für Account-Datensätze gelten, erfahren Sie unter Limits für Account-Objekte.

Mengenlimits

Sofern nicht anders angegeben, gelten diese Limits für Ihr gesamtes Unternehmen. Es handelt sich um Anfangskapazitäten. Wenn Sie mehr Datensätze oder ein höheres Limit benötigen, wenden Sie sich an Ihr Braze-Account-Team, um eine Erhöhung anzufordern.

Limit Standardwert
Datenobjekt-Datensätze pro Unternehmen (über alle Workspaces hinweg) 50.000
Felder pro Datenobjekttyp 500
Mit einem:einer Nutzer:in verknüpfte Datenobjekte 1.000
Mit einem Datenobjekt verknüpfte Nutzer:innen 10.000
Objektbeziehungen für ein Datenobjekt 1.000

Feld- und Wertlimits

Diese Limits sind für alle Unternehmen fest vorgegeben.

Limit Wert
Felder pro Beziehungstyp (Nutzerbeziehungen und Objektbeziehungen) 25. Beziehungsfelder werden nicht auf das Limit für Felder pro Datenobjekttyp angerechnet.
Länge von Attributwerten 255 Zeichen
Datumsfelder RFC 3339-Datums-/Zeit-Strings mit Uhrzeit und Zeitzone, zum Beispiel 2026-11-03T00:00:00Z. Braze lehnt reine Datumswerte wie 2026-11-03 ab. Weitere Informationen finden Sie unter Datumsfeldformat.
Länge und Format von object_id 250 Zeichen. Nur Buchstaben, Zahlen, Bindestriche und Unterstriche.
Länge und Format von Feldnamen 250 Zeichen. Nur Buchstaben, Zahlen und Unterstriche; darf nicht mit einem Unterstrich beginnen.
Reservierte Feldnamen id, external_id, object_id und display_name können nicht als angepasste Feldnamen verwendet werden.

Datumsfeldformat

Datumsfelder akzeptieren nur RFC 3339-Datums-/Zeit-Strings, die sowohl eine Uhrzeit als auch eine Zeitzone enthalten. Braze benötigt den vollständigen Wert, damit nie eine Uhrzeit oder Zeitzone geraten werden muss. Wenn Ihre Quelle reine Datumswerte speichert, etwa Verlängerungs- oder Vertragsdaten in Ihrem Data Warehouse, konvertieren Sie diese vor dem Senden, zum Beispiel in Ihrer Warehouse-Transformation.

Wert Ergebnis
2026-11-03T00:00:00Z Akzeptiert
2026-11-03T00:00:00-05:00 Akzeptiert
2026-11-03 Abgelehnt, da Uhrzeit und Zeitzone fehlen
2026-11-03T00:00:00 Abgelehnt, da die Zeitzone fehlt

Dieses Format gilt für Datumsfelder in Datenobjekten, Nutzerbeziehungen und Objektbeziehungen. Wie Braze einen abgelehnten Wert meldet, hängt davon ab, wie Sie ihn senden:

  • Die Endpunkte zum Erstellen, Ersetzen und Aktualisieren einzelner Datensätze geben 400 zurück. Sind mehrere Attribute ungültig, nennt der Fehler nur das erste.
  • Die Bulk-Upsert-Endpunkte nehmen die Anfrage mit 202 an und erfassen dann für den Datensatz einen Verarbeitungsfehler data-object-schema-mismatch, zum Beispiel attributes: renewal_date is not valid for its field.
  • Cloud Data Ingestion-Synchronisierungen verwenden dieselbe Verarbeitung wie die Bulk-Endpunkte. Braze übernimmt daher keine Zeile mit einem reinen Datumswert, und der Fehler erscheint in den Synchronisierungsprotokollen.

Eine Anfrage für einen einzelnen Datensatz, die zum Beispiel 2026-11-03 für ein Datumsfeld renewal_date sendet, gibt diese 400-Antwort zurück:

{
  "error": "Validation failed: Attrs do not conform to field definitions: The property '#/renewal_date' must be a valid RFC3339 date/time string"
}

Was passiert, wenn Sie ein Limit erreichen

Eine Anfrage, die ein Mengenlimit überschreiten würde, gibt 422 mit einer Fehler-id zurück, die das Limit identifiziert:

{
  "errors": [
    {
      "id": "data-object-record-limit-exceeded",
      "message": "This company has reached its data object record limit"
    }
  ]
}
Limit Fehler-id
Datenobjekt-Datensätze pro Unternehmen data-object-record-limit-exceeded
Felder pro Datenobjekttyp data-object-field-limit-exceeded
Felder pro Beziehungstyp data-object-field-limit-exceeded
Mit einem:einer Nutzer:in verknüpfte Datenobjekte data-objects-per-user-limit-exceeded
Mit einem Datenobjekt verknüpfte Nutzer:innen users-per-data-object-limit-exceeded
Objektbeziehungen für ein Datenobjekt data-object-relationship-limit-exceeded

Ihre vorhandenen Datensätze und Beziehungen bleiben bestehen – nur die Anfrage, die das Limit überschreiten würde, wird abgelehnt. Um unter einem Limit wieder Platz zu schaffen, löschen Sie nicht mehr benötigte Datensätze oder entfernen Sie nicht mehr verwendete Beziehungen. Um ein Mengenlimit zu erhöhen, wenden Sie sich an Ihr Braze-Account-Team.

Anfragen, die die Validierung nicht bestehen, etwa weil eine object_id oder ein Attributwert zu lang ist, geben 400 zurück. Anfragen, die das Rate-Limit überschreiten, geben 429 zurück.

Kernkonzepte

In diesem Abschnitt werden die wichtigsten Bezeichner definiert, die in allen Endpunkten für Datenobjekte verwendet werden.

  • type_name: Der Maschinenname des Datenobjekttyps, eindeutig innerhalb eines Workspace.
  • object_id: Ihr Objekt-Bezeichner, eindeutig innerhalb eines Typs.
  • user: Die Nutzer:in in einer Schreibanfrage für eine Nutzerbeziehung, identifiziert durch genau einen der Werte external_id, braze_id, alias, email oder phone.
  • attributes: Objekt- oder Beziehungsdaten mit Feldnamen als Schlüsseln, die anhand des konfigurierten Schemas validiert werden.

So funktionieren Beziehungen

In diesem Abschnitt lernen Sie Beziehungstypen, Beziehungskanten und das Verhalten von anchor kennen, bevor Sie die Referenzseiten der Endpunkte verwenden.

Beziehungsmodell im Überblick

Das folgende Diagramm zeigt, wie Typen, Datensätze und Beziehungen zusammenhängen und was Sie in Braze damit erreichen, wenn Sie sie miteinander verknüpfen. Die Typen definieren Sie im Dashboard. Die Datensätze und die Verknüpfungen zwischen ihnen schreiben Sie anschließend über diese Endpunkte.

%%{init: {"flowchart": {"wrappingWidth": 400}} }%%
flowchart LR
  subgraph define["Set up in the dashboard"]
    objtype["Data object types define<br/>the fields a record has"]
    reltype["Relationship types determine<br/>which links are allowed"]
  end

  subgraph write["Write with the API"]
    person["A person you<br/>send messages to"]
    record["A business record<br/>they belong to"]
    related["Another record<br/>connected to it"]
    person -- "A user relationship links<br/>a person to a record" --> record
    record -- "An object relationship links<br/>one record to another" --> related
  end

  subgraph unlock["What it unlocks"]
    segment["Segment people by the<br/>records they belong to"]
    liquid["Personalize messages with<br/>data from those records"]
  end

  define -- "decides what you<br/>are allowed to link" --> write
  write -- "makes these<br/>possible" --> unlock

Typen und Kanten sind getrennt

  • Beziehungstypen legen fest, welche Verknüpfungen gültig sind, und werden im Dashboard verwaltet.
  • Beziehungskanten sind die tatsächlichen Verknüpfungen zwischen Datensätzen. Sie werden über diese API-Endpunkte erstellt, aktualisiert und gelöscht.
  • Bevor Sie Beziehungen schreiben, rufen Sie die gültigen rel_kind-Werte mit folgenden Endpunkten ab:
    • GET /data_objects/types/{type_name}/user_relationship_types
    • GET /data_objects/types/{type_name}/object_relationship_types
  • rel_kind ist nicht über alle Paare von Objekttypen hinweg eindeutig. Beispielsweise kann rel_kind für ein Paar von Objekttypen subaccount und für ein anderes partner_account lauten.
  • Schreibvorgänge für Objektbeziehungen erfordern daher sowohl rel_kind als auch related_type_name, um den gewünschten Beziehungstyp zusammen mit dem anderen Objekttyp in der Verknüpfung zu bestimmen.
  • Wenn related_type_name nicht zum Beziehungstyp für dieses rel_kind passt, gibt die Anfrage 400 zurück.

anchor steuert die Richtung der Beziehung

Objektbeziehungen sind gerichtet. Das Objekt in der URL wird abhängig von anchor interpretiert.

anchor Rolle des URL-Objekts Schlüssel des verknüpften Objekts in Antworten
source (Standard) Ausgangsseite (ausgehende Kante) to_data_object
target Zielseite (eingehende Kante) from_data_object

Wenn Sie dieselbe Kante aus der entgegengesetzten anchor-Perspektive erstellen, betrifft dies dennoch nur eine zugrunde liegende Beziehung. Ein zweiter Erstellungsaufruf für dieselbe Kante gibt 409 (duplicate-object-relationship) zurück.

Unterschiedliche Pfade für Nutzerbeziehungen

Lese- und Schreibvorgänge für Nutzerbeziehungen verwenden bewusst unterschiedliche Endpunktpfade:

  • Lesen: GET /data_objects/objects/{type_name}/{object_id}/user_relationships
  • Schreiben: POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users

Beziehungsattribute sind von Objektattributen getrennt

  • Beziehungsendpunkte geben Attribute auf Kantenebene im übergeordneten Feld attributes zurück.
  • Objektattribute bleiben unter to_data_object oder from_data_object verschachtelt.
  • PUT ersetzt die attributes der Beziehung, PATCH führt die attributes der Beziehung zusammen.

Praxisbeispiel

Dieses Beispiel zeigt einen typischen Account-Workflow:

  1. Erstellen Sie account/acct-123.
  2. Erstellen Sie account/acct-456 als untergeordneten Account.
  3. Verknüpfen Sie eine:n Nutzer:in mit acct-123 über rel_kind: account_user.
  4. Verknüpfen Sie acct-123 mit acct-456 über rel_kind: subaccount.

So lesen Sie die Verknüpfungen wieder aus:

  • GET /data_objects/objects/account/acct-123/user_relationships für verknüpfte Nutzer:innen
  • GET /data_objects/objects/account/acct-123/object_relationships für ausgehende Objektverknüpfungen
  • GET /data_objects/objects/account/acct-456/object_relationships?anchor=target für eingehende Objektverknüpfungen

Bulk-Endpunkte

Verwenden Sie die Bulk-Endpunkte, um Datenobjekte, Objektbeziehungen und Nutzerbeziehungen stapelweise aus Ihren eigenen Systemen zu synchronisieren. Jede Anfrage erstellt, ersetzt oder löscht bis zu 50 Datensätze, und Braze verarbeitet den Batch im Hintergrund.

Methode Endpunkt Zweck
PUT /data_objects/objects Bis zu 50 Datenobjekte beliebiger Typen erstellen oder ersetzen
DELETE /data_objects/objects Bis zu 50 Datenobjekte beliebiger Typen löschen
PUT /data_objects/object_relationships Bis zu 50 Objekt-zu-Objekt-Beziehungen erstellen oder ersetzen
DELETE /data_objects/object_relationships Bis zu 50 Objekt-zu-Objekt-Beziehungen löschen
PUT /data_objects/user_relationships Bis zu 50 Nutzer-zu-Objekt-Beziehungen erstellen oder ersetzen
DELETE /data_objects/user_relationships Bis zu 50 Nutzer-zu-Objekt-Beziehungen löschen

Wann Sie die Bulk-Endpunkte verwenden sollten

Verwenden Sie die Bulk-Endpunkte, wenn Sie viele Datensätze aus Ihren eigenen Systemen synchronisieren und nicht jede Änderung angewendet sein muss, bevor die Antwort zurückkommt. Verwenden Sie die Einzeldatensatz-Endpunkte, wenn die Änderung sofort sichtbar sein soll, wenn Sie Datensätze lesen müssen oder wenn Sie mit PATCH nur einige Attribute eines Datensatzes aktualisieren möchten.

Die Bulk-Endpunkte unterscheiden sich von den Einzeldatensatz-Endpunkten in folgenden Punkten:

  • Die Verarbeitung erfolgt asynchron. Eine 202-Antwort bedeutet, dass Braze den Batch angenommen und in die Warteschlange gestellt hat, nicht dass die Datensätze bereits angewendet wurden. Erst bei der Verarbeitung des Batches prüft Braze, ob Typen, Beziehungstypen, Objekte und Nutzer:innen existieren und ob die Attribute den Feldern des Typs entsprechen. Eine Anfrage, die 202 zurückgibt, kann daher später noch Fehler für einzelne Datensätze verursachen.
  • Die Validierung erfolgt nach dem Alles-oder-nichts-Prinzip. Wenn ein Datensatz in einer Anfrage die Validierung nicht besteht, lehnt Braze die gesamte Anfrage mit 400 ab, speichert nichts und listet alle Fehler auf.
  • Datensätze werden nach Eingangszeit sortiert. Braze versieht jeden Datensatz mit dem Zeitpunkt, zu dem die Anfrage eingegangen ist. Senden Sie daher kein updated_at. Wenn zwei Anfragen denselben Datensatz ändern, setzt sich die Anfrage durch, die Braze später erhalten hat.
  • Datensätze können auf Abhängigkeiten warten. Das Löschen eines Objekts oder einer Beziehung, die noch nicht existiert, sowie eine Beziehung, deren Objekt oder Nutzer:in noch nicht existiert, wartet, statt sofort fehlzuschlagen. Braze wiederholt den Vorgang etwa 40 Stunden lang (10 Versuche). Ein Objekt-Upsert wartet nie.
  • Die Bulk-Endpunkte verwenden eigene API-Schlüssel-Berechtigungen und teilen sich ein Rate-Limit von 1.000 Anfragen pro Minute und Workspace.
  • Die Bulk-Endpunkte erstellen niemals Datenobjekttypen. Jeder type_name muss bereits existieren.

Die Produktlimits gelten für die Bulk-Endpunkte auf dieselbe Weise wie für die Einzeldatensatz-Endpunkte.

Paginierung und Datenaktualität

Dieser Abschnitt beschreibt, wie die Paginierung bei Listen funktioniert und wann geschriebene Daten voraussichtlich sichtbar sind.

  • Listen-Endpunkte unterstützen limit und offset.
  • limit ist standardmäßig 100 und wird auf einen Wert zwischen 1 und 250 begrenzt.
  • offset ist standardmäßig 0. Negative Werte werden auf 0 angehoben.
  • Schreibvorgänge für einzelne Datensätze sind sofort für Lesevorgänge und die Liquid-Personalisierung sichtbar. Bulk-Schreibvorgänge werden angewendet, sobald Braze den Batch aus der Warteschlange verarbeitet.
  • Die Segment-Mitgliedschaft auf Basis von Datenobjekten kann bis zu einer Stunde verzögert sein, da berechnete Filter stündlich aktualisiert werden.

Fehlerverhalten

Dieser Abschnitt fasst die Status- und Fehlerantwortmuster zusammen, die bei allen Endpunkten für Datenobjekte verwendet werden.

  • 404, 409, 422 und 429 geben ein errors-Array mit id und message zurück.
  • 400, 401 und 403 geben einen einzelnen error-String zurück.
  • Die Bulk-Endpunkte geben 400- und 500-Fehler als errors-Array mit id und message zurück. Ein 400-Fehler enthält zusätzlich den fehlerhaften parameter, sofern vorhanden, und bei Fehlern auf Datensatzebene den index des Datensatzes.
  • 422 bedeutet, dass die Anfrage ein Produktlimit überschreiten würde. Die Standardwerte der Limits variieren je nach Vertrag Ihres Unternehmens.

New Stuff!