Skip to content

セグメント別ユーザープロファイルのエクスポート

post

/users/export/segment

このエンドポイントを使用して、Segment内のすべてのユーザーをエクスポートします。

ユーザーデータは、改行で区切られたユーザーJSONオブジェクトの複数のファイルとしてエクスポートされます(1行に1つのJSONオブジェクトなど)。データは、自動生成されたURL、またはこの統合がすでに設定されている場合はS3バケットにエクスポートされます。

企業は、このエンドポイントを使用するSegmentごとに、特定の時刻に最大1つのエクスポートを実行できます。エクスポートが完了するのを待ってから、再試行してください。

前提条件

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

レート制限

APIレート制限に記載されているように、このエンドポイントにはデフォルトのBrazeレート制限(1時間あたり250,000リクエスト)が適用されます。

認証情報ベースの応答の詳細

S3Azure、または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つのファイルを作成します。大きなワークスペース内で小さなSegmentをエクスポートすると、複数のファイルが生成される場合があります。その後、ファイルを展開し、必要に応じてすべてのjsonファイルを1つのファイルに連結できます。output_formatgzipを指定すると、ファイル拡張子は.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を使用してエクスポートするフィールドを指定し、転送サイズを抑えるために必要なフィールドのみを指定することです。ファイルの生成でエラーが発生する場合は、ランダムバケット番号に基づいてユーザー群をより多くのSegmentに分割することを検討してください(たとえば、ランダムバケット番号が1,000未満、または1,000から2,000の間のSegmentを作成します)。

どちらのシナリオでも、オプションで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の識別子。Segment識別子を参照してください。

特定のSegmentのsegment_idは、BrazeアカウントのAPIキーページから確認できます。または、Segment一覧エンドポイントを使用することもできます。
callback_endpoint オプション 文字列 エクスポートが利用可能になったときにダウンロードURLをPOSTするエンドポイント。
fields_to_export 必須* 文字列の配列 エクスポートするユーザーデータフィールドの名前。このパラメーターにcustom_attributesを含めることで、すべてのカスタム属性をエクスポートすることもできます。エクスポートできるフィールドの完全なリストについては、エクスポートするフィールドを参照してください。
custom_attributes_to_export オプション 文字列の配列 エクスポートする特定のカスタム属性の名前。最大500個のカスタム属性をエクスポートできます。ダッシュボードでカスタム属性の作成および管理を行うには、データ設定 > カスタム属性に移動します。
output_format オプション 文字列 ファイルの出力形式。デフォルトはzipファイル形式です。独自のS3バケットを使用している場合は、zipまたはgzipを指定できます。

すべてのカスタム属性をエクスポートするリクエスト例

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 文字列 アトリビューション統合からのデータ(設定されている場合)。Campaignの下のオプションのサブグループの識別子。
attributed_ad 文字列 アトリビューション統合からのデータ(設定されている場合)。Campaignと広告グループの下のオプションのサブグループの識別子。
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 整数 ユーザーのランダムバケット番号。ランダムユーザーの均一分布Segmentを作成するために使用されます。
time_zone 文字列 IANAタイムゾーンデータベースと同じ形式のユーザーのタイムゾーン。
total_revenue 浮動小数点 このユーザーに帰属する総収益。総収益は、受信したCampaignおよびCanvasesのコンバージョン期間中にユーザーが行った購入に基づいて計算されます。
uninstalled_at タイムスタンプ ユーザーがアプリをアンインストールした日時。アプリがアンインストールされていない場合は省略されます。
user_aliases オブジェクト alias_nameおよびalias_labelを含むユーザーエイリアスオブジェクト(存在する場合)。

重要な注意事項

  • custom_eventspurchasescampaigns_received、およびcanvases_receivedのフィールドには、過去90日間のデータのみが含まれます。
  • custom_eventspurchasesの両方に、firstcountのフィールドが含まれています。これらのフィールドは両方とも全期間の情報を反映しており、過去90日間のデータに限定されません。たとえば、特定のユーザーが90日以上前にイベントを最初に実行した場合、これはfirstフィールドに正確に反映され、countフィールドは過去90日より前に発生したイベントも考慮します。
  • 企業がエンドポイントレベルで実行できる同時セグメントエクスポートの数は100に制限されています。この制限を超えると、エラーが発生します。
  • 最初のエクスポートジョブの実行中にSegmentを2回目にエクスポートしようとすると、429エラーが発生します。
  • 403 Forbiddenレスポンスは、多くの場合、エクスポートファイルがまだ準備できていないことを意味します。
  • サブスクリプショングループのデータは、セグメントエクスポートでは利用できません。サブスクリプションステータスでユーザーを特定するには、サブスクリプショングループのメンバーシップに基づいて別のSegmentを作成し、そのSegmentをエクスポートしてください。

応答

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
}

null URL

レスポンスに"url": nullが含まれている(またはダウンロードURLが省略されている)場合で、Amazon S3バケットやAzure Blob Storageコンテナなどのクラウドストレージ統合を設定している場合、BrazeはAPIレスポンスで一時的なダウンロードURLを返す代わりに、接続されたバケットまたはコンテナにエクスポートを書き込みます。接続されたクラウドストレージのバケットまたはコンテナからファイルを取得してください。

ダウンロード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 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!