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 disponibles pour tous, mais votre espace de travail doit être provisionné pour les comptes avant que vous puissiez utiliser ces endpoints. Pour demander le provisionnement, accédez à Paramètres des données > Comptes et remplissez le questionnaire. Une fois le provisionnement terminé, les permissions de clé API des objets de données apparaissent dans Paramètres > Clés API. Pour plus de détails, consultez Activer les comptes.

Endpoints de type

• 

  GET : Lister les types d’objets de données
• 

  GET : Obtenir un type d’objet de données
• 

  GET : Lister les types de relations utilisateur
• 

  GET : Lister les types de relations entre objets

Endpoints d’objet

• 

  GET : Lister les objets de données
• 

  GET : Obtenir un objet de données
• 

  POST : Créer un objet de données
• 

  PUT : Remplacer un objet de données
• 

  PATCH : Mettre à jour un objet de données
• 

  DELETE : Supprimer un objet de données

Endpoints de relations entre objets

• 

  GET : Lister les relations entre objets
• 

  POST : Créer une relation entre objets
• 

  PUT : Remplacer une relation entre objets
• 

  PATCH : Mettre à jour une relation entre objets
• 

  DELETE : Supprimer une relation entre objets

Endpoints de relations utilisateur

• 

  GET : Lister les relations utilisateur
• 

  POST : Créer une relation utilisateur
• 

  PUT : Remplacer une relation utilisateur
• 

  PATCH : Mettre à jour une relation utilisateur
• 

  DELETE : Supprimer une relation 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 une erreur 403.

Permissions des clés 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é.

Remarque

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

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.

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

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

1
2
3
4
5
6
7
8

{
  "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 qui se passe lorsque vous en atteignez une. Pour savoir comment ces limites s’appliquent aux enregistrements de compte, consultez Limites des objets de compte.

Limites de nombre

Sauf mention 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 votre équipe de compte Braze pour demander une augmentation.

Limites des champs et des valeurs

Ces limites sont fixes pour toutes les entreprises.

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 :

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"
    }
  ]
}

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 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, par exemple avec 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 principaux identifiants 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.
• braze_id : ID utilisateur Braze utilisé sur les endpoints de relations utilisateur.
• 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 d’anchor avant que vous n’utilisiez 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 liaison vous permet de faire dans Braze. Vous définissez les types dans le tableau de bord, puis vous écrivez les enregistrements et les liens qui les unissent à 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 valides et sont gérés dans le tableau de bord.
• Les arêtes de relation sont les liens réels entre les enregistrements. Elles sont créées, mises à jour et supprimées via ces endpoints de l’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 exigent related_type_name

• rel_kind n’est pas unique pour l’ensemble des 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.
• Les écritures de relations entre objets exigent 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 détermine le sens de la relation

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

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 de premier niveau attributes.
• 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 pour des comptes :

1. Créez account/acct-123.
2. Créez account/acct-456 en tant que compte enfant.
3. Liez un utilisateur à acct-123 avec rel_kind: account_user.
4. Liez 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

Remarque

Les endpoints DELETE des relations entre objets et des relations utilisateur exigent un corps de requête JSON.

Pagination et fraîcheur des données

Cette section décrit le comportement de la pagination des listes et les délais de visibilité des données attendus après une écriture.

• Les endpoints de liste prennent en charge limit et offset.
• limit vaut 100 par défaut et est limité à une plage de 1 à 250.
• offset vaut 0 par défaut, et les valeurs négatives sont ramenées à 0.
• Les écritures sont immédiatement visibles pour les lectures et la personnalisation Liquid.
• L’appartenance à un Segment basée sur les objets de données peut présenter un décalage 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 modèles de statut et de réponse d’erreur utilisés par l’ensemble des endpoints des objets de données.

• Les codes 404, 409, 422 et 429 renvoient un tableau errors contenant id et message.
• Les codes 400, 401 et 403 renvoient une seule chaîne de caractères error.
• Le code 422 signifie que la requête dépasserait une limite du produit. Les valeurs limites par défaut varient selon le contrat de l’entreprise.