セグメント別ユーザープロファイルのエクスポート
/users/export/segment
このエンドポイントを使用して、セグメント内のすべてのユーザーをエクスポートします。
このエンドポイントを使用する場合は、次の点に注意してください。
1. この API リクエストの fields_to_export フィールドは必須です。
2. custom_events、purchases、campaigns_received、canvases_received のフィールドには、過去90日間のデータのみが含まれます。
ユーザーデータは、改行で区切られたユーザー JSON オブジェクトの複数のファイルとしてエクスポートされます(1行に1つの JSON オブジェクトなど)。データは、自動生成された URL、またはこの統合がすでに設定されている場合は S3 バケットにエクスポートされます。
エクスポートの出力形式: エクスポートが成功し、クラウドストレージ認証情報を設定していない場合、HTTP レスポンスには圧縮アーカイブ(ZIP または GZIP ファイル)をダウンロードするための URL が含まれます。クラウドストレージ認証情報(S3、Azure、または Google Cloud Storage)が設定されている場合、Braze はエクスポートをバケットに直接書き込み、レスポンスにはダウンロード URL は含まれません。エクスポートが失敗した場合は、代わりにメール通知が届きます。クラウドストレージ認証情報を設定すると、大規模なエクスポートで障害が発生する可能性が低くなります。
企業は、このエンドポイントを使用するセグメントごとに、特定の時刻に最大1つのエクスポートを実行できます。エクスポートが完了するのを待ってから、再試行してください。
前提条件
このエンドポイントを使用するには、users.export.segment 権限を持つ API キーが必要です。
レート制限
API レート制限に記載されているように、このエンドポイントにはデフォルトの Braze レート制限(1時間あたり250,000リクエスト)が適用されます。
認証情報ベースの応答の詳細
S3、Azure、または Google Cloud Storage の認証情報を Braze に追加した場合、各ファイルは segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip のようなキー形式で ZIP ファイルとしてバケットにアップロードされます。Azure を使用している場合は、Braze の Azure パートナー概要ページで [これをデフォルトのデータエクスポート先にする] チェックボックスがオンになっていることを確認してください。通常、Braze は処理を最適化するために5,000ユーザーごとに1つのファイルを作成します。大きなワークスペース内で小さなセグメントをエクスポートすると、複数のファイルが生成される場合があります。その後、ファイルを展開し、必要に応じてすべての json ファイルを1つのファイルに連結できます。output_format に gzip を指定すると、ファイル拡張子は .zip ではなく .gz になります。
ZIP のエクスポートパスの内訳
ZIP 形式:
bucket-name/segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip
ZIP の例:
braze.docs.bucket/segment-export/abc56c0c-rd4a-pb0a-870pdf4db07q/2019-04-25/d9696570-dfb7-45ae-baa2-25e302r2da27-1556044807/114f0226319130e1a4770f2602b5639a.zip
| プロパティ | 詳細 | 例での表示 |
|---|---|---|
bucket-name |
バケット名に基づいて固定されます。 | braze.docs.bucket |
segment-export |
固定。 | segment-export |
SEGMENT_ID |
エクスポートリクエストに含まれます。 | abc56c0c-rd4a-pb0a-870pdf4db07q |
YYYY-MM-dd |
コールバックが正常に受信された日付。 | 2019-04-25 |
RANDOM_UUID |
リクエスト時に Braze によって生成されるランダム UUID。 | d9696570-dfb7-45ae-baa2-25e302r2da27 |
TIMESTAMP_WHEN_EXPORT_STARTED |
UTC でエクスポートが要求された Unix 時間(2017-01-01:00:00:00Z からの秒数)。 | 1556044807 |
filename |
ファイルごとにランダム。 | 114f0226319130e1a4770f2602b5639a |
このエンドポイントを使用する際にエクスポートに独自のバケットポリシーを適用するため、独自の S3 または Azure 認証情報を設定することを強くお勧めします。クラウドストレージの認証情報がない場合は、リクエストへの応答で、すべてのユーザーファイルを含む ZIP ファイルをダウンロードできる URL が提供されます。URL は、エクスポートの準備ができた後にのみ有効な場所になります。
クラウドストレージ認証情報を提供しない場合は、このエンドポイントからエクスポートできるデータ量に制限があることに注意してください。エクスポートするフィールドやユーザーの数によっては、ファイルが大きすぎるとファイル転送が失敗することがあります。ベストプラクティスは、fields_to_export を使用してエクスポートするフィールドを指定し、転送サイズを抑えるために必要なフィールドのみを指定することです。ファイルの生成でエラーが発生する場合は、ランダムバケット番号に基づいてユーザー群をより多くのセグメントに分割することを検討してください(たとえば、ランダムバケット番号が1,000未満、または1,000から2,000の間のセグメントを作成します)。
どちらのシナリオでも、オプションで callback_endpoint を指定して、エクスポートの準備が整ったときに通知を受け取ることができます。callback_endpoint が指定されている場合、Braze はダウンロードの準備ができたときに、指定されたアドレスに POST リクエストを行います。POST の本文は “success”:true です。S3 認証情報を Braze に追加していない場合、POST の本文にはダウンロード URL を値として持つ属性 url が追加されます。
ユーザー群が大きいほど、エクスポート時間が長くなります。たとえば、2,000万人のユーザーを持つアプリの場合、1時間以上かかることもあります。
リクエスト本文
1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
{
"segment_id" : (required, string) identifier for the segment to be exported,
"callback_endpoint" : (optional, string) endpoint to post a download URL when the export is available,
"fields_to_export" : (required, array of string) name of user data fields to export, you may also export custom attributes. New accounts must specify specific fields to export,
"output_format" : (optional, string) when using your own S3 bucket, specifies file format as 'zip' or 'gzip'. Defaults to ZIP file format
}
リクエストパラメーター
| パラメーター | 必須 | データタイプ | 説明 |
|---|---|---|---|
segment_id |
必須 | 文字列 | エクスポートするセグメントの識別子。セグメント識別子を参照してください。 特定のセグメントの segment_id は、Braze アカウントの API Keys ページから確認できます。または、セグメント一覧エンドポイントを使用することもできます。 |
callback_endpoint |
オプション | 文字列 | エクスポートが利用可能になったときにダウンロード URL を POST するエンドポイント。 |
fields_to_export |
必須* | 文字列の配列 | エクスポートするユーザーデータフィールドの名前。このパラメーターに custom_attributes を含めることで、すべてのカスタム属性をエクスポートすることもできます。エクスポートできるフィールドの完全なリストについては、エクスポートするフィールドを参照してください。 |
custom_attributes_to_export |
オプション | 文字列の配列 | エクスポートする特定のカスタム属性の名前。最大500個のカスタム属性をエクスポートできます。ダッシュボードでカスタム属性の作成および管理を行うには、[データ設定] > [カスタム属性] に移動します。 |
output_format |
オプション | 文字列 | ファイルの出力形式。デフォルトは zip ファイル形式です。独自の S3 バケットを使用している場合は、zip または gzip を指定できます。 |
fields_to_export パラメーターに custom_attributes が含まれている場合、custom_attributes_to_export の内容に関係なく、すべてのカスタム属性がエクスポートされます。特定の属性をエクスポートすることが目的の場合は、custom_attributes を fields_to_export パラメーターに含めないでください。代わりに、custom_attributes_to_export パラメーターを使用してください。
すべてのカスタム属性をエクスポートするリクエスト例
1
2
3
4
5
6
7
8
9
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/segment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"segment_id" : "segment_identifier",
"callback_endpoint" : "example_endpoint",
"fields_to_export" : ["first_name", "email", "purchases", "custom_attributes"],
"output_format" : "zip"
}'
特定のカスタム属性をエクスポートするリクエスト例
1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://rest.iad-01.braze.com/users/export/segment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
"segment_id" : "segment_identifier",
"callback_endpoint" : "example_endpoint",
"fields_to_export" : ["first_name", "email", "purchases"],
"custom_attributes_to_export" : ["allergies", "favorite_food"],
"output_format" : "zip"
}'
エクスポートするフィールド
以下は、有効な 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形式)。 |
created_from |
文字列 | ユーザープロファイルの作成に使用された方法(例: SDK、REST API、CSV インポート)。 |
custom_attributes |
オブジェクト | このユーザーのカスタム属性のキーと値のペア。 |
custom_events |
配列 | 過去90日間にこのユーザーに帰属するカスタムイベント。 |
devices |
配列 | ユーザーのデバイスに関する情報。プラットフォームに応じて、次の情報が含まれます。 - model: デバイスのモデル名- os: デバイスのオペレーティングシステム- carrier: デバイスのサービスキャリア(利用可能な場合)- idfv: (iOS) Braze デバイス識別子、Apple の Vendor 用識別子(存在する場合)- idfa: (iOS) 広告用識別子(存在する場合)- device_id: (Android) Braze デバイス識別子- google_ad_id: (Android) Google Play 広告識別子(存在する場合)- roku_ad_id: (Roku) Roku 広告識別子- 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 |
文字列 | Braze にインポートされた形式のユーザーの電話番号。たとえば、電話番号を追加するリクエストが 1234567890 として送信された場合、同じ形式でエクスポートされます。 |
purchases |
配列 | このユーザーが過去90日間に行った購入。 |
push_tokens |
配列 | ユーザーのプッシュトークンに関する情報。 |
random_bucket |
整数 | ユーザーのランダムバケット番号。ランダムユーザーの均一分布セグメントを作成するために使用されます。 |
time_zone |
文字列 | IANA タイムゾーンデータベースと同じ形式のユーザーのタイムゾーン。 |
total_revenue |
浮動小数点 | このユーザーに帰属する総収益。総収益は、受信したキャンペーンおよびキャンバスのコンバージョン期間中にユーザーが行った購入に基づいて計算されます。 |
uninstalled_at |
タイムスタンプ | ユーザーがアプリをアンインストールした日時。アプリがアンインストールされていない場合は省略されます。 |
user_aliases |
オブジェクト | alias_name および alias_label を含むユーザーエイリアスオブジェクト(存在する場合)。 |
重要な注意事項
custom_events、purchases、campaigns_received、およびcanvases_receivedのフィールドには、過去90日間のデータのみが含まれます。custom_eventsとpurchasesの両方に、firstとcountのフィールドが含まれています。これらのフィールドは両方とも全期間の情報を反映しており、過去90日間のデータに限定されません。たとえば、特定のユーザーが90日以上前にイベントを最初に実行した場合、これはfirstフィールドに正確に反映され、countフィールドは過去90日より前に発生したイベントも考慮します。- 企業がエンドポイントレベルで実行できる同時セグメントエクスポートの数は100に制限されています。この制限を超えると、エラーが発生します。
- 最初のエクスポートジョブの実行中にセグメントを2回目にエクスポートしようとすると、429エラーが発生します。
応答
1
2
3
4
5
{
"message": (required, string) the status of the export, returns 'success' when completed without errors,
"object_prefix": (required, string) the filename prefix that is used for the JSON file produced by this export, for example, 'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
"url" : (optional, string) the URL where the segment export data can be downloaded if you do not have your own S3 credentials
}
URL が使用可能になった後、数時間のみ有効です。そのため、独自の S3 認証情報を Braze に追加することを強くお勧めします。
API レスポンスに object_prefix が表示され、データをダウンロードする URL がない場合、このエンドポイント用に Amazon S3 バケットがすでに設定されていることを意味します。このエンドポイントを使用してエクスポートされたデータは、S3 バケットに直接送信されます。
ユーザーエクスポートファイルの出力例
ユーザーエクスポートオブジェクト(Braze は可能な限り少ないデータを含めます—オブジェクトにフィールドがない場合は、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 the user's push notifications are turned on or turned off
},
...
],
"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"
},
...
]
}
CSV および API のエクスポートに関するヘルプについては、「エクスポートのトラブルシューティング」を参照してください。
GitHub でこのページを編集