外部IDの名前を変更する

このエンドポイントを使用して、ユーザーのexternal IDの名前を変更します。

1回のリクエストで最大50個の名前変更オブジェクトを送信できます。

このエンドポイントは、ユーザーに新しい（プライマリ）external_idを設定し、既存のexternal_idを非推奨にします。つまり、非推奨のIDが削除されるまで、どちらのexternal_idでもユーザーを識別できるということです。複数のexternal IDを持つことで、以前のexternal ID命名スキーマを使用しているレガシーバージョンのアプリが壊れないように、移行期間を設けることができます。

古い命名スキーマが使用されなくなった後は、/users/external_ids/removeエンドポイントを使用して非推奨のexternal IDを削除することを強く推奨します。

警告

非推奨のexternal IDは、/users/deleteではなく/users/external_ids/removeエンドポイントを使用して削除してください。非推奨のexternal IDを使用して/users/deleteにリクエストを送信すると、ユーザープロファイルは完全に削除され、元に戻すことはできません。

前提条件

このエンドポイントを使用するには、users.external_ids.rename権限を持つAPIキーが必要です。

レート制限

APIレート制限に記載されているように、このエンドポイントには1分あたり1,000リクエストのレート制限が適用されます。

リクエスト本文

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)
}

リクエストパラメーター

以下の点に注意してください。

• current_external_idはユーザーのプライマリIDである必要があり、非推奨IDにすることはできません。
• new_external_idは、プライマリIDまたは非推奨IDとしてすでに使用されているものであってはなりません。
• current_external_idとnew_external_idを同じにすることはできません。

リクエスト例

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"
    }
  ]
}'

応答

この応答は、成功したすべての名前変更と、関連するエラーを伴う失敗した名前変更を確認します。rename_errorsフィールドのエラーメッセージは、元のリクエストの配列内のオブジェクトのインデックスを参照します。

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>
}

messageフィールドは、有効なリクエストに対してはsuccessを返します。より具体的なエラーはrename_errors配列に格納されます。messageフィールドは、以下の場合にエラーを返します。

• 無効なAPIキー
• 空のexternal_id_renames配列
• 50を超えるオブジェクトを持つexternal_id_renames配列
• レート制限に到達（1分あたり1,000件以上のリクエスト）

よくある質問

MAUに影響しますか？

いいえ。ユーザー数は変わらず、新しいexternal_idが設定されるだけです。

ユーザーの行動履歴は変わりますか？

いいえ。ユーザー自体は同じであり、すべての行動履歴は引き続きそのユーザーに紐づいています。

開発ワークスペースまたはステージングワークスペースで実行できますか？

はい。実際、ステージングまたは開発ワークスペースでテスト移行を実行し、本番データで実行する前にすべてがスムーズに進んでいることを確認することを強く推奨します。

データポイントは記録されますか？

この機能はデータポイントを記録しません。

推奨される非推奨期間はどのくらいですか？

非推奨のexternal IDをいつまで保持できるかについて厳密な制限はありませんが、非推奨のIDでユーザーを参照する必要がなくなったら、削除することを強く推奨します。