コンテンツにスキップ

識別子によるユーザープロファイルのエクスポート

post

/users/export/ids

このエンドポイントを使用して、ユーザー識別子を指定して任意のユーザープロファイルからデータをエクスポートします。

1つのリクエストには、最大50個のexternal_idsまたはuser_aliasesを含めることができます。device_idemail_address、またはphoneを指定する場合、リクエストごとにこれらの識別子のうち1つのみを含めることができます。

前提条件

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

レート制限

2024年8月22日以降にBrazeにオンボーディングした場合、このエンドポイントには、APIレート制限に記載されているように、1分あたり250リクエストのレート制限が適用されます。

以下の要件を満たすことで、このエンドポイントのレート制限を1秒あたり40リクエストまで引き上げることもできます。

  • ワークスペースにデフォルトのレート制限(1分あたり250リクエスト)が有効になっていること。既存のレート制限の解除についてサポートが必要な場合は、担当のBrazeアカウントマネージャーにお問い合わせください。
  • リクエストに、受け取りたいすべてのフィールドを列挙するfields_to_exportパラメーターが含まれていること。

リクエスト本文

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "external_ids": (optional, array of strings) External identifiers for users you wish to export,
  "user_aliases": (optional, array of user alias objects) user aliases for users to export,
  "device_id": (optional, string) Device identifier as returned by various SDK methods such as `getDeviceId`,
  "braze_id": (optional, string) Braze identifier for a particular user,
  "email_address": (optional, string) Email address of user,
  "phone": (optional, string) Phone number of user,
  "fields_to_export": (optional, array of strings) Name of user data fields to export
}

リクエストパラメーター

パラメーター 必須 データタイプ 説明
external_ids オプション 文字列の配列 エクスポートするユーザーの外部識別子。
user_aliases オプション ユーザーエイリアスオブジェクトの配列 エクスポートするユーザーのユーザーエイリアス
device_id オプション 文字列 getDeviceIdなどのさまざまなSDKメソッドによって返されるデバイス識別子。
braze_id オプション 文字列 特定のユーザーのBraze識別子。
email_address オプション 文字列 ユーザーのメールアドレス。
phone オプション E.164形式の文字列 ユーザーの電話番号。
fields_to_export オプション* 文字列の配列 エクスポートするユーザーデータフィールドの名前。

*このフィールドは、1秒あたり40リクエストの高速レート制限を使用するために必要です。省略した場合、1分あたり250リクエストのデフォルトレート制限が代わりに使用されます。

*2024年8月22日以降にBrazeにオンボーディングした顧客には必須です。

リクエスト例

curl --location --request POST 'https://rest.iad-01.braze.com/users/export/ids' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "external_ids": ["user_identifier1", "user_identifier2"],
  "user_aliases": [
    {
      "alias_name": "example_alias",
      "alias_label": "example_label"
    }
  ],
  "device_id": "1234567",
  "braze_id": "braze_identifier",
  "email_address": "example@example.com",
  "phone": "11112223333",
  "fields_to_export": ["first_name", "email", "purchases"]
}'

エクスポートするフィールド

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

/users/export/idsエンドポイントは、受信したすべてのキャンペーンやキャンバス、実行されたすべてのカスタムイベント、行われたすべての購入、すべてのカスタム属性などのデータを含む、このユーザーのユーザープロファイル全体をまとめることに注意してください。このため、このエンドポイントは他のREST APIエンドポイントよりも低速になります。

リクエストされたデータによっては、このAPIエンドポイントでは1分あたり250件のリクエストのレート制限があるため、ニーズを満たすには不十分な場合があります。このエンドポイントを定期的に使用してユーザーをエクスポートすることを想定している場合は、代わりに、非同期で大規模なデータプルに最適化されているセグメント別のユーザーエクスポートを検討してください。

レスポンス

{
    "message": (string) returns 'success' when the request completes without errors,
    "users" : (array of object) the data for each of the exported users, may be empty if no users are found,
    "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}

このエンドポイントからアクセスできるデータの例については、以下の例を参照してください。

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

ユーザーエクスポートオブジェクト(できるだけ少ないデータを含めます。オブジェクトにフィールドがない場合は、nullまたは空であると見なされます):

{
    "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,
        "provisionally_opted_in": (boolean) included for iOS and Android tokens only. Indicates whether the token is in a provisional push authorization state. `true` means the token is provisionally opted in (notifications are delivered quietly), `false` means the token isn't provisional (the user has explicitly authorized or denied push), and `null` means provisional status isn't set. Provisional authorization applies to iOS; Android tokens report `null`
      },
      ...
    ],
    "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)
      },
      ...
    ]
}
{
    "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" : "Alex",
    "last_name" : "Smith",
    "email" : "example@example.com",
    "dob" : "1980-12-21",
    "home_city" : "Chicago",
    "country" : "US",
    "phone" : "+15555550123",
    "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,
        "provisionally_opted_in": null
      },
      ...
    ],
    "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!