Skip to content

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

post

/users/export/segment

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

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

企業がこのエンドポイントを使用して一度に実行できるエクスポートは、セグメントごとに最大 1 回であることに注意してください。エクスポートが完了するのを待ってから、やり直してください。

前提条件

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

レート制限

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

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

S3Azure、または Google クラウドストレージの認証情報を 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_formatof を指定するとgzip.gzファイル拡張子はの代わりになります.zip

Export pathing breakdown for ZIP

ZIP フォーマット: bucket-name/segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.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:00:00:00 Z までの秒数)。 1556044807    
filename ファイルごとにランダム。 114f0226319130e1a4770f2602b5639a    

このエンドポイントを使用するときは、独自のS3またはAzure認証情報を設定して、エクスポートに独自のバケットポリシーを適用することを強くお勧めします。クラウドストレージの認証情報がない場合は、リクエストへの応答に、すべてのユーザーファイルを含むZIPファイルをダウンロードできるURLが表示されます。この URL は、エクスポートの準備ができて初めて有効な場所になります。

クラウドストレージの認証情報を提供しない場合、このエンドポイントからエクスポートできるデータ量に制限があることに注意してください。エクスポートするフィールドとユーザー数によっては、サイズが大きすぎるとファイル転送が失敗する場合があります。ベストプラクティスは、fields_to_exportどのフィールドを使用してエクスポートするかを指定し、転送のサイズを小さく抑えるために必要なフィールドのみを指定することです。ファイルの生成でエラーが発生した場合は、ランダムなバケット番号に基づいてユーザーベースをさらにセグメントに分割することを検討してください (たとえば、ランダムなバケット番号が 1,000 未満、または 1,000 ~ 2,000 のセグメントを作成します)。

どちらのシナリオでも、callback_endpointオプションでエクスポートの準備が整ったときに通知するように指定できます。callback_endpointが提供されている場合、ダウンロードの準備が整い次第、提供されたアドレスへの投稿リクエストを行います。投稿の本文は「成功」: true になります。BrazeにS3認証情報を追加していない場合、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. *Beginning April 2021, 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 キーページから確認するかセグメントリストエンドポイントを使用できます
callback_endpoint オプション 文字列 エクスポートが可能になったときにダウンロード URL を投稿するエンドポイント。
fields_to_export 必須* 文字列の配列 エクスポートするユーザーデータフィールドの名前。custom_attributesこのパラメータに含めることで、すべてのカスタムアトリビュートをエクスポートすることもできます。

* 2021 年 4 月以降、新規アカウントではエクスポートする特定のフィールドを指定する必要があります。
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_exportfields_to_exportを使用して返されるデータを最小限に抑えると、この API エンドポイントの応答時間を短縮できます。

エクスポートするフィールド データ型 説明  
apps Array このユーザーがセッションをログに記録したアプリ。これには次のフィールドが含まれます。

-name: アプリ名
-platform: iOS、Android、ウェブなどのアプリプラットフォーム
-version: アプリのバージョン番号または名前
-sessions: このアプリの合計セッション数
-first_used: 最初のセッションの日付
-last_used: 最終セッションの日付

すべてのフィールドは文字列です。
 
attributed_campaign 文字列 アトリビューション統合からのデータ(設定されている場合)特定の広告キャンペーンの識別子。  
attributed_source 文字列 アトリビューション統合からのデータ(設定されている場合)広告が掲載されたプラットフォームの識別子。  
attributed_adgroup 文字列 アトリビューション統合からのデータ(設定されている場合)キャンペーンの下にあるオプションのサブグループの識別子。  
attributed_ad 文字列 アトリビューション統合からのデータ(設定されている場合)キャンペーンと広告グループの下にあるオプションのサブグループの識別子。  
braze_id 文字列 Braze がこのユーザーに設定したデバイス固有のユーザー識別子。  
country 文字列 ISO 3166-1アルファ2標準を使用するユーザーの国  
created_at 文字列 ユーザープロファイルが作成された日付と時刻(ISO 8601形式)。  
custom_attributes オブジェクト このユーザーのカスタム属性キーと値のペア。  
custom_events 配列 過去 90 日間にこのユーザーに発生したカスタムイベント。  
devices Array ユーザーのデバイスに関する情報。プラットフォームによっては以下が含まれる場合があります。

modelデバイスのモデル名
osデバイスのオペレーティングシステム
carrierデバイスのサービスキャリア (利用可能な場合)
-idfv: (iOS) Braze デバイス識別子、ベンダー用の Apple 識別子 (存在する場合)
-idfa: (iOS) 広告の識別子 (存在する場合)
device_id(アンドロイド) Braze デバイス識別子
google_ad_id(Android) Google Play 広告識別子 (存在する場合)
roku_ad_id(ロク) ロク広告識別子
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 文字列 E.164形式のユーザーの電話番号。  
purchases 配列 このユーザーが過去 90 日間に購入したもの。  
push_tokens 配列 ユーザーのプッシュトークンに関する情報。  
random_bucket Integer ユーザーのランダムなバケット番号。ランダムなユーザーのセグメントを均一に分散させるために使用されます。  
time_zone 文字列 IANAタイムゾーンデータベースと同じ形式のユーザーのタイムゾーン。  
total_revenue Float このユーザーに帰属する総収益。総収益は、ユーザーが受け取ったキャンペーンやキャンバスのコンバージョン期間中に行った購入に基づいて計算されます。  
uninstalled_at タイムスタンプ ユーザーがアプリをアンインストールした日付と時刻。アプリがアンインストールされていない場合は省略されます。  
user_aliases オブジェクト alias_nameおよびを含むユーザーエイリアスオブジェクトalias_label存在する場合)。  

重要な注意事項

  • custom_events、、purchasescampaigns_receivedcanvases_receivedのフィールドには、過去 90 日間のデータのみが含まれます。
  • custom_eventspurchasesfirstとには両方におよびのフィールドが含まれますcount。これらのフィールドは両方とも過去の情報を反映し、過去 90 日間のデータだけに限定されません。たとえば、特定のユーザーが90日前に初めてイベントを行った場合、これはフィールドに正確に反映され、firstcountフィールドには過去90日より前に発生したイベントも考慮されます。
  • 企業がエンドポイントレベルで実行できるセグメントの同時エクスポート数は 100 に制限されています。この制限を超える試行はエラーになります。
  • 最初のエクスポートジョブの実行中にセグメントをもう一度エクスポートしようとすると、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 が公開されると、その有効期間は数時間です。そのため、Braze には独自の S3 認証情報を追加することを強くお勧めします。

ユーザー・エクスポート・ファイル出力の例

ユーザーエクスポートオブジェクト (可能な限り少ないデータを含めます。オブジェクトにフィールドがない場合は、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
{
    "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" : (bool)
      },
      ...
    ],
    "push_tokens" : [
      {
        "app" : (string) app name,
        "platform" : (string),
        "token" : (string)
      },
      ...
    ],
    "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" : (bool),
           "opened_push" : (bool),
           "clicked_email" : (bool),
           "clicked_triggered_in_app_message" : (bool)
          },
          "converted" : (bool),
          "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, bool) 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": (bool),
        "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!