Renommer des ID externes

Utilisez cet endpoint pour renommer les ID externes de vos utilisateurs.

Vous pouvez envoyer jusqu’à 50 objets de renommage par requête.

Cet endpoint définit un nouvel external_id (principal) pour l’utilisateur et rend son external_id existant obsolète. Cela signifie que l’utilisateur peut être identifié par l’un ou l’autre des external_id jusqu’à ce que celui qui est obsolète soit supprimé. Le fait de disposer de plusieurs ID externes permet de prévoir une période de migration, de sorte que les versions antérieures de vos applications qui utilisent l’ancien schéma de dénomination des ID externes ne soient pas interrompues.

Une fois que votre ancien schéma de nommage n’est plus utilisé, nous vous recommandons vivement de supprimer les ID externes obsolètes à l’aide de l’endpoint /users/external_ids/remove.

Avertissement

Assurez-vous de supprimer les ID externes obsolètes à l’aide de l’endpoint /users/external_ids/remove plutôt que /users/delete. L’envoi d’une requête à /users/delete avec l’ID externe obsolète supprime entièrement le profil utilisateur et cette action ne peut pas être annulée.

Conditions préalables

Pour utiliser cet endpoint, vous aurez besoin d’une clé API avec l’autorisation users.external_ids.rename.

Limite de débit

Nous appliquons une limite de débit de 1 000 requêtes par minute à cet endpoint, comme documenté dans Limites de débit de l’API.

Corps de la requête

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3
{
  "external_id_renames" : (required, array of external ID rename objects)
}

Paramètres de requête

Notez ce qui suit :

• Le current_external_id doit être l’ID principal de l’utilisateur et ne peut pas être un ID obsolète.
• Le new_external_id ne doit pas être déjà utilisé en tant qu’ID principal ou ID obsolète.
• Le current_external_id et le new_external_id ne peuvent pas être identiques.

Exemple de requête

1
2
3
4
5
6
7
8
9
10
11
curl --location --request POST 'https://rest.iad-01.braze.com/users/external_ids/rename' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "external_id_renames" :[
    {
      "current_external_id": "existing_external_id",
      "new_external_id" : "new_external_id"
    }
  ]
}'

Réponse

La réponse confirmera tous les renommages réussis, ainsi que les renommages échoués avec les erreurs associées. Les messages d’erreur dans le champ rename_errors font référence à l’index de l’objet dans le tableau de la requête d’origine.

1
2
3
4
5
{
  "message" : (string) status message,
  "external_ids" : (array of strings) successful rename operations,
  "rename_errors": (array of arrays) <minor error message>
}

Le champ message renverra success pour toute requête valide. Des erreurs plus spécifiques sont capturées dans le tableau rename_errors. Le champ message renvoie une erreur dans les cas suivants :

• Clé API non valide
• Tableau external_id_renames vide
• Tableau external_id_renames contenant plus de 50 objets
• Limite de débit atteinte (plus de 1 000 requêtes par minute)

Foire aux questions

Cela a-t-il un impact sur les MAU ?

Non, car le nombre d’utilisateurs reste le même ; ils ont simplement un nouvel external_id.

Le comportement des utilisateurs change-t-il rétroactivement ?

Non, car l’utilisateur est toujours le même et tout son comportement historique lui reste associé.

Peut-on l’exécuter sur des espaces de travail de développement ou de mise à l’essai ?

Oui. En fait, nous vous recommandons vivement d’effectuer un test de migration sur un espace de travail de développement ou de mise à l’essai, et de vous assurer que tout s’est bien déroulé avant d’exécuter la migration sur les données de production.

Cette fonctionnalité enregistre-t-elle des points de données ?

Cette fonctionnalité n’enregistre pas de points de données.

Quel est le délai d’obsolescence recommandé ?

Nous n’imposons pas de limite stricte quant à la durée pendant laquelle vous pouvez conserver des ID externes obsolètes, mais nous vous recommandons vivement de les supprimer dès qu’il n’est plus nécessaire de référencer les utilisateurs par l’ID obsolète.