Passer au contenu

Créer ou remplacer des relations utilisateur en masse

put

/data_objects/user_relationships

Utilisez cet endpoint pour créer ou remplacer jusqu’à 50 relations entre utilisateurs et objets en une seule requête.

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 appliqué. Pour modifier une seule relation et voir le changement immédiatement, utilisez Remplacer une relation utilisateur. Pour savoir quel endpoint utiliser selon le cas, consultez Endpoints en masse.

Conditions préalables

Pour utiliser cet endpoint, vous avez besoin d’une clé API disposant de l’autorisation data_objects.user_relationships.bulk_upsert. Les autorisations portant sur un seul enregistrement, comme data_objects.user_relationships.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 et avec les synchronisations Cloud Data Ingestion des objets de données. Elle est distincte de la limite d’écriture par enregistrement unique.

Paramètres de requête

Le tableau suivant répertorie et décrit les paramètres du corps de requête JSON pour l’endpoint /data_objects/user_relationships.

Paramètre Requis Type de données Description
records Requis Tableau Les relations utilisateur à créer ou à remplacer. Doit contenir entre 1 et 50 enregistrements. Braze rejette tout autre champ de premier niveau.
records[].type_name Requis Chaîne de caractères Type de l’objet auquel l’utilisateur est associé
records[].object_id Requis Chaîne de caractères Identifiant de l’objet auquel l’utilisateur est associé
records[].rel_kind Requis Chaîne de caractères Nom du type de relation. Pour obtenir la liste des valeurs valides, utilisez Lister les types de relations utilisateur.
records[].user Requis Objet L’utilisateur à associer. Doit contenir exactement un des éléments suivants : external_id, braze_id, email, phone ou alias. En envoyer zéro ou plus d’un génère une erreur.
records[].user.external_id Facultatif Chaîne de caractères L’ID externe de l’utilisateur
records[].user.braze_id Facultatif Chaîne de caractères L’ID utilisateur Braze
records[].user.email Facultatif Chaîne de caractères L’adresse e-mail de l’utilisateur
records[].user.phone Facultatif Chaîne de caractères Le numéro de téléphone de l’utilisateur
records[].user.alias Facultatif Objet Objet d’alias d’utilisateur avec alias_name et alias_label (tous deux requis en cas d’utilisation)
records[].attributes Requis Objet Attributs de la relation, indexés par nom de champ. Envoyez {} si le type de relation n’en comporte aucun.

Lorsqu’une adresse e-mail ou un numéro de téléphone correspond à plusieurs utilisateurs, les règles standard de sélection de profil de Braze déterminent l’utilisateur associé.

Comment Braze traite le lot

  • La validation fonctionne en tout ou rien. Si un enregistrement échoue à la validation, Braze rejette l’ensemble de la requête avec une erreur 400, n’enregistre rien et répertorie toutes les erreurs. Corrigez les erreurs et renvoyez la requête complète.
  • Les vérifications ont lieu pendant le traitement. Au moment où il traite le lot, Braze vérifie que le type, le type de relation, l’objet et l’utilisateur existent, et que les attributs correspondent aux champs du type de relation. Une requête qui renvoie 202 peut donc encore entraîner des échecs pour certains enregistrements par la suite. Consultez É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 la même relation, celle reçue en dernier par Braze l’emporte, et Braze ignore une écriture plus ancienne qui arrive après.
  • Les relations peuvent attendre leur objet et leur utilisateur. 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). Si l’objet ou l’utilisateur n’existe toujours pas au terme de ce délai, l’enregistrement échoue avec data-object-dependency-not-found.

Exemple de requête

Cette section comprend 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",
      "rel_kind": "owns",
      "user": {"external_id": "user-1"},
      "attributes": {"role": "admin"}
    }
  ]
}

Exemple de requête cURL

Cet exemple associe l’utilisateur dont l’ID externe est user-1 à acct-001 avec le type de relation owns, et enregistre son role comme admin.

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/user_relationships' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "records": [
    {
      "type_name": "account",
      "object_id": "acct-001",
      "rel_kind": "owns",
      "user": {"external_id": "user-1"},
      "attributes": {"role": "admin"}
    }
  ]
}'

Réponse

Cette section comprend un exemple de réponse réussie et les champs de la réponse.

Exemple de réponse réussie

Le code de statut 202 pourrait renvoyer le corps de réponse suivant.

{
  "source_import_id": "api-20261022T153012123456-9f3a1c2b",
  "status": "queued",
  "record_count": 1
}

Paramètres de réponse

Le tableau suivant répertorie et décrit les champs d’une réponse réussie.

Paramètre Requis Type de données Description
source_import_id Requis Chaîne de caractères L’identifiant généré par Braze pour cette requête. Chaque requête constitue sa propre importation.
status Requis Chaîne de caractères Toujours queued. Le lot est accepté et en attente de traitement.
record_count Requis 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 chaque enregistrement concerné lorsqu’il traite un lot en file d’attente.

Code Signification
data-object-type-not-found type_name ne désigne aucun type actif dans l’espace de travail.
data-object-relationship-type-not-found rel_kind ne désigne aucun type de relation actif pour ce type.
data-object-schema-mismatch Les attributes ne correspondent pas aux champs du type de relation. Le message indique chaque attribut en cause.
data-object-invalid-user-identifier L’identifiant utilisateur ne permet pas de trouver un utilisateur.
data-object-ingestion-rejected Tout autre rejet.
data-object-dependency-not-found L’objet ou l’utilisateur était toujours introuvable après environ 40 heures de nouvelles tentatives.

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 parameter reprend les noms utilisés dans votre requête, par exemple user.external_id.

{
  "errors": [
    {"index": 0, "id": "schema-mismatch", "parameter": "rel_kind", "message": "rel_kind is required"}
  ]
}

Le tableau suivant répertorie les erreurs courantes pour cet endpoint et explique comment les résoudre.

Statut Cause Recommandation
400 Requête invalide (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 requis, contient un champ non reconnu (y compris updated_at), contient un champ de type incorrect ou une chaîne vide, ou comporte un objet user avec plusieurs identifiants Corrigez chaque enregistrement répertorié et renvoyez la requête complète.
400 Identifiant utilisateur manquant (missing-user-identifier) : l’objet user d’un enregistrement ne comporte aucun identifiant Envoyez exactement un identifiant dans l’objet user de chaque enregistrement.
401 Clé REST API manquante ou invalide 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 nécessaire ou la requête est bloquée par la liste d’autorisation Vérifiez que la clé dispose de data_objects.user_relationships.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 renvoyer la requête sans risque.
New Stuff!