Datenobjekt-Endpunkte

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

Wichtig

Datenobjekte befinden sich derzeit im Early Access. Ihr Workspace muss aktiviert sein, bevor die Datenobjekt-API-Schlüsselberechtigungen unter Einstellungen > API-Schlüssel angezeigt werden.

Typ-Endpunkte

• 

  GET: Datenobjekttypen auflisten
• 

  GET: Datenobjekttyp abrufen
• 

  GET: Nutzer:innenbeziehungstypen auflisten
• 

  GET: Objektbeziehungstypen auflisten

Objekt-Endpunkte

• 

  GET: Datenobjekte auflisten
• 

  GET: Datenobjekt abrufen
• 

  POST: Datenobjekt erstellen
• 

  PUT: Datenobjekt ersetzen
• 

  PATCH: Datenobjekt aktualisieren
• 

  DELETE: Datenobjekt löschen

Objektbeziehungs-Endpunkte

• 

  GET: Objektbeziehungen auflisten
• 

  POST: Objektbeziehung erstellen
• 

  PUT: Objektbeziehung ersetzen
• 

  PATCH: Objektbeziehung aktualisieren
• 

  DELETE: Objektbeziehung löschen

Nutzer:innenbeziehungs-Endpunkte

• 

  GET: Nutzer:innenbeziehungen auflisten
• 

  POST: Nutzer:innenbeziehung erstellen
• 

  PUT: Nutzer:innenbeziehung ersetzen
• 

  PATCH: Nutzer:innenbeziehung aktualisieren
• 

  DELETE: Nutzer:innenbeziehung löschen

Basis-URL und Authentifizierung

Verwenden Sie Ihren Workspace-REST-Endpunkt und senden Sie Authorization: Bearer YOUR_REST_API_KEY. Dieser Abschnitt erklärt, wo Datenobjekte-Endpunkte gehostet werden und wie Anfragen authentifiziert werden.

• Informationen zu Endpunkt-Hosts finden Sie in der Braze-API-Übersicht.
• Alle Anfrage- und Antwort-Payloads sind JSON.
• Anfragen sind auf den Workspace beschränkt, dem der API-Schlüssel gehört.
• Wenn der Schlüssel eine IP-Zulassungsliste hat, geben nicht zugelassene IP-Adressen 403 zurück.

API-Schlüssel-Berechtigungen

In diesem Abschnitt wird jedem Endpunkt die erforderliche Berechtigung zugeordnet, damit Sie API-Schlüssel sicher einschränken können.

Hinweis

Für Objektbeziehungslesevorgänge wird data_objects.read verwendet. Es gibt keine Berechtigung data_objects.object_relationships.read.

Rate-Limits

Dieser Abschnitt erläutert die standardmäßigen Anfragekontingente und Antwort-Header für Lese- und Schreibzugriffe.

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

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

1
2
3
4
5
6
7
8

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

Produktlimits

Dieser Abschnitt beschreibt die Limits, die Braze für Datenobjekte durchsetzt, und was passiert, wenn Sie eines erreichen.

Anzahl-Limits

Diese Limits gelten für Ihr gesamtes Unternehmen, sofern nicht anders angegeben. Ihr Braze-Account-Team kann die Standardwerte für Ihr Unternehmen anpassen.

Feld- und Wertlimits

Diese Limits sind für alle Unternehmen fest vorgegeben.

Was passiert, wenn Sie ein Limit erreichen

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

1
2
3
4
5
6
7
8

{
  "errors": [
    {
      "id": "data-object-record-limit-exceeded",
      "message": "This company has reached its data object record limit"
    }
  ]
}

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

Anfragen, die die Validierung nicht bestehen, z. B. eine zu lange object_id oder ein zu langer Attributwert, geben 400 zurück. Anfragen, die das Rate-Limit überschreiten, geben 429 zurück.

Kernkonzepte

Dieser Abschnitt definiert die wichtigsten Bezeichner, die über alle Datenobjekte-Endpunkte hinweg verwendet werden.

• type_name: Der Maschinenname des Datenobjekttyps, eindeutig innerhalb eines Workspace.
• object_id: Ihr Objektbezeichner, eindeutig innerhalb eines Typs.
• braze_id: Die Braze-Nutzer:innen-ID, die auf Endpunkten für Nutzer:innenbeziehungen verwendet wird.
• attributes: Ein nach Feldnamen strukturiertes Objekt oder Beziehungsdaten, die anhand des konfigurierten Schemas validiert werden.

So funktionieren Beziehungen

Dieser Abschnitt erklärt Beziehungstypen, Beziehungskanten und das Verhalten von anchor, bevor Sie die Endpunkt-Referenzseiten verwenden.

Das Beziehungsmodell auf einen Blick

Verwenden Sie dieses Diagramm, um zu sehen, wie Typen, Datensätze und Beziehungen zusammenpassen und was deren Verknüpfung in Braze ermöglicht. Sie definieren die Typen im Dashboard und schreiben dann die Datensätze sowie die Verknüpfungen zwischen ihnen ü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 definieren, welche Verknüpfungen zulässig sind, und werden im Dashboard verwaltet.
• Beziehungskanten sind die tatsächlichen Verknüpfungen zwischen Datensätzen und werden über diese API-Endpunkte erstellt, aktualisiert und gelöscht.
• Bevor Sie Beziehungen schreiben, listen Sie zulässige rel_kind-Werte auf mit:
  • GET /data_objects/types/{type_name}/user_relationship_types
  • GET /data_objects/types/{type_name}/object_relationship_types

Warum Objektbeziehungen related_type_name erfordern

• rel_kind ist nicht global eindeutig über alle Objekttyppaare hinweg. Zum Beispiel kann rel_kind für ein Paar von Objekttypen subaccount und für ein anderes partner_account sein.
• 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 Zuordnung zu identifizieren.
• Wenn related_type_name nicht mit dem Beziehungstyp für dieses rel_kind übereinstimmt, gibt die Anfrage 400 zurück.

anchor steuert die Beziehungsrichtung

Objektbeziehungen sind gerichtet. Das URL-Objekt wird basierend auf anchor interpretiert.

Das Erstellen derselben Kante aus der entgegengesetzten Anchor-Perspektive zielt weiterhin auf eine zugrunde liegende Beziehung ab. Ein zweiter Erstellungsaufruf für dieselbe Kante gibt 409 (duplicate-object-relationship) zurück.

Pfad-Asymmetrie bei Nutzer:innenbeziehungen

Lese- und Schreibvorgänge für Nutzer:innenbeziehungen verwenden absichtlich 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 attributes-Feld der obersten Ebene zurück.
• Objektattribute bleiben unter to_data_object oder from_data_object verschachtelt.
• PUT ersetzt die attributes der Beziehung, und PATCH führt die attributes der Beziehung zusammen.

Praxisbeispiel

Dieses Beispiel zeigt einen typischen Konto-Workflow:

1. Erstellen Sie account/acct-123.
2. Erstellen Sie account/acct-456 als Unterkonto.
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.

Um die Verknüpfungen auszulesen:

• 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

Hinweis

Die DELETE-Endpunkte für Objektbeziehungen und Nutzer:innenbeziehungen erfordern einen JSON-Anfragekörper.

Paginierung und Datenaktualität

Dieser Abschnitt behandelt das Paginierungsverhalten bei Listen-Endpunkten und die erwartete Sichtbarkeit von Daten nach Schreibvorgängen.

• Listen-Endpunkte unterstützen limit und offset.
• limit ist standardmäßig 100 und wird auf 1 bis 250 begrenzt.
• offset ist standardmäßig 0, und negative Werte werden auf 0 gesetzt.
• Schreibvorgänge sind sofort für Lesevorgänge und Liquid-Personalisierung sichtbar.
• 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 in den Datenobjekte-Endpunkten 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.
• 422 bedeutet, dass die Anfrage ein Produktlimit überschreiten würde. Die Standardlimitwerte variieren je nach Unternehmensvertrag.