Créer ou remplacer des objets de données en masse
/data_objects/objects
Utilisez cet endpoint pour créer ou remplacer jusqu’à 50 objets de données, de types éventuellement différents, en une seule requête.

Data Objects est disponible pour tous, mais votre espace de travail doit être provisionné pour Accounts avant que vous puissiez utiliser cet endpoint. Pour demander le provisionnement, allez dans Paramètres des données > Comptes et remplissez le questionnaire. Pour en savoir plus, consultez la section Activer Accounts.
Braze accepte la requête et la traite en arrière-plan. Une réponse 202 signifie que le lot est mis en file d’attente, et non qu’il est appliqué. Pour modifier un seul objet de données et voir le changement immédiatement, utilisez Remplacer un objet de données. Pour savoir quand utiliser chacun d’eux, consultez la section Endpoints en masse.
Conditions préalables
Pour utiliser cet endpoint, vous avez besoin d’une clé API disposant de l’autorisation data_objects.bulk_upsert. Les autorisations portant sur un seul enregistrement, comme data_objects.create, ne donnent pas accès à cet endpoint.
Limite de débit
Cet endpoint fait partie du compartiment d’écriture en masse de Data Objects, avec une limite par défaut de 1 000 requêtes par minute et par espace de travail. Cette limite est partagée entre les six endpoints en masse ainsi qu’avec les synchronisations d’objets de données via Cloud Data Ingestion. Elle est distincte de la limite d’écriture pour un seul enregistrement.
Paramètres de la requête
Le tableau suivant répertorie et décrit les paramètres du corps de requête JSON pour l’endpoint /data_objects/objects.
| Paramètre | Obligatoire | Type de données | Description |
|---|---|---|---|
records |
Obligatoire | Tableau | Les objets de données à créer ou à remplacer. Doit contenir de 1 à 50 enregistrements. Braze rejette tout autre champ de premier niveau. |
records[].type_name |
Obligatoire | Chaîne de caractères | Le nom machine du type d’objet de données. Le type doit déjà exister. Cet endpoint ne crée jamais de types. |
records[].object_id |
Obligatoire | Chaîne de caractères | Votre identifiant pour l’objet, soit la même valeur que object_id dans les chemins des endpoints pour un seul enregistrement |
records[].attributes |
Obligatoire | Objet | Les attributs de l’objet, indexés par nom de champ. Chaque champ doit déjà être défini sur le type. |
Traitement du lot par Braze
- La validation est globale. Si un seul enregistrement échoue à la validation, Braze rejette l’ensemble de la requête avec un code
400, n’enregistre rien et liste toutes les erreurs. Corrigez les erreurs et renvoyez la requête complète. - Les vérifications ont lieu pendant le traitement. Braze vérifie l’existence de chaque type et la correspondance des attributs avec les champs du type au moment où il traite le lot. Une requête qui renvoie
202peut donc tout de même entraîner des échecs ultérieurs pour certains enregistrements. Consultez la section Échecs de traitement. - 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. Braze rejette toute requête qui l’inclut. Lorsque deux requêtes modifient le même objet, c’est celle reçue en dernier par Braze qui l’emporte, et Braze ignore une écriture plus ancienne qui arrive après coup. - Les upserts n’attendent pas. Un upsert d’objet n’attend jamais un autre enregistrement. Un upsert reçu après la suppression du même objet recrée cet objet.
Exemple de requête
Cette section contient un exemple de payload JSON et un exemple de requête cURL.
Exemple de payload de requête
{
"records": [
{"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
{"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
]
}
Exemple de requête cURL
Cet exemple crée ou remplace un enregistrement account et un enregistrement opportunity dans la même requête.
curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/objects' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"records": [
{"type_name": "account", "object_id": "acct-001", "attributes": {"name": "Acme"}},
{"type_name": "opportunity", "object_id": "opp-001", "attributes": {"amount": 10}}
]
}'
Réponse
Cette section contient un exemple de réponse réussie ainsi que les champs de la réponse.
Exemple de réponse réussie
Le code de statut 202 peut renvoyer le corps de réponse suivant.
{
"source_import_id": "api-20261022T153012123456-9f3a1c2b",
"status": "queued",
"record_count": 2
}
Paramètres de la réponse
Le tableau suivant répertorie et décrit les champs d’une réponse réussie.
| Paramètre | Obligatoire | Type de données | Description |
|---|---|---|---|
source_import_id |
Obligatoire | Chaîne de caractères | L’identifiant généré par Braze pour cette requête. Chaque requête constitue son propre import. |
status |
Obligatoire | Chaîne de caractères | Toujours queued. Le lot est accepté et en attente de traitement. |
record_count |
Obligatoire | Entier | Le nombre d’enregistrements dans la requête |
Échecs de traitement
Braze ne renvoie pas ces codes depuis l’endpoint. Il les enregistre pour les enregistrements concernés lorsqu’il traite un lot mis en file d’attente.
| Code | Signification |
|---|---|
data-object-type-not-found |
type_name ne correspond à aucun type actif dans l’espace de travail. |
data-object-schema-mismatch |
Les attributes ne correspondent pas aux champs du type. Le message indique chaque attribut en cause. |
data-object-ingestion-rejected |
Tout autre rejet, par exemple un object_id refusé. |
Erreurs
Une réponse 400 signifie que Braze n’a rien enregistré. Chaque erreur comporte un id, un message, le parameter en cause le cas échéant et, pour les erreurs au niveau d’un enregistrement, l’index de l’enregistrement (sa position dans records, à partir de 0).
Le tableau suivant répertorie les erreurs courantes pour cet endpoint et la manière de les résoudre.
| Statut | Cause | Recommandation |
|---|---|---|
400 |
Requête non valide (invalid-request) : le corps n’est pas un objet JSON ou contient du JSON mal formé, records est absent ou contient moins de 1 ou plus de 50 entrées, ou le corps contient un champ défini par Braze (source_type, source_import_id, source_chunk_id ou record_type) |
Envoyez un objet JSON dont le seul champ est records, avec 1 à 50 enregistrements. |
400 |
Incompatibilité de schéma (schema-mismatch) : un enregistrement ne contient pas un champ obligatoire, contient un champ non reconnu (y compris updated_at), ou contient un champ du mauvais type ou une chaîne vide |
Corrigez chaque enregistrement listé et renvoyez la requête complète. |
401 |
Clé REST API manquante ou non valide | Vérifiez que l’en-tête Authorization utilise Bearer YOUR_REST_API_KEY et que la clé est active. |
403 |
La clé API ne dispose pas de l’autorisation requise ou la requête est bloquée par la liste d’autorisation | Vérifiez que la clé dispose de data_objects.bulk_upsert et que votre IP source figure dans la liste d’autorisation de la clé, si elle est configurée. |
404 |
Data Objects n’est pas activé pour votre entreprise | Vérifiez que votre espace de travail est provisionné pour Accounts. |
429 |
Limite de débit dépassée | Réessayez après X-RateLimit-Reset et réduisez la fréquence des requêtes. |
500 |
Le lot n’a pas pu être accepté (internal-error) |
Braze n’a rien accepté : vous pouvez donc réessayer la requête sans risque. |