Renommer des ID externes

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

Vous pouvez envoyer jusqu’à 50 objets renommés par demande.

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é. La présence de plusieurs ID externes permet de prévoir une période de migration pour que les versions antérieures de vos applications qui utilisent l’ancien schéma de nommage des ID externes ne s’interrompent pas.

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.

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

We apply a rate limit of 1,000 requests per minute to this endpoint, as documented in API rate limits.

Corps de la demande

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 demande

• 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 déjà être utilisé comme ID principal ou ID obsolète
• Les current_external_id et new_external_id ne peuvent pas être identiques

Exemple de demande

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 et les renommages infructueux avec toutes les erreurs associées. Les messages d’erreur dans le champ rename_errors référenceront l’index de l’objet dans le tableau de la demande 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 toutes les demandes valides. Des erreurs plus spécifiques sont saisies 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 avec plus de 50 objets
• Atteinte de la limite de débit (plus de 1 000 requêtes/minute)

Foire aux questions

Cela a-t-il un impact sur le MAU ?
Non, puisque le nombre d’utilisateurs restera le même, ils auront simplement un nouvel external_id.

Le comportement des utilisateurs change-t-il au cours du temps ?
Non, étant donné que l’utilisateur est toujours le même et que tous ses comportements historiques sont toujours liés à lui.

Est-il possible de l’exécuter sur des espaces de travail de développement/préproduction ?
Oui. En fait, nous vous recommandons vivement d’effectuer un test de migration sur un espace de travail de développement ou de mise à disposition, et de vous assurer que tout s’est bien déroulé avant d’exécuter la migration sur les données de production.

Est-ce que cela consomme des points de données ?
Cette fonctionnalité ne coûte pas de points de données.

Quel est le délai d’obsolescence recommandé ?
Nous n’avons pas de limite stricte quant à la durée pendant laquelle vous pouvez conserver des ID externes dépréciés, mais nous vous recommandons vivement de les supprimer lorsqu’il n’est plus nécessaire de référencer les utilisateurs par l’ID déprécié.