新しいユーザーエイリアスを作成する

このエンドポイントを使用して、既存の識別済みユーザーに新しいユーザーエイリアスを追加するか、新しい未識別ユーザーを作成します。

リクエストごとに最大50個のユーザーエイリアスを指定できます。

既存のユーザーにユーザーエイリアスを追加するには、新しいユーザーエイリアスオブジェクトにexternal_idを含める必要があります。オブジェクトにexternal_idが存在しても、そのexternal_idを持つユーザーがいない場合、エイリアスはどのユーザーにも追加されません。external_idが存在しない場合でもユーザーは作成されますが、後で識別する必要があります。これは「Identifying Users」とusers/identifyエンドポイントを使用して行うことができます。

エイリアスのみの新規ユーザーを作成するには、新しいユーザーエイリアスオブジェクトからexternal_idを省略する必要があります。ユーザーが作成されたら、/users/trackエンドポイントを使用してエイリアスのみのユーザーに属性、イベント、購入を関連付け、/users/identifyエンドポイントを使用してexternal_idでユーザーを識別します。

alias_labelとalias_nameが既に存在する場合

alias_labelとalias_nameの組み合わせは、ユーザー群全体で一意である必要があります。詳細については、ユーザーエイリアスを参照してください。

alias_labelとalias_nameのペアが既にいずれかのユーザーに存在するリクエストを送信した場合（同じユーザーか別のユーザーかを問わず）、エンドポイントは成功レスポンスを返します（例："aliases_processed": 1、"message": "success"）。この場合、リクエスト内のユーザーに新しいエイリアスは追加されません。alias_labelとalias_nameのペアが既に使用されているため、リクエストは変更を行わず、該当ユーザーにエイリアスが追加されなかったように見えることがあります。

前提条件

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

レート制限

このエンドポイントには、1分あたり20,000リクエストの共有レート制限が適用されます。このレート制限は、APIレート制限に記載されているように、/users/delete、/users/identify、/users/merge、および/users/alias/updateエンドポイントと共有されます。

リクエスト本文

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
{
  "user_aliases" : (required, array of new user alias object)
}

リクエストパラメーター

新しいユーザーエイリアスオブジェクトを指定したエンドポイントリクエスト本文

1
2
3
4
5
{
  "external_id" : (optional, string),
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

リクエスト例

1
2
3
4
5
6
7
8
9
10
11
12
curl --location --request POST 'https://rest.iad-01.braze.com/users/alias/new' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "user_aliases" :[
    {
      "external_id": "external_identifier",
      "alias_name" : "example_name",
      "alias_label" : "example_label"
    }
  ]
}'

レスポンス

同じalias_labelとalias_nameが既にユーザーに存在するためにエイリアスがスキップされた場合でも、レスポンス本文は成功を示すことがあります。詳細については、エイリアスラベルと名前が既に存在する場合を参照してください。

1
2
3
4
{
    "aliases_processed": 1,
    "message": "success"
}

トラブルシューティング

このエンドポイントでユーザーエイリアスを作成した後、属性が更新されないのはなぜですか？

これは通常、/users/alias/newの後に別の/users/trackリクエストを送信してエイリアスで属性を更新しようとした場合に発生します。Brazeが新しいalias_labelとalias_nameのペアをプロファイルに一貫して解決できるようになる前にトラックリクエストが処理されるため、属性が期待するユーザーに反映されません。

推奨されるアプローチ： エイリアスのみのプロファイルを作成する場合、または既に存在するエイリアスでプロファイルを更新する場合にのみ、単一の/users/track呼び出しを使用してください。attributes配列内で、user_aliasとプロファイルフィールドを同じユーザー属性オブジェクトに配置することで、Brazeがユーザーの解決と更新の適用を1つのステップで行います。

そのオブジェクトからエイリアスのみのプロファイルを作成する必要がある場合は、_update_existing_onlyをfalseに設定してください。user_aliasを使用しているときにこれを省略すると、Brazeはデフォルトで更新のみの動作となり、エイリアスのみのプロファイルは作成されません。エイリアスがワークスペース内のユーザーに既に存在する場合、同じリクエストでそのプロファイルが新しい属性で更新されます。

/users/trackを使用して、external_idで識別された既存のユーザーに新しいエイリアスを追加することはできません。ユーザー属性オブジェクトでは、external_idとuser_aliasは相互に排他的です。識別済みユーザーにエイリアスを追加するには、まず/users/alias/newを呼び出してください。エイリアスが関連付けられた後、/users/trackでexternal_idまたは既存のエイリアスを使用してそのプロファイルを更新できます。

たとえば、以下の/users/track本文は、エイリアスがまだ存在しない場合はエイリアスのみのプロファイルを作成し、そのエイリアスを既に持つ既存のプロファイルがある場合はそのプロファイルを更新します。

1
2
3
4
5
6
7
8
9
10
11
12
{
  "attributes": [
    {
      "user_alias": {
        "alias_name": "[email protected]",
        "alias_label": "email"
      },
      "_update_existing_only": false,
      "string_attribute": "test_alias_only_update"
    }
  ]
}