Segmentによるユーザープロファイルのエクスポート
/users/export/segment
このエンドポイントを使用して、Segment内のすべてのユーザーs をエクスポートします。
このエンドポイントを使用する場合は、次の点に注意してください。
1.このAPI リクエストのfields_to_export フィールドはrequired です。
2.custom_events、purchases、campaigns_received、canvases_received のフィールドには、過去 90 日間のデータのみが含まれます。
ユーザーデータは、新しい行で区切られたユーザーのJSONオブジェクトの複数のファイルとしてエクスポートされます(1行に1つのJSONオブジェクトなど)。データは、自動生成されたURL またはS3 バケットにエクスポートされます(この統合がすでに設定されている場合)。
出力形式のエクスポート:エクスポートが成功し、クラウドストレージ認証情報s を設定していない場合、HTTP レスポンスには圧縮アーカイブ(ZIP またはGZIP ファイル) を読み込むするためのURL が含まれます。クラウドストレージ認証情報(S3、Azure、またはGoogle Cloud Storage) が設定されている場合、Braze はエクスポートをバケットに直接書き込み、レスポンスにはダウン読み込むURL は含まれません。エクスポートが失敗した場合は、代わりにメール 通知が表示されます。クラウドストレージ認証情報を設定すると、大規模なエクスポートで障害が発生する可能性が低くなります。
企業は、このエンドポイントを使用するセグメントごとに、特定の時刻に最大 1 つのエクスポートを実行できます。エクスポートが完了するのを待ってから、再試行してください。
前提条件
このエンドポイントを使用するには、API キーとusers.export.segmentの権限が必要です。
レート制限
API レート制限で説明されているように、このエンドポイントにはデフォルトの1時間あたり25万リクエストのBraze レート 制限が適用されます。
認証情報ベースの応答の詳細
S3、Azure、またはGoogle Cloud Storage 認証情報 s をBraze に追加した場合、各ファイルはsegment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip のようなキー形式でZIP ファイルとしてバケットにアップロードされます。Azure を使用している場合は、Braze の Azure パートナーの概要ページで、[これをデフォルトのデータエクスポート先にする] チェックボックスがオンになっていることを確認します。通常、Braze は5000 ユーザー 秒あたり1 つのファイルを作成し、プロセッシングを最適化します。大きなワークスペース内で小さなセグメントをエクスポートすると、複数のファイルが生成される場合があります。その後、ファイルを抽出し、必要に応じてすべてのjson ファイルを1 つのファイルに連結できます。output_format のgzip を指定すると、ファイル拡張子は.zip ではなく.gz になります。
Export pathing breakdown for 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 は、エクスポートの準備ができた後でのみ有効な場所になります。
クラウドストレージ認証情報s を提供しない場合は、このエンドポイントからエクスポートできるデータ量に制限があることに注意してください。エクスポートするフィールドやユーザーの個数によっては、大きすぎるとファイル転送が失敗することがあります。ベストプラクティスは、fields_to_export を使用してエクスポートするフィールドを指定し、転送のサイズを低く保つために必要なフィールドs のみを指定することです。ファイルを生成するエラーを取得する場合は、乱数バケット番号に基づいてユーザー群をより多くのSegments に分割することを検討します(たとえば、乱数バケット番号が1000 未満、または1000 から2000 の間のSegmentを作成します)。
どちらのシナリオでも、オプションでcallback_endpoint を指定して、エクスポートの準備が整ったときに通知することができます。callback_endpoint が指定されている場合、Braze は、ダウン読み込むの準備ができたときに、指定された住所に投稿リクエストを行います。投稿の本文は”success”:true です。S3 認証情報 s をBraze に追加していない場合、投稿の本文には、下の読み込むURL を値として持つ属性url が追加されます。
ユーザー群s が大きいほど、エクスポート時間が長くなります。例えば、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。セグメント識別子を参照してください。 特定のSegmentの segment_id は、Braze アカウントのAPI Keys ページから見つけることができます。または、 Segment一覧エンドポイント を使用することもできます。 |
callback_endpoint |
オプション | 文字列 | エクスポートが利用可能になった場合に、ダウンロード URL を投稿するエンドポイント。 |
fields_to_export |
必須* | 文字列の配列 | エクスポートするユーザーデータ フィールドの名前。また、このパラメータにcustom_attributes を含めることで、すべてのカスタム属性s をエクスポートすることもできます。*2021 年 4 月以降、新しいアカウントでは、エクスポートする特定のフィールドを指定する必要があります。 |
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: 最終セッションの日付すべてのフィールドsはストリングです。 |
attributed_campaign |
文字列 | アトリビューション積分からのデーター(設定されている場合)。特定の広告キャンペーンのID。 |
attributed_source |
文字列 | アトリビューション積分からのデーター(設定されている場合)。広告が表示されたプラットフォームのID。 |
attributed_adgroup |
文字列 | アトリビューション積分からのデーター(設定されている場合)。キャンペーン の下のオプションのサブグループのID。 |
attributed_ad |
文字列 | アトリビューション積分からのデーター(設定されている場合)。キャンペーンと広告グループの下にある任意のサブグループの識別子。 |
push_subscribe |
string | ユーザーのプッシュ通知の購読ステータス。 |
email_subscribe |
string | ユーザーのメールサブスクリプションステータス。 |
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 |
string | Braze にインポートされた形式のユーザの電話番号。たとえば、電話番号を追加するリクエストが1234567890 のように含まれている場合、同じ形式でエクスポートされます。 |
purchases |
配列 | このユーザーは過去90日間に購入しました。 |
push_tokens |
配列 | ユーザーのプッシュトークンについての説明。 |
random_bucket |
整数 | ユーザーの乱数バケット番号。乱数ユーザーsの一様分布Segmentsを作成するために使用されます。 |
time_zone |
文字列 | IANAタイムゾーンデータベースと同じ形式のユーザーのタイムゾーン。 |
total_revenue |
フロート | このユーザーに帰属する総収益。総収益は、受領したキャンペーンおよびキャンバスのコンバージョン期間中に行われたユーザーの購入に基づいて計算されます。 |
uninstalled_at |
タイムスタンプ | ユーザーがアプリをアンインストールした日時。アプリがアンインストールされていない場合は省略されます。 |
user_aliases |
オブジェクト | alias_name およびalias_label を含むユーザーエイリアスオブジェクト (存在する場合)。 |
重要なお知らせ
custom_events、purchases、campaigns_received、およびcanvases_receivedのフィールドs には、過去90 日間のデータのみが含まれます。custom_eventsとpurchasesの両方に、firstとcountのフィールドs が含まれています。これらのフィールドは両方とも常に情報を反映しており、過去90日間のデータに限定されません。たとえば、特定のユーザーが90 日前にイベントを最初に実行した場合、これはfirstフィールドにac キュレート ly が反映され、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" : "example@braze.com",
"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 でこのページを編集