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 バケットにエクスポートされます。
企業は、このエンドポイントを使用するセグメントごとに、特定の時刻に最大 1 つのエクスポートを実行できます。エクスポートが完了するのを待ってから、再試行してください。
前提条件
このエンドポイントを使用するには、API キーとusers.export.segment
の権限が必要です。
レート制限
API レート制限で説明されているように、このエンドポイントにはデフォルトの1時間あたり25万リクエストのBraze レート 制限が適用されます。
認証情報ベースの応答の詳細
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 パートナーの概要ページで、[これをデフォルトのデータエクスポート先にする] チェックボックスがオンになっていることを確認します。通常、処理を最適化するため、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 は、エクスポートの準備ができた後でのみ有効な場所になります。
クラウドストレージ認証情報s を提供しない場合は、このエンドポイントからエクスポートできるデータ量に制限があることに注意してください。エクスポートするフィールドやユーザーの個数によっては、大きすぎるとファイル転送が失敗することがあります。ベストプラクティスは、fields_to_export
を使用してエクスポートするフィールドを指定し、転送のサイズを低く保つために必要なフィールドs のみを指定することです。ファイルを生成するエラーを取得する場合は、乱数バケット番号に基づいてユーザー群をより多くのSegments に分割することを検討します(たとえば、乱数バケット番号が1000 未満、または1000 から2000 の間のSegmentを作成します)。
どちらのシナリオでも、オプションでcallback_endpoint
を指定して、エクスポートの準備が整ったときに通知することができます。callback_endpoint
が指定されている場合は、ダウンロードの準備ができたときに指定されたアドレスに POST リクエストを送信します。投稿の本文は”success”:true になります。Braze に S3 認証情報を追加していない場合、投稿の本文にはダウンロード 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 |
文字列 | アトリビューション積分からのデーター(設定されている場合)。キャンペーンと広告グループの下にある任意のサブグループの識別子。 |
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 を含むユーザーエイリアスオブジェクト (存在する場合)。 |
重要なお知らせ
custom_events
、purchases
、campaigns_received
、およびcanvases_received
のフィールドには、過去90 日間のデータのみが含まれます。custom_events
とpurchases
の両方に、first
とcount
のフィールドs が含まれています。これら両方のフィールドには、過去 90 日間のデータだけに限定されず、すべての期間の情報が反映されます。たとえば、特定のユーザーが 90 日前に初回のイベントを実行した場合、これはfirst
フィールドに正確に反映され、count
フィールドでは過去 90 日より前に発生したイベントも考慮されます。- 企業がエンドポイント レベルで実行できる同時セグメント エクスポートの数は 100 に制限されています。この制限を超える試みはエラーになります。
- 初回のエクスポートジョブがまだ実行されている間にセグメントを 2 回目にエクスポートしようとすると、429 エラーが発生します。
応答
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,
"object_prefix": (required, string) the filename prefix that will be 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 に追加することを強くお勧めします。
サンプルユーザーのエクスポートファイルアウトプット
ユーザエクスポートオブジェクト(できるだけ少ないデータを含みます。オブジェクトにフィールドがない場合は、null、false、または空であると見なされます):
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 のエクスポートに関するヘルプについては、「エクスポートのトラブルシューティング」を参照してください。