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.

Endpoints d’objet

Endpoints de relations entre objets

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ù sont hébergés les endpoints des objets de données et comment les requêtes sont authentifiées.

  • Pour connaître 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é dispose d’une liste d’adresses IP autorisées, les adresses IP qui n’y figurent pas renvoient 403.

Permissions de la clé API

Cette section associe chaque endpoint à la permission requise, afin que vous puissiez limiter 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
data_objects.bulk_upsert Création ou remplacement d’objets en masse
data_objects.bulk_delete Suppression d’objets en masse
data_objects.object_relationships.bulk_upsert Création ou remplacement de relations entre objets en masse
data_objects.object_relationships.bulk_delete Suppression de relations entre objets en masse
data_objects.user_relationships.bulk_upsert Création ou remplacement de relations utilisateur en masse
data_objects.user_relationships.bulk_delete Suppression de relations utilisateur en masse

Limites de débit

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

Compartiment Limite par défaut
Lectures d’objets de données 1 000 requêtes par minute
Écritures d’objets de données 1 000 requêtes par minute
Écritures en masse d’objets de données 1 000 requêtes par minute, partagées entre les six endpoints en masse et avec les synchronisations d’objets de données via l’ingestion de données cloud

La limite d’écriture en masse s’applique par espace de travail et est distincte de la limite d’écriture d’un enregistrement unique.

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

Lorsqu’une requête est limitée, 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 1000 requests per minute."
    }
  ]
}

Limites du produit

Cette section répertorie les limites que Braze applique aux objets de données et ce à quoi vous attendre lorsque vous en atteignez une. Pour savoir comment ces limites s’appliquent aux enregistrements de comptes, consultez la section Limites des objets de compte.

Limites de nombre

Sauf indication contraire, ces limites s’appliquent à l’ensemble de votre entreprise. Il s’agit de capacités de départ. Si vous avez besoin de plus d’enregistrements ou d’une limite plus élevée, contactez l’équipe de gestion de votre compte Braze pour demander une augmentation.

Limite Valeur par défaut
Enregistrements d’objets de données par entreprise (tous espaces de travail confondus) 50 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
Champs par type de relation (relations utilisateur et relations entre objets) 25. Les champs de relation ne sont pas pris en compte dans la limite de champs par type d’objet de données.
Longueur d’une valeur d’attribut 255 caractères
Longueur et format de object_id 250 caractères. Lettres, chiffres, traits d’union et traits de soulignement uniquement.
Longueur et format des noms de champs 250 caractères. Lettres, chiffres et traits de soulignement uniquement ; ne peut pas commencer par un trait de soulignement.
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.

Que se passe-t-il lorsque vous atteignez une limite ?

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

{
  "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
Champs par type de relation 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 la place sous une limite, supprimez les enregistrements dont vous n’avez plus besoin ou les relations que vous n’utilisez plus. Pour augmenter une limite de nombre, contactez l’équipe de gestion de votre compte Braze.

Les requêtes dont la validation échoue, par exemple un object_id ou une valeur d’attribut trop long, renvoient une erreur 400. Les requêtes qui dépassent la limite de débit renvoient une erreur 429.

Concepts de base

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

  • type_name : 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.
  • user : L’utilisateur concerné par une requête d’écriture de relation utilisateur, identifié par un seul élément parmi external_id, braze_id, alias, email ou phone.
  • attributes : Données d’objet ou de relation indexées par nom de champ et validées par rapport au schéma configuré.

Fonctionnement des relations

Cette section présente les types de relations, les arêtes de relation et le comportement du paramètre anchor. Lisez-la avant de consulter les pages de référence des endpoints.

Aperçu du modèle de relations

Ce diagramme montre comment les types, les enregistrements et les relations s’articulent, et ce que leur mise en relation vous permet de faire dans Braze. Vous définissez les types dans le tableau de bord, puis vous écrivez les enregistrements et les liens entre eux à l’aide de 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 autorisés et se gèrent dans le tableau de bord.
  • Les arêtes de relation sont les liens réels entre les enregistrements. Elles se créent, se mettent à jour et se suppriment via ces endpoints d’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
  • rel_kind n’est pas unique à l’échelle de toutes les paires de types d’objets. Par exemple, rel_kind peut valoir subaccount pour une paire de types d’objets et partner_account pour une autre.
  • L’écriture d’une relation entre objets nécessite donc à la fois rel_kind et related_type_name pour identifier le type de relation visé ainsi que l’autre type d’objet de l’association.
  • Si related_type_name ne correspond pas au type de relation associé à ce rel_kind, la requête renvoie 400.

anchor contrôle le sens de la relation

Les relations entre objets sont orientées. L’objet indiqué dans l’URL est interprété en fonction de anchor.

anchor Rôle de l’objet de l’URL Clé de l’objet associé dans les réponses
source (par défaut) Côté origine (arête sortante) to_data_object
target Côté destination (arête entrante) from_data_object

Créer la même arête depuis la perspective d’ancrage opposée cible toujours une seule et même 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 les écritures de relations utilisateur utilisent volontairement 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 relation renvoient les attributs propres à l’arête dans le champ attributes de premier niveau.
  • Les attributs d’objet restent imbriqués sous to_data_object ou from_data_object.
  • PUT remplace les attributes de la relation, tandis que PATCH les fusionne.

Exemple concret

Cet exemple illustre un flux de travail courant autour des comptes :

  1. Créez account/acct-123.
  2. Créez account/acct-456 en tant que compte enfant.
  3. Associez un utilisateur à acct-123 avec rel_kind: account_user.
  4. Associez acct-123 à acct-456 avec rel_kind: subaccount.

Pour relire les liens :

  • GET /data_objects/objects/account/acct-123/user_relationships pour les utilisateurs associé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

Endpoints en masse

Utilisez les endpoints en masse pour synchroniser par lots des objets de données, des relations entre objets et des relations utilisateur depuis vos propres systèmes. Chaque requête crée, remplace ou supprime jusqu’à 50 enregistrements, et Braze traite le lot en arrière-plan.

Méthode Endpoint Objectif
PUT /data_objects/objects Créer ou remplacer jusqu’à 50 objets de données, tous types confondus
DELETE /data_objects/objects Supprimer jusqu’à 50 objets de données, tous types confondus
PUT /data_objects/object_relationships Créer ou remplacer jusqu’à 50 relations entre objets
DELETE /data_objects/object_relationships Supprimer jusqu’à 50 relations entre objets
PUT /data_objects/user_relationships Créer ou remplacer jusqu’à 50 relations entre utilisateurs et objets
DELETE /data_objects/user_relationships Supprimer jusqu’à 50 relations entre utilisateurs et objets

Quand utiliser les endpoints en masse

Utilisez les endpoints en masse lorsque vous synchronisez de nombreux enregistrements depuis vos propres systèmes et que vous n’avez pas besoin que chaque modification soit appliquée avant le retour de la réponse. Utilisez les endpoints à enregistrement unique lorsque la modification doit être visible immédiatement, lorsque vous devez lire des enregistrements ou lorsque vous souhaitez mettre à jour seulement certains attributs d’un enregistrement avec PATCH.

Les endpoints en masse se distinguent des endpoints à enregistrement unique sur les points suivants :

  • Le traitement est asynchrone. Une réponse 202 signifie que Braze a accepté le lot et l’a placé en file d’attente, et non qu’il a appliqué les enregistrements. Braze vérifie l’existence des types, des types de relation, des objets et des utilisateurs, ainsi que la correspondance des attributs avec les champs du type, au moment du traitement du lot. Une requête qui renvoie 202 peut donc encore entraîner des échecs pour certains enregistrements par la suite.
  • La validation fonctionne en tout ou rien. Si un seul enregistrement d’une requête échoue à la validation, Braze rejette l’ensemble de la requête avec une erreur 400, n’enregistre rien et liste toutes les erreurs.
  • Les enregistrements sont ordonnés selon leur heure de réception. Braze horodate chaque enregistrement avec l’heure à laquelle il a reçu la requête : n’envoyez donc pas updated_at. Lorsque deux requêtes modifient le même enregistrement, c’est celle reçue en dernier par Braze qui l’emporte.
  • Les enregistrements peuvent attendre leurs dépendances. La suppression d’un objet ou d’une relation qui n’existe pas encore, ainsi qu’une relation dont l’objet ou l’utilisateur n’existe pas encore, est mise en attente au lieu d’échouer immédiatement. Braze effectue de nouvelles tentatives pendant environ 40 heures (10 tentatives). L’upsert d’un objet n’est jamais mis en attente.
  • Les endpoints en masse utilisent leurs propres autorisations de clé API et partagent une limite de débit de 1 000 requêtes par minute et par espace de travail.
  • Les endpoints en masse ne créent jamais de types d’objets de données. Chaque type_name doit déjà exister.

Les limites du produit s’appliquent aux endpoints en masse de la même manière qu’aux endpoints à enregistrement unique.

Pagination et fraîcheur des données

Cette section décrit le fonctionnement de la pagination des listes et le délai de visibilité des données après une écriture.

  • Les endpoints de liste prennent en charge limit et offset.
  • limit vaut 100 par défaut et est ramené à une valeur comprise entre 1 et 250.
  • offset vaut 0 par défaut, et toute valeur négative est ramenée à 0.
  • Les écritures d’enregistrements individuels sont immédiatement visibles pour les lectures et la personnalisation Liquid. Les écritures en masse sont appliquées lorsque Braze traite le lot en file d’attente.
  • L’appartenance aux Segments basée sur les objets de données peut accuser un retard allant jusqu’à une heure, car les filtres calculés sont actualisés toutes les heures.

Comportement en cas d’erreur

Cette section résume les codes de statut et les formats de réponse d’erreur communs aux endpoints des objets de données.

  • Les erreurs 404, 409, 422 et 429 renvoient un tableau errors contenant id et message.
  • Les erreurs 400, 401 et 403 renvoient une seule chaîne de caractères error.
  • Les endpoints groupés renvoient les erreurs 400 et 500 sous la forme d’un tableau errors contenant id et message. Une erreur 400 inclut également le parameter en cause, s’il y en a un, ainsi que l’index de l’enregistrement pour les erreurs propres à un enregistrement.
  • Une erreur 422 signifie que la requête dépasserait une limite du produit. Les valeurs limites par défaut dépendent du contrat de l’entreprise.

New Stuff!