Passer au contenu

Remplacer une relation utilisateur

put

/data_objects/objects/{type_name}/{object_id}/users

Utilisez cet endpoint pour créer ou remplacer une relation utilisateur.

Conditions préalables

Pour utiliser cet endpoint, vous aurez besoin d’une clé API disposant de l’autorisation data_objects.user_relationships.update.

Limite de débit

Cet endpoint fait partie du compartiment d’écriture des objets de données, avec une limite par défaut de 1 000 requêtes par minute.

Paramètres de chemin

Le tableau suivant répertorie et décrit les paramètres de chemin de l’endpoint /data_objects/objects/{type_name}/{object_id}/users.

Paramètre Obligatoire Type de données Description
type_name Obligatoire String Type d’objet
object_id Obligatoire String Identifiant de l’objet

Paramètres de requête

Le tableau suivant répertorie et décrit les paramètres du corps de requête JSON de l’endpoint /data_objects/objects/{type_name}/{object_id}/users.

Paramètre Obligatoire Type de données Description
user Obligatoire Objet L’utilisateur à associer à l’objet. Doit contenir exactement un des identifiants suivants : external_id, braze_id, alias, email ou phone.
user.external_id Facultatif String L’ID externe de l’utilisateur.
user.braze_id Facultatif String L’ID utilisateur Braze.
user.alias Facultatif Objet Objet alias d’utilisateur avec alias_name et alias_label (tous deux obligatoires s’il est utilisé).
user.email Facultatif String L’adresse e-mail de l’utilisateur.
user.phone Facultatif String Le numéro de téléphone de l’utilisateur. Doit pouvoir être converti au format E.164.
rel_kind Obligatoire String Type de relation
attributes Facultatif Objet Attributs de la relation

Identification de l’utilisateur

  • Transmettez exactement un identifiant dans user. Si aucun identifiant non nul n’est fourni, ou s’il y en a plusieurs, une erreur 400 est renvoyée. Les champs d’identifiant nuls accompagnant un identifiant valide sont acceptés.
  • Si une adresse e-mail ou un numéro de téléphone correspond à plusieurs profils utilisateur, Braze choisit l’utilisateur identifié (celui qui possède un external_id). En cas d’égalité persistante, Braze choisit le profil mis à jour le plus récemment.
  • Utilisez external_id lorsqu’il est disponible.

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

{
  "user": {
    "external_id": "user-123"
  },
  "rel_kind": "account_user",
  "attributes": {
    "role": "admin"
  }
}

Autre exemple utilisant un alias d’utilisateur :

{
  "user": {
    "alias": {
      "alias_name": "[email protected]",
      "alias_label": "crm_email"
    }
  },
  "rel_kind": "account_user",
  "attributes": {
    "role": "admin"
  }
}

Exemple de requête cURL

Cet exemple remplace les attributs de la relation account_user entre l’utilisateur et acct-123, en écrasant tous les attributs précédemment enregistrés pour cette relation.

curl --location --request PUT 'https://rest.iad-01.braze.com/data_objects/objects/account/acct-123/users' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "user": {
    "external_id": "user-123"
  },
  "rel_kind": "account_user",
  "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 200 peut renvoyer le corps de réponse suivant.

{
  "user_relationship": {
    "type_name": "account",
    "object_id": "acct-123",
    "rel_kind": "account_user",
    "user": {
      "external_id": "user-123",
      "braze_id": "507f1f77bcf86cd799439011"
    },
    "attributes": { "role": "admin" }
  }
}

Paramètres de 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
user_relationship Obligatoire Objet Enregistrement de la relation utilisateur créée ou remplacée
user_relationship.type_name Obligatoire String Nom machine du type d’objet de données
user_relationship.object_id Obligatoire String Identifiant de l’objet de données
user_relationship.rel_kind Obligatoire String Valeur du type de relation
user_relationship.user Obligatoire Objet Objet utilisateur lié contenant l’identifiant tel qu’envoyé, ainsi que braze_id
user_relationship.attributes Obligatoire Objet Attributs de la relation (toujours présent, objet vide s’il n’y en a aucun)

Erreurs

Le tableau suivant répertorie les erreurs courantes de cet endpoint et la manière de les résoudre.

Statut Cause Recommandation
400 user manquant ou vide, aucun identifiant, plus d’un identifiant, identifiant vide, braze_id, email ou alias mal formé, numéro de téléphone impossible à convertir au format E.164, ou ancien corps avec braze_id au niveau supérieur Envoyez un objet user contenant exactement un identifiant valide.
400 rel_kind inconnu pour le type ou erreur de validation du schéma Vérifiez que rel_kind est valide pour le type d’objet et que attributes correspond au schéma de la relation.
404 Relation, objet ou utilisateur introuvable (user-not-found ou data-object-relationship-not-found) Vérifiez que l’objet, l’utilisateur et les valeurs de clé de la relation existent bien.
422 Limite d’objets par utilisateur atteinte (data-objects-per-user-limit-exceeded) ou limite d’utilisateurs par objet atteinte (users-per-data-object-limit-exceeded) Réduisez le nombre de relations de l’utilisateur ou de l’objet, ou contactez le support Braze au sujet des limites de votre espace de travail.
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 requise ou la requête est bloquée par la liste d’autorisation Vérifiez que la clé dispose de l’autorisation data_objects.user_relationships.update et que votre adresse IP source figure dans la liste d’autorisation de la clé, si celle-ci est configurée.
429 Limite de débit dépassée Réessayez après X-RateLimit-Reset et réduisez la fréquence des requêtes.
New Stuff!