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およびCanvasのコンバージョン期間中にユーザーが行った購入に基づいて計算されます。
uninstalled_at タイムスタンプ ユーザーがアプリをアンインストールした日時。アプリがアンインストールされていない場合は省略されます。
user_aliases オブジェクト alias_name および alias_label を含むユーザーエイリアスオブジェクト(存在する場合)。

重要な注意事項

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

応答

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!