Passer au contenu

Endpoints des objets de données

Utilisez ces endpoints pour lister les types d’objets de données, gérer les enregistrements d’objets de données, et gérer les relations entre objets et utilisateurs.

Important

Les objets de données sont actuellement en accès anticipé. Votre espace de travail doit être activé avant que les permissions de clé API des objets de données n’apparaissent dans Paramètres > Clés API.

Endpoints de type

Endpoints d'objet

Endpoints de relations objet

Endpoints de relations utilisateur

URL de base et authentification

Utilisez l’endpoint REST de votre espace de travail et envoyez Authorization: Bearer YOUR_REST_API_KEY. Cette section explique où les endpoints des objets de données sont hébergés et comment les requêtes sont authentifiées.

Pour les hôtes des endpoints, consultez l’aperçu de l’API Braze.
Tous les payloads de requête et de réponse sont au format JSON.
Les requêtes sont limitées à l’espace de travail propriétaire de la clé API.
Si la clé possède une liste d’adresses IP autorisées, les adresses IP non autorisées renvoient une erreur 403.

Permissions de clé API

Cette section associe chaque endpoint à la permission requise afin que vous puissiez définir la portée de vos clés API en toute sécurité.

Permission	Groupe d’endpoints
`data_objects.read`	Lecture des types et des objets, et lecture des relations entre objets
`data_objects.create`	Création d’objets
`data_objects.update`	Remplacement et mise à jour d’objets
`data_objects.delete`	Suppression d’objets
`data_objects.user_relationships.read`	Lecture des relations utilisateur
`data_objects.user_relationships.create`	Création de relations utilisateur
`data_objects.user_relationships.update`	Remplacement et mise à jour de relations utilisateur
`data_objects.user_relationships.delete`	Suppression de relations utilisateur
`data_objects.object_relationships.create`	Création de relations entre objets
`data_objects.object_relationships.update`	Remplacement et mise à jour de relations entre objets
`data_objects.object_relationships.delete`	Suppression de relations entre objets

Remarque

La lecture des relations entre objets utilise data_objects.read. Il n’existe pas de permission data_objects.object_relationships.read.

Limites de débit

Cette section explique les quotas de requêtes par défaut et les en-têtes de réponse pour le trafic en lecture et en écriture.

Compartiment	Limite par défaut
Lecture des objets de données	50 requêtes par minute
Écriture des objets de données	50 requêtes par minute

Chaque réponse inclut X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.

Pour les requêtes limitées, Braze renvoie un code 429 et un payload d’erreur contenant id et message.

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

Limites du produit

Cette section répertorie les limites appliquées par Braze aux objets de données et ce à quoi vous pouvez vous attendre lorsque vous en atteignez une.

Limites de nombre

Ces limites s’appliquent à votre entreprise dans son ensemble, sauf indication contraire. Votre équipe de compte Braze peut ajuster les valeurs par défaut pour votre entreprise.

Limite	Valeur par défaut
Enregistrements d’objets de données par entreprise (tous les espaces de travail confondus)	1 000 000
Champs par type d’objet de données	500
Objets de données liés à un utilisateur	1 000
Utilisateurs liés à un objet de données	10 000
Relations entre objets pour un objet de données	1 000

Limites des champs et des valeurs

Ces limites sont fixes pour toutes les entreprises.

Limite	Valeur
Longueur de la valeur d’attribut	255 caractères
Longueur et format de l’`object_id`	250 caractères. Lettres, chiffres, tirets et underscores uniquement.
Longueur et format du nom de champ	250 caractères. Lettres, chiffres et underscores uniquement, et ne peut pas commencer par un underscore.
Noms de champs réservés	`id`, `external_id`, `object_id` et `display_name` ne peuvent pas être utilisés comme noms de champs personnalisés.

Ce qui se passe lorsque vous atteignez une limite

Une requête qui dépasserait une limite de nombre renvoie 422 avec un id d’erreur qui identifie la limite :

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

Limite	`id` d’erreur
Enregistrements d’objets de données par entreprise	`data-object-record-limit-exceeded`
Champs par type d’objet de données	`data-object-field-limit-exceeded`
Objets de données liés à un utilisateur	`data-objects-per-user-limit-exceeded`
Utilisateurs liés à un objet de données	`users-per-data-object-limit-exceeded`
Relations entre objets pour un objet de données	`data-object-relationship-limit-exceeded`

Vos enregistrements et relations existants restent en place — seule la requête qui dépasserait la limite est rejetée. Pour libérer de l’espace sous une limite, supprimez les enregistrements dont vous n’avez plus besoin ou retirez les relations que vous n’utilisez plus. Pour augmenter une limite de nombre, contactez votre équipe de compte Braze.

Les requêtes qui échouent à la validation, comme un object_id ou une valeur d’attribut trop longue, renvoient 400. Les requêtes dépassant la limite de débit renvoient 429.

Concepts fondamentaux

Cette section définit les identifiants clés utilisés dans tous les endpoints des objets de données.

type_name : Le nom machine du type d’objet de données, unique au sein d’un espace de travail.
object_id : Votre identifiant d’objet, unique au sein d’un type.
braze_id : L’ID utilisateur Braze utilisé sur les endpoints de relations utilisateur.
attributes : Objet indexé par nom de champ ou données de relation validées par rapport au schéma configuré.

Fonctionnement des relations

Cette section explique les types de relations, les arêtes de relations et le comportement de anchor avant de consulter les pages de référence des endpoints.

Aperçu du modèle de relations

Utilisez ce diagramme pour voir comment les types, les enregistrements et les relations s’articulent ensemble, et ce que leur liaison vous permet de faire dans Braze. Vous définissez les types dans le tableau de bord, puis vous créez les enregistrements et les liens entre eux via ces endpoints.

%%{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

Les types et les arêtes sont distincts

Les types de relations définissent les liens valides et sont gérés dans le tableau de bord.
Les arêtes de relations sont les liens réels entre les enregistrements et sont créées, mises à jour et supprimées via ces endpoints API.
Avant d’écrire des relations, listez les valeurs rel_kind valides avec :
- GET /data_objects/types/{type_name}/user_relationship_types
- GET /data_objects/types/{type_name}/object_relationship_types

Pourquoi les relations entre objets nécessitent `related_type_name`

rel_kind n’est pas globalement unique pour toutes les paires de types d’objets. Par exemple, rel_kind peut être subaccount pour une paire de types d’objets et partner_account pour une autre.
Les écritures de relations entre objets nécessitent donc à la fois rel_kind et related_type_name pour identifier le type de relation visé ainsi que l’autre type d’objet dans l’association.
Si related_type_name ne correspond pas au type de relation pour ce rel_kind, la requête renvoie 400.

`anchor` contrôle la direction de la relation

Les relations entre objets sont directionnelles. L’objet de l’URL est interprété en fonction de anchor.

`anchor`	Rôle de l’objet URL	Clé de l’objet lié dans les réponses
`source` (par défaut)	Côté « de » (arête sortante)	`to_data_object`
`target`	Côté « vers » (arête entrante)	`from_data_object`

Créer la même arête depuis la perspective d’ancre opposée cible toujours une seule relation sous-jacente. Un second appel de création pour la même arête renvoie 409 (duplicate-object-relationship).

Asymétrie des chemins pour les relations utilisateur

Les lectures et écritures de relations utilisateur utilisent intentionnellement des chemins d’endpoint différents :

Lecture : GET /data_objects/objects/{type_name}/{object_id}/user_relationships
Écriture : POST|PUT|PATCH|DELETE /data_objects/objects/{type_name}/{object_id}/users

Les attributs de relation sont distincts des attributs d’objet

Les endpoints de relations renvoient les attributs au niveau de l’arête dans le champ attributes de premier niveau.
Les attributs de l’objet restent imbriqués sous to_data_object ou from_data_object.
PUT remplace les attributes de la relation, et PATCH fusionne les attributes de la relation.

Exemple pratique

Cet exemple illustre un workflow de compte courant :

Créer account/acct-123.
Créer account/acct-456 en tant que compte enfant.
Lier un utilisateur à acct-123 avec rel_kind: account_user.
Lier acct-123 à acct-456 avec rel_kind: subaccount.

Pour relire les liens :

GET /data_objects/objects/account/acct-123/user_relationships pour les utilisateurs liés
GET /data_objects/objects/account/acct-123/object_relationships pour les liens d’objets sortants
GET /data_objects/objects/account/acct-456/object_relationships?anchor=target pour les liens d’objets entrants