콘텐츠로 건너뛰기

식별자로 사용자 프로필 내보내기

post

/users/export/ids

이 엔드포인트를 사용하여 사용자 식별자를 지정하여 모든 사용자 프로필에서 데이터를 내보낼 수 있습니다.

하나의 요청에 최대 50개의 external_ids 또는 user_aliases를 포함할 수 있습니다. device_id, email_address, phone을 지정하려는 경우 요청당 이 식별자 중 하나만 포함할 수 있습니다.

필수 조건

이 엔드포인트를 사용하려면 users.export.ids 권한이 있는 API 키가 필요합니다.

사용량 제한

2024년 8월 22일 이후에 Braze에 온보딩한 경우, 이 엔드포인트는 API 사용량 제한에 명시된 대로 분당 250건의 요청으로 사용량 제한이 적용됩니다.

다음 요구 사항을 충족하면 이 엔드포인트의 사용량 제한을 초당 40건의 요청으로 늘릴 수도 있습니다:

  • 워크스페이스에 기본 사용량 제한(분당 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 선택 사항* 문자열 배열 내보낼 사용자 데이터 필드의 이름입니다.

*초당 40건의 빠른 사용량 제한을 사용하려면 이 필드가 필수입니다. 생략하면 기본값인 분당 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": "[email protected]",
  "phone": "11112223333",
  "fields_to_export": ["first_name", "email", "purchases"]
}'

내보낼 필드

다음은 유효한 fields_to_export 목록입니다. fields_to_export를 사용하여 반환되는 데이터를 최소화하면 이 API 엔드포인트의 응답 시간을 개선할 수 있습니다.

내보낼 필드 데이터 유형 설명
apps 배열 이 사용자가 세션을 기록한 앱으로, 다음 필드를 포함합니다:

- name: 앱 이름
- platform: iOS, Android 또는 웹과 같은 앱 플랫폼
- 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) 광고용 식별자(있는 경우)
- 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 문자열 E.164 형식의 사용자 전화번호입니다.
purchases 배열 이 사용자가 지난 90일 동안 수행한 구매입니다.
push_tokens 배열 앱의 알림을 보낼 위치를 지정하는 고유 익명 식별자입니다.
random_bucket 정수 무작위 사용자의 균일하게 분산된 세그먼트를 생성하는 데 사용되는 사용자의 무작위 버킷 번호입니다.
time_zone 문자열 IANA 시간대 데이터베이스와 동일한 형식의 사용자 시간대입니다.
total_revenue 플로트 이 사용자에게 귀속된 총 매출입니다. 총 매출은 사용자가 수신한 Campaigns 및 Canvases의 전환 기간 동안 수행한 구매를 기반으로 계산됩니다.
uninstalled_at 타임스탬프 사용자가 앱을 삭제한 날짜와 시간입니다. 앱이 삭제되지 않은 경우 생략됩니다.
user_aliases 오브젝트 alias_namealias_label을 포함하는 사용자 별칭 오브젝트(있는 경우)입니다.

/users/export/ids 엔드포인트는 수신한 모든 Campaigns 및 Canvases, 수행한 모든 커스텀 이벤트, 모든 구매, 모든 커스텀 속성 등의 데이터를 포함하여 이 사용자의 전체 사용자 프로필을 가져온다는 점에 유의하세요. 결과적으로 이 엔드포인트는 다른 REST API 엔드포인트보다 속도가 느립니다.

요청되는 데이터에 따라 분당 250건의 요청 사용량 제한으로 인해 이 API 엔드포인트가 요구 사항을 충족하기에 충분하지 않을 수 있습니다. 이 엔드포인트를 정기적으로 사용하여 사용자를 내보낼 예정이라면, 비동기식이며 대규모 데이터 가져오기에 더 최적화된 세그먼트별 사용자 내보내기를 고려하세요.

응답

{
    "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" : "[email protected]",
    "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!