識別子によるユーザープロファイルのエクスポート
/users/export/ids
このエンドポイントを使用して、ユーザー識別子を指定して任意のユーザープロファイルからデータをエクスポートします。
1 つのリクエストには、最大 50 個の external_ids
または user_aliases
を含めることができます。device_id
、email_address
、または phone
を指定する場合は、リクエストごとにいずれか 1 つの識別子のみを含めることができます。
前提条件
このエンドポイントを使用するには、API キーとusers.export.ids
の権限が必要です。
レート制限
2024年8月22日以降に Braze にオンボーディングした場合、このエンドポイントには、API レート制限に記載されているように、1分あたり250リクエストのレート制限が適用されます。
Request body
1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
7
8
9
{
"external_ids": (optional, array of strings) External identifiers for users you wish to export,
"user_aliases": (optional, array of user alias objects) user aliases for users to export,
"device_id": (optional, string) Device identifier as returned by various SDK methods such as `getDeviceId`,
"braze_id": (optional, string) Braze identifier for a particular user,
"email_address": (optional, string) Email address of user,
"phone": (optional, string) Phone number of user,
"fields_to_export": (required, array of strings) Name of user data fields to export
}
2024年8月22日以降に Braze にオンボーディングした顧客については、リクエストパラメータfields_to_export
が必要です。
リクエストパラメーター
パラメーター | required | データ型 | 説明 |
---|---|---|---|
external_ids |
オプション | 文字列の配列 | エクスポートするユーザーの外部識別子s。 |
user_aliases |
オプション | ユーザー別名オブジェクトの配列 | エクスポートするユーザーのユーザーエイリアス。 |
device_id |
オプション | 文字列 | getDeviceId などのさまざまな SDK メソッドによって返されるデバイス識別子。 |
braze_id |
オプション | 文字列 | 特定のユーザーのBraze 識別子。 |
email_address |
オプション | 文字列 | ユーザーのメールアドレス。 |
phone |
オプション | E.164形式の文字列 | ユーザーの電話番号。 |
fields_to_export |
必須 | 文字列の配列 | エクスポートするユーザーデータ フィールドの名前。 |
例のリクエスト
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/ids' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"external_ids": ["user_identifier1", "user_identifier2"],
"user_aliases": [
{
"alias_name": "example_alias",
"alias_label": "example_label"
}
],
"device_id": "1234567",
"braze_id": "braze_identifier",
"email_address": "[email protected]",
"phone": "11112223333",
"fields_to_export": ["first_name", "email", "purchases"]
}'
エクスポートするフィールド
以下は、有効なfields_to_export
のリストです。fields_to_export
を使用して返されるデータを最小限に抑えると、このAPI エンドポイントのレスポンスタイムが向上します。
エクスポートするフィールド | データタイプ | 説明 |
---|---|---|
apps |
配列 | このユーザーがセッションを記録したアプリケーション。これには次のフィールドが含まれます。 - name : アプリ名- platform : アプリ プラットフォーム(iOS、Android、またはWeb など)- version :アプリのバージョン番号または名前 - sessions : このアプリの総セッション数- first_used : 初回セッションの日付- last_used : 最終セッションの日付すべてのフィールドsはストリングです。 |
attributed_campaign |
文字列 | アトリビューション積分からのデーター(設定されている場合)。特定の広告キャンペーンのID。 |
attributed_source |
文字列 | アトリビューション積分からのデーター(設定されている場合)。広告が表示されたプラットフォームのID。 |
attributed_adgroup |
文字列 | アトリビューション積分からのデーター(設定されている場合)。キャンペーン の下のオプションのサブグループのID。 |
attributed_ad |
文字列 | アトリビューション積分からのデーター(設定されている場合)。キャンペーンと広告グループの下にある任意のサブグループの識別子。 |
push_subscribe |
文字列 | ユーザーのプッシュサブスクリプションステータス。 |
email_subscribe |
文字列 | ユーザーのメールサブスクリプションステータス。 |
braze_id |
文字列 | このユーザーにBrazeで設定されたデバイス固有の一意のユーザー 識別子。 |
country |
文字列 | ISO 3166-1 alpha-2 標準を使用するユーザーの国。 |
created_at |
文字列 | ユーザープロファイルが作成された日時 (ISO 8601形式)。 |
custom_attributes |
オブジェクト | このユーザーのカスタム属性キーと値のペア。 |
custom_events |
配列 | 過去 90 日間にこのユーザーに帰属するカスタム イベント。 |
devices |
配列 | ユーザーのデバイスに関する情報。プラットフォームに応じて、次の情報が含まれます。 - model :デバイスのモデル名- os :装置のオペレーティングシステム- carrier :デバイスのサービスキャリア (利用可能な場合)- idfv : (iOS) Braze デバイス識別子、ベンダーの Apple 識別子 (存在する場合)- idfa : (iOS) Advertising の識別子(存在する場合)- device_id :(Android)Braze機器識別子- google_ad_id :(Android)グーグルプレイ広告識別子(存在する場合)- roku_ad_id :(Roku) Roku 広告識別子- ad_tracking_enabled :デバイスで広告”トラッキングが有効になっている場合、真または偽になることがあります |
dob |
文字列 | YYYY-MM-DD 形式のユーザーの生年月日。 |
email |
文字列 | ユーザーのメールアドレス。 |
external_id |
文字列 | 識別されたユーザー固有のユーザー識別子。 |
first_name |
文字列 | ユーザーの名。 |
gender |
文字列 | ユーザーの性別。可能な値は次のとおりです。 - M : 男性- F : 女性- O : その他- N : 該当なし- P : 言いたくない- nil :不明 |
home_city |
文字列 | ユーザーの所在地。 |
language |
文字列 | ISO-639-1 規格のユーザー言語。 |
last_coordinates |
浮動小数点の配列 | [longitude, latitude] としてフォーマットされたユーザーの最新のデバイスの場所。 |
last_name |
文字列 | ユーザの姓。 |
phone |
文字列 | E.164 形式のユーザーの電話番号。 |
purchases |
配列 | このユーザーは過去90日間に購入しました。 |
push_tokens |
配列 | アプリの通知の送信先を指定する一意の匿名識別子。 |
random_bucket |
整数 | ユーザーの乱数バケット番号。乱数ユーザーsの一様分布Segmentsを作成するために使用されます。 |
time_zone |
文字列 | IANAタイムゾーンデータベースと同じ形式のユーザーのタイムゾーン。 |
total_revenue |
フロート | このユーザーに帰属する総収益。総収益は、受領したキャンペーンおよびキャンバスのコンバージョン期間中に行われたユーザーの購入に基づいて計算されます。 |
uninstalled_at |
タイムスタンプ | ユーザーがアプリをアンインストールした日時。アプリがアンインストールされていない場合は省略されます。 |
user_aliases |
オブジェクト | alias_name およびalias_label を含むユーザーエイリアスオブジェクト (存在する場合)。 |
/users/export/ids
エンドポイントは、受信したすべてのキャンペーンやキャンバス、実行されたすべてのカスタムイベント、作成されたすべての購入、すべてのカスタム属性などのデータを含む、このユーザーのユーザープロファイル全体をまとめることに注意してください。このため、このエンドポイントは他の REST API エンドポイントよりも低速になります。
要求されたデータによっては、この API エンドポイントでは1分あたり 250 件のリクエストのレート制限があるため、ニーズを満たすには不十分な場合があります。このエンドポイントを定期的に使用してユーザーをエクスポートすることを想定している場合は、代わりに、非同期で大規模なデータプルに最適化されているセグメント別にユーザーをエクスポートすることを検討してください。
応答
1
2
3
4
5
6
7
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"message": (required, string) the status of the export, returns 'success' when completed without errors,
"users" : (array of object) the data for each of the exported users, may be empty if no users are found,
"invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}
このエンドポイントからアクセスできるデータの例については、次の例を参照してください。
サンプルユーザーのエクスポートファイルアウトプット
ユーザー・エクスポート・オブジェクト(可能な限り最小限のデータを含める。オブジェクトにフィールドがない場合は、NULLまたは空であると仮定する):
CSV および API のエクスポートに関するヘルプについては、「エクスポートのトラブルシューティング」を参照してください。