Skip to content

識別子によるユーザープロファイルのエクスポート

post

/users/export/ids

このエンドポイントを使用して、ユーザー識別子を指定して任意のユーザープロファイルからデータをエクスポートします。

1つのリクエストには、最大50個のexternal_idsまたはuser_aliasesを含めることができます。device_idemail_address、またはphoneを指定する場合、リクエストごとにこれらの識別子のうち1つのみを含めることができます。

前提条件

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

レート制限

2024年8月22日以降にBrazeにオンボーディングした場合、このエンドポイントには、APIレート制限に記載されているように、1分あたり250リクエストのレート制限が適用されます。

以下の要件を満たすことで、このエンドポイントのレート制限を1秒あたり40リクエストまで引き上げることもできます。

  • ワークスペースにデフォルトのレート制限(1分あたり250リクエスト)が有効になっていること。既存のレート制限の解除についてサポートが必要な場合は、担当のBrazeアカウントマネージャーにお問い合わせください。
  • リクエストに、受け取りたいすべてのフィールドを列挙する fields_to_export パラメーターが含まれていること。

リクエスト本文

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": (optional, array of strings) Name of user data fields to export
}

リクエストパラメーター

パラメーター 必須 データタイプ 説明
external_ids オプション 文字列の配列 エクスポートするユーザーの外部識別子。
user_aliases オプション ユーザーエイリアスオブジェクトの配列 エクスポートするユーザーのユーザーエイリアス
device_id オプション 文字列 getDeviceIdなどのさまざまなSDKメソッドによって返されるデバイス識別子。
braze_id オプション 文字列 特定のユーザーのBraze識別子。
email_address オプション 文字列 ユーザーのメールアドレス。
phone オプション E.164形式の文字列 ユーザーの電話番号。
fields_to_export オプション* 文字列の配列 エクスポートするユーザーデータフィールドの名前。

*このフィールドは、1秒あたり40リクエストの高速レート制限を使用するために必要です。省略した場合、1分あたり250リクエストのデフォルトレート制限が代わりに使用されます。

*2024年8月22日以降にBrazeにオンボーディングした顧客には必須です。

リクエスト例

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: 最終セッションの日付

すべてのフィールドは文字列です。
attributed_campaign 文字列 アトリビューション統合からのデータ(設定されている場合)。特定の広告キャンペーンの識別子。
attributed_source 文字列 アトリビューション統合からのデータ(設定されている場合)。広告が表示されたプラットフォームの識別子。
attributed_adgroup 文字列 アトリビューション統合からのデータ(設定されている場合)。キャンペーンの下のオプションのサブグループの識別子。
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 Identifier for Vendor(存在する場合)
- idfa: (iOS) Identifier for Advertising(存在する場合)
- device_id: (Android) Brazeデバイス識別子
- google_ad_id: (Android) Google Play Advertising Identifier(存在する場合)
- roku_ad_id: (Roku) Roku Advertising Identifier
- ad_tracking_enabled: デバイスで広告トラッキングが有効になっている場合、trueまたはfalse
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 整数 ユーザーの乱数バケット番号。ランダムユーザーの均一分布セグメントを作成するために使用されます。
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
{
    "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または空であると見なされます):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
{
    "created_at": (string),
    "external_id" : (string),
    "user_aliases" : [
      {
        "alias_name" : (string),
        "alias_label" : (string)
      }
    ],
    "braze_id": (string),
    "first_name" : (string),
    "last_name" : (string),
    "email" : (string),
    "dob" : (string) date for the user's date of birth,
    "home_city" : (string),
    "country" : (string) ISO-3166-1 alpha-2 standard,
    "phone" : (string),
    "language" : (string) ISO-639-1 standard,
    "time_zone" : (string),
    "last_coordinates" : (array of float) [lon, lat],
    "gender" : (string) "M" | "F",
    "total_revenue" : (float),
    "attributed_campaign" : (string),
    "attributed_source" : (string),
    "attributed_adgroup" : (string),
    "attributed_ad" : (string),
    "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "custom_attributes" : (object) custom attribute key-value pairs,
    "custom_events" : [
      {
        "name" : (string),
        "first" : (string) date,
        "last" : (string) date,
        "count" : (int)
      },
      ...
    ],
    "purchases" : [
      {
        "name" : (string),
        "first" : (string) date,
        "last" : (string) date,
        "count" : (int)
      },
      ...
    ],
    "devices" : [
      {
        "model" : (string),
        "os" : (string),
        "carrier" : (string),
        "idfv" : (string) only included for iOS devices when IDFV collection is enabled,
        "idfa" : (string) only included for iOS devices when IDFA collection is enabled,
        "google_ad_id" : (string) only included for Android devices when Google Play Advertising Identifier collection is enabled,
        "roku_ad_id" : (string) only included for Roku devices,
        "ad_tracking_enabled" : (boolean)
      },
      ...
    ],
    "push_tokens" : [
      {
        "app" : (string) app name,
        "platform" : (string),
        "token" : (string),
        "device_id": (string),
        "notifications_enabled": (boolean) whether foreground push notifications are enabled for this token. `true` means foreground push is enabled for the token, and `false` means foreground push is disabled (for example, background-only). This is device-level and doesn't indicate the user's global push subscription status
      },
      ...
    ],
    "apps" : [
      {
        "name" : (string),
        "platform" : (string),
        "version" : (string),
        "sessions" : (integer),
        "first_used" : (string) date,
        "last_used" : (string) date
      },
      ...
    ],
    "campaigns_received" : [
      {
        "name" : (string),
        "last_received" : (string) date,
        "engaged" :
         {
           "opened_email" : (boolean),
           "opened_push" : (boolean),
           "clicked_email" : (boolean),
           "clicked_triggered_in_app_message" : (boolean)
          },
          "converted" : (boolean),
          "api_campaign_id" : (string),
          "variation_name" : (optional, string) exists only if it is a multivariate campaign,
          "variation_api_id" : (optional, string) exists only if it is a multivariate campaign,
          "in_control" : (optional, boolean) exists only if it is a multivariate campaign
        },
      ...
    ],
    "canvases_received": [
      {
        "name": (string),
        "api_canvas_id": (string),
        "last_received_message": (string) date,
        "last_entered": (string) date,
        "variation_name": (string),
        "in_control": (boolean),
        "last_exited": (string) date,
        "steps_received": [
          {
            "name": (string),
            "api_canvas_step_id": (string),
            "last_received": (string) date
          },
          {
            "name": (string),
            "api_canvas_step_id": (string),
            "last_received": (string) date
          },
          {
            "name": (string),
            "api_canvas_step_id": (string),
            "last_received": (string) date
          }
        ]
      },
      ...
    ],
    "cards_clicked" : [
      {
        "name" : (string)
      },
      ...
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
{
    "created_at" : "2020-07-10 15:00:00.000 UTC",
    "external_id" : "A8i3mkd99",
    "user_aliases" : [
      {
        "alias_name" : "user_123",
        "alias_label" : "amplitude_id"
      }
    ],
    "braze_id": "5fbd99bac125ca40511f2cb1",
    "random_bucket" : 2365,
    "first_name" : "Jane",
    "last_name" : "Doe",
    "email" : "[email protected]",
    "dob" : "1980-12-21",
    "home_city" : "Chicago",
    "country" : "US",
    "phone" : "+442071838750",
    "language" : "en",
    "time_zone" : "Eastern Time (US & Canada)",
    "last_coordinates" : [41.84157636433568, -87.83520818508256],
    "gender" : "F",
    "total_revenue" : 65,
    "attributed_campaign" : "braze_test_campaign_072219",
    "attributed_source" : "braze_test_source_072219",
    "attributed_adgroup" : "braze_test_adgroup_072219",
    "attributed_ad" : "braze_test_ad_072219",
    "push_subscribe" : "opted_in",
    "push_opted_in_at": "2020-01-26T22:45:53.953Z",
    "email_subscribe" : "subscribed",
    "custom_attributes":
    {
      "loyaltyId": "37c98b9d-9a7f-4b2f-a125-d873c5152856",
      "loyaltyPoints": "321",
       "loyaltyPointsNumber": 107
    },
    "custom_events": [
      {
        "name": "Loyalty Acknowledgement",
        "first": "2021-06-28T17:02:43.032Z",
        "last": "2021-06-28T17:02:43.032Z",
        "count": 1
      },
      ...
    ],
    "purchases": [
      {
        "name": "item_40834",
        "first": "2021-09-05T03:45:50.540Z",
        "last": "2022-06-03T17:30:41.201Z",
        "count": 10
      },
      ...
    ],
    "devices": [
      {
        "model": "Pixel XL",
        "os": "Android (Q)",
        "carrier": null,
        "device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
        "ad_tracking_enabled": true
      },
      ...
    ],
    "push_tokens": [
      {
        "app": "MovieCanon",
        "platform": "Android",
        "token": "12345abcd",
        "device_id": "312ef2c1-83db-4789-967-554545a1bf7a",
        "notifications_enabled": true
      },
      ...
    ],
    "apps": [
      {
        "name": "MovieCannon",
        "platform": "Android",
        "version": "3.29.0",
        "sessions": 1129,
        "first_used": "2020-02-02T19:56:19.142Z",
        "last_used": "2021-11-11T00:25:19.201Z"
      },
      ...
    ],
    "campaigns_received": [
      {
        "name": "Email Unsubscribe",
        "api_campaign_id": "d72fdc84-ddda-44f1-a0d5-0e79f47ef942",
        "last_received": "2022-06-02T03:07:38.105Z",
        "engaged":
        {
           "opened_email": true
        },
        "converted": true,
        "multiple_converted":
        {
          "Primary Conversion Event - A": true
        },
        "in_control": false,
        "variation_name": "Variant 1",
        "variation_api_id": "1bddc73a-a134-4784-9134-5b5574a9e0b8"
      },
      ...
    ],
    "canvases_received": [
      {
        "name": "Non Global  Holdout Group 4/21/21",
        "api_canvas_id": "46972a9d-dc81-473f-aa03-e3473b4ed781",
        "last_received_message": "2021-07-07T20:46:24.136Z",
        "last_entered": "2021-07-07T20:45:24.000+00:00",
        "variation_name": "Variant 1",
        "in_control": false,
        "last_entered_control_at": null,
        "last_exited": "2021-07-07T20:46:24.136Z",
        "steps_received": [
          {
            "name": "Step",
            "api_canvas_step_id": "43d1a349-c3c8-4be1-9fbe-ce708e4d1c39",
            "last_received": "2021-07-07T20:46:24.136Z"
          },
          ...
        ]
      }
      ...
    ],
    "cards_clicked" : [
      {
        "name" : "Loyalty Promo"
      },
      ...
    ]
}
New Stuff!