外部IDの名前を変更する

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

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

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

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

前提条件

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

レート制限

要求本文:

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,000 リクエスト/分超)

よくある質問

これは MAU に影響しますか?
いいえ。ユーザー数は変わらないため、新しいexternal_id が追加されるだけです。

ユーザーの行動は長期的に変化していますか?
いや、ユーザーは変わらないし、過去の行動もすべてつながっている。

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

これはデータポイントを消費しますか?
この機能はデータポイントを消費しません。

推奨される償却期間は？
非推奨の外部IDをいつまで残しておけるかについての厳しい制限はないが、非推奨のIDでユーザーを参照する必要がなくなったら、削除することを強く推奨する。