Datenobjekt-Endpunkte

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

Wichtig

Datenobjekte sind allgemein verfügbar, aber Ihr Workspace muss für Accounts bereitgestellt sein, bevor Sie diese Endpunkte verwenden können. Um die Bereitstellung anzufordern, gehen Sie zu Dateneinstellungen > Accounts und füllen Sie den Fragebogen aus. Nach Abschluss der Bereitstellung werden die API-Schlüssel-Berechtigungen für Datenobjekte unter Einstellungen > API-Schlüssel angezeigt. Weitere Informationen finden Sie unter Accounts aktivieren.

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 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 Übersicht über die Braze API.
• Alle Anfrage- und Antwort-Payloads sind JSON.
• Anfragen sind auf den Workspace beschränkt, dem der API-Schlüssel gehört.
• Wenn für den Schlüssel eine IP-Allowlist konfiguriert ist, geben Anfragen von IP-Adressen, die nicht auf der Allowlist stehen, 403 zurück.

API-Schlüssel-Berechtigungen

Dieser Abschnitt ordnet jedem Endpunkt die erforderliche Berechtigung zu, damit Sie den Umfang von API-Schlüsseln sicher festlegen können.

Hinweis

Für das Lesen von Objektbeziehungen wird data_objects.read verwendet. Eine Berechtigung data_objects.object_relationships.read gibt es nicht.

Rate-Limits

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

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.

1
2
3
4
5
6
7
8

{
  "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 passiert, wenn Sie ein Limit erreichen. Wie diese Limits für Kontodatensätze gelten, erfahren Sie unter Limits für Kontoobjekte.

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 anzufragen.

Feld- und Wertlimits

Diese Limits sind für alle Unternehmen fest vorgegeben.

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 betreffende Limit angibt:

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 unter einem Limit wieder Platz zu schaffen, löschen Sie Datensätze, die Sie nicht mehr benötigen, oder entfernen Sie Beziehungen, die Sie nicht mehr verwenden. Um ein Mengenlimit zu erhöhen, wenden Sie sich an Ihr Braze-Account-Team.

Anfragen, die die Validierung nicht bestehen, etwa wegen einer zu langen object_id oder eines zu langen Attributwerts, 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 Objektbezeichner, eindeutig innerhalb eines Typs.
• braze_id: Die Braze-Nutzer-ID, die in Endpunkten für Nutzer:innenbeziehungen verwendet wird.
• attributes: Nach Feldnamen geschlüsselte Objekt- oder Beziehungsdaten, die anhand des konfigurierten Schemas validiert werden.

So funktionieren Beziehungen

Dieser Abschnitt erläutert Beziehungstypen, Beziehungskanten und das Verhalten von anchor, bevor Sie die Referenzseiten zu den Endpunkten verwenden.

Übersicht über das Beziehungsmodell

Dieses Diagramm zeigt, wie Typen, Datensätze und Beziehungen zusammenhängen und was Sie in Braze durch deren Verknüpfung erreichen können. Sie definieren die Typen im Dashboard und schreiben anschließend die Datensätze und 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 legen fest, 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 die gültigen rel_kind-Werte mit folgenden Endpunkten auf:
  • 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 über alle Paare von Objekttypen hinweg global eindeutig. So kann rel_kind beispielsweise 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 beabsichtigten Beziehungstyp zusammen mit dem anderen Objekttyp in der Verknüpfung zu identifizieren.
• Wenn related_type_name nicht zum Beziehungstyp für dieses rel_kind passt, gibt die Anfrage 400 zurück.

anchor steuert die Beziehungsrichtung

Objektbeziehungen sind gerichtet. Das Objekt in der URL wird anhand von anchor interpretiert.

Wenn Sie dieselbe Kante aus der entgegengesetzten Anchor-Perspektive erstellen, bezieht sich dies weiterhin auf eine einzige zugrunde liegende Beziehung. Ein zweiter Erstellungsaufruf für dieselbe Kante gibt 409 (duplicate-object-relationship) zurück.

Unterschiedliche Pfade für Nutzer:innenbeziehungen

Lese- und Schreibvorgänge für Nutzer:innenbeziehungen 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 Beziehungs-attributes, und PATCH führt die Beziehungs-attributes zusammen.

Ausführliches Beispiel

Dieses Beispiel zeigt einen gängigen Konto-Workflow:

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

Hinweis

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

Paginierung und Datenaktualität

Dieser Abschnitt beschreibt das Paginierungsverhalten von Listen und den erwarteten Zeitpunkt, ab dem Daten nach Schreibvorgängen sichtbar sind.

• List-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, und negative Werte werden auf 0 angehoben.
• Schreibvorgänge sind sofort für Lesevorgänge und die Liquid-Personalisierung sichtbar.
• Die Segment-Zugehörigkeit 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 von 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.
• 422 bedeutet, dass die Anfrage ein Produktlimit überschreiten würde. Die Standardwerte der Limits variieren je nach Vertrag des Unternehmens.