Google BigQuery용 클라우드 데이터 수집

이 페이지에서는 클라우드 데이터 수집(CDI)을 사용해 Google BigQuery의 데이터를 Braze로 동기화하는 데 필요한 모든 내용을 다룹니다. Google Cloud에서 만들어야 하는 리소스, Braze에서 소스를 연결하고 동기화를 생성하는 방법, 데이터 유형별 소스 테이블, BigQuery 관련 문제 해결 방법을 확인할 수 있습니다.

설정 개요

1. BigQuery 계정에서 Braze로 동기화할 테이블 또는 뷰를 설정합니다.
2. 서비스 계정을 생성하고, 동기화할 데이터가 포함된 BigQuery 프로젝트와 데이터 세트에 대한 액세스를 허용합니다.
3. 지원되는 인증 방법 중 하나를 사용해 Braze가 서비스 계정에 액세스하는 방식을 설정합니다.
4. Braze 대시보드에서 새 소스와 동기화를 생성합니다.
5. 통합을 검증하고 동기화를 시작합니다.

1단계: 소스 테이블 설정

이 섹션의 단계에서는 PAYLOAD 열이 있는 테이블을 생성합니다. 데이터 정의 단계에서 비주얼로 열을 매핑하거나 SQL로 쿼리를 작성할 계획이라면, 기존 테이블이나 뷰를 대신 사용할 수 있습니다. 이 경우 테이블 생성 단계는 건너뛰고, 동기화할 테이블 또는 뷰에 대한 읽기 권한을 Braze에 부여하세요. 옵션 비교는 데이터 정의 옵션 선택하기를 참조하세요.

프로젝트, 데이터 세트, 테이블 이름은 원하는 대로 지정할 수 있지만, 열 이름은 다음 탭의 정의와 일치해야 합니다. 테이블 대신 뷰나 구체화된 뷰를 사용할 수도 있습니다.

필요한 경우 소스 테이블을 보관할 새 프로젝트나 데이터 세트를 설정합니다.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

참고

PAYLOAD 열을 사용하는 경우, 소스 테이블이나 뷰에 다음 탭에 나열되지 않은 열(예: 감사 또는 해싱용 열)을 포함할 수 있습니다. Braze는 이 탭에 설명된 열만 읽으며, 그 밖의 열은 클라우드 데이터 수집 동기화 중에 사용되지 않습니다.

동기화할 데이터 유형에 맞는 탭을 선택하세요.

• 사용자 속성
• 커스텀 이벤트
• 구매 이벤트
• 카탈로그 항목
• canvas 트리거
• 사용자 삭제

사용자 속성, 커스텀 이벤트, 구매 이벤트는 모두 동일한 형태의 소스 테이블을 사용합니다. PAYLOAD의 내용만 다릅니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id, alias_name and alias_label, or braze_id is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  --braze_id can only be used to update existing users created through the Braze SDK
  braze_id STRING,
  --If you include both email and phone, email is used as the primary identifier
  email STRING,
  phone STRING,
  payload JSON
);

필드 이름	유형	모드
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	JSON	REQUIRED
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE
BRAZE_ID	STRING	NULLABLE
EMAIL	STRING	NULLABLE
PHONE	STRING	NULLABLE

• UPDATED_AT - 이 행이 테이블에서 업데이트되거나 테이블에 추가된 시간입니다. Braze는 UPDATED_AT이 마지막으로 동기화된 값보다 늦은 행을 동기화합니다. 경계 타임스탬프와 정확히 일치하는 행은 같은 타임스탬프를 가진 새 행이 있으면 다시 동기화될 수 있습니다.
• 사용자 식별자 열 - 테이블에는 하나 이상의 사용자 식별자 열이 포함될 수 있습니다. 각 행에는 식별자가 하나만 포함되어야 합니다(external_id, alias_name과 alias_label의 조합, braze_id, email 또는 phone 중 하나). 소스 테이블에는 식별자 유형 한 가지, 두 가지, 세 가지, 네 가지 또는 다섯 가지 모두에 대한 열이 있을 수 있습니다.
  • EXTERNAL_ID - 업데이트하려는 사용자를 식별합니다. 이 값은 Braze에서 사용하는 external_id 값과 일치해야 합니다.
  • ALIAS_NAME 및 ALIAS_LABEL - 이 두 열은 사용자 별칭 객체를 생성합니다. alias_name은 고유 식별자여야 하며, alias_label은 별칭의 유형을 지정합니다. 사용자는 레이블이 서로 다른 여러 별칭을 가질 수 있지만, alias_label당 alias_name은 하나만 가질 수 있습니다.
  • BRAZE_ID - Braze 사용자 식별자입니다. 이 값은 Braze SDK에서 생성되며, Cloud Data Ingestion을 통해 Braze ID로 새 사용자를 생성할 수는 없습니다. 새 사용자를 생성하려면 외부 사용자 ID 또는 사용자 별칭을 지정하세요.
  • EMAIL - 사용자의 이메일 주소입니다. 동일한 이메일 주소를 가진 프로필이 여러 개 있으면 가장 최근에 업데이트된 프로필이 우선적으로 업데이트됩니다. 이메일과 전화번호를 모두 포함하면 이메일이 기본 식별자로 사용됩니다.
  • PHONE - 사용자의 전화번호입니다. 동일한 전화번호를 가진 프로필이 여러 개 있으면 가장 최근에 업데이트된 프로필이 우선적으로 업데이트됩니다.
• PAYLOAD - Braze에서 사용자에게 동기화할 필드의 JSON 문자열입니다.

속성 동기화의 경우 PAYLOAD는 사용자 속성 객체 형식을 따릅니다. 중첩 커스텀 속성, 객체 배열, 구독 그룹 상태를 포함할 수 있습니다. 페이로드 예시는 테이블 설정을 참조하세요.

중요

BigQuery 파티셔닝

CDI는 BigQuery 파티션을 지원합니다. UPDATED_AT의 함수(예: 데이터 세트 크기에 따라 일, 주 또는 시간 단위)로 파티셔닝하면 BigQuery가 스캔해야 하는 데이터를 줄일 수 있습니다. 이렇게 하면 매우 큰 테이블의 성능과 효율성이 향상됩니다.

다른 필드로는 파티셔닝하지 마세요. 다양한 구성을 테스트하여 데이터에 가장 적합한 설정을 찾으세요.

모든 CDI 쿼리는 UPDATED_AT으로 필터링하지만, 이 동작은 변경될 수 있습니다. 쿼리에 이 절이 포함되지 않아도 되도록 테이블 스키마를 설계하세요.

자세한 내용은 BigQuery 파티셔닝 설명서를 참조하세요.

커스텀 이벤트는 사용자 속성과 동일한 소스 테이블을 사용합니다. 사용자 속성 탭에 표시된 테이블을 생성한 다음, PAYLOAD를 이벤트 객체로 채우세요.

이벤트를 동기화하려면 이벤트 이름이 필요합니다. time 필드는 ISO 8601 문자열 또는 yyyy-MM-dd'T'HH:mm:ss:SSSZ 형식으로 지정하세요. time 필드가 없으면 Braze는 UPDATED_AT 열 값을 이벤트 시간으로 사용합니다. app_id, properties 등 그 밖의 필드는 선택 사항입니다.

행당 하나의 이벤트를 동기화할 수 있습니다.

1
2
3
4
5
6
7
8
9

{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Alex Smith"
    }
}

구매 이벤트는 사용자 속성과 동일한 소스 테이블을 사용합니다. 사용자 속성 탭에 표시된 테이블을 생성한 다음, PAYLOAD를 구매 객체로 채우세요.

구매 이벤트를 동기화하려면 product_id, currency, price가 필요합니다. 선택 사항인 time 필드는 ISO 8601 문자열 또는 yyyy-MM-dd'T'HH:mm:ss:SSSZ 형식으로 지정하세요. time 필드가 없으면 Braze는 UPDATED_AT 열 값을 이벤트 시간으로 사용합니다. app_id, quantity, properties 등 그 밖의 필드는 선택 사항입니다.

행당 하나의 구매 이벤트를 동기화할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11
12

{
    "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
    "product_id" : "Completed Order",
    "currency" : "USD",
    "price" : 219.98,
    "time" : "2013-07-16T19:20:30+01:00",
    "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
        ]
    }
}

카탈로그 동기화를 생성하기 전에 Braze에서 대상 카탈로그를 생성하세요. 전체 카탈로그 워크플로는 카탈로그 데이터 동기화 및 삭제를 참조하세요.

1
2
3
4
5
6
7

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CATALOGS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  id STRING,
  payload JSON,
  deleted BOOLEAN
);

필드 이름	유형	모드
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	JSON	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	OPTIONAL

통합 이름은 Braze에서 생성한 카탈로그 이름과 정확히 일치해야 합니다.

동기화가 실행될 때마다 소스 테이블이 완전히 새로 고쳐지도록 카탈로그 데이터로 뷰를 생성하는 것을 권장합니다. 예를 들어 product_id와 세 개의 추가 속성이 있는 제품 데이터 테이블(product_catalog_1)이 있다면 다음 뷰를 동기화할 수 있습니다.

1
2
3
4
5
6
7
8
9
10
11

CREATE view IF NOT EXISTS BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS (SELECT
    last_updated as UPDATED_AT,
    product_id as ID,
    TO_JSON(
      STRUCT(
      attribute_1,
      attribute_2,
      attribute_3,
      )
    ) as PAYLOAD
  FROM `BRAZE_CLOUD_PRODUCTION.INGESTION.product_catalog_1`);

Canvas 트리거는 제로 카피 개인화를 지원합니다. 대상 Canvas 설정 및 고려 사항은 제로 카피 개인화를 참조하세요.

1
2
3
4
5
6
7
8
9
10

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties JSON
);

필드 이름	유형	필수 여부
UPDATED_AT	TIMESTAMP	예
PROPERTIES	JSON	예
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

Canvas 트리거 동기화는 다른 사용자 데이터 동기화와 세 가지 면에서 다릅니다.

• 외부 ID 또는 사용자 별칭 식별자만 지원됩니다. 이메일과 전화번호는 식별자로 지원되지 않습니다.
• 기존 Braze 사용자만 동기화할 수 있습니다. 새 사용자는 생성할 수 없습니다.
• PROPERTIES가 PAYLOAD 열을 대체합니다. 이 열은 개인화를 위해 Canvas 항목 속성으로 사용하려는 필드를 담은 JSON 문자열입니다.

Canvas 트리거 테이블에는 다음 열이 필요합니다.

• UPDATED_AT - 이 행이 업데이트되거나 테이블에 추가된 시간입니다. Braze는 UPDATED_AT이 마지막으로 동기화된 값보다 이후인 행을 동기화합니다. 경계 타임스탬프와 정확히 일치하는 행은 같은 타임스탬프를 가진 새 행이 있으면 다시 동기화될 수 있습니다.
• 사용자 식별자 열로 EXTERNAL_ID 또는 ALIAS_NAME과 ALIAS_LABEL 중 하나가 필요합니다. 이 열은 Canvas 메시징을 트리거할 대상 사용자를 식별합니다.
  • EXTERNAL_ID - Canvas에 진입시킬 사용자를 식별합니다. 이 값은 Braze에서 사용하는 external_id 값과 일치해야 합니다.
  • ALIAS_NAME 및 ALIAS_LABEL - 이 두 열로 사용자 별칭 객체를 생성합니다. alias_name은 고유 식별자여야 하며, alias_label은 별칭 유형을 지정합니다. 사용자는 레이블이 서로 다른 여러 별칭을 가질 수 있지만, alias_label당 alias_name은 하나만 가질 수 있습니다.
• PROPERTIES - Canvas에서 개인화 속성으로 사용할 수 있게 할 필드를 담은 JSON 문자열입니다. 사용자별 정보가 포함되어야 합니다.

참고

모든 행이나 사용자에게 속성이 필요한 것은 아닙니다. 다만 속성 값은 유효한 JSON 문자열이어야 합니다. 행에 속성이 없으면 빈 {} 문자열을 입력하세요.

시작하려면 새 동기화를 생성할 때 Canvas 트리거 데이터 유형을 선택하세요.

사용자 삭제를 위한 소스 테이블에는 하나 이상의 사용자 식별자 유형과 UPDATED_AT 타임스탬프가 포함되어야 합니다. 사용자 삭제 데이터에는 페이로드 열이 지원되지 않습니다.

• UPDATED_AT - 이 행이 테이블에 업데이트되거나 추가된 시간입니다. Braze는 UPDATED_AT이 마지막으로 동기화된 값보다 이후인 행을 동기화합니다. 새 행이 경계 타임스탬프와 정확히 같은 타임스탬프를 공유하는 경우, 해당 경계 타임스탬프의 행이 다시 동기화될 수 있습니다.
• 사용자 식별자 열 - 각 행에는 식별자가 하나만 포함되어야 합니다. external_id, alias_name과 alias_label의 조합, braze_id 중 하나를 사용하세요. 소스 테이블에는 한 가지, 두 가지 또는 세 가지 식별자 유형 모두에 대한 열이 포함될 수 있습니다.
  • EXTERNAL_ID - 업데이트하려는 사용자를 식별합니다. Braze에서 사용하는 external_id 값과 일치해야 합니다.
  • ALIAS_NAME 및 ALIAS_LABEL - 이 두 열은 사용자 별칭 객체를 생성합니다. alias_name은 고유 식별자여야 하며, alias_label은 별칭 유형을 지정합니다. 사용자는 레이블이 서로 다른 여러 별칭을 가질 수 있지만, alias_label당 alias_name은 하나만 가질 수 있습니다.
  • BRAZE_ID - Braze 사용자 식별자입니다. 이 식별자는 Braze SDK에서 생성되며, Cloud Data Ingestion을 통해 Braze ID로 신규 사용자를 생성할 수는 없습니다. 신규 사용자를 생성하려면 외부 사용자 ID 또는 사용자 별칭을 지정하세요.

중요

사용자 삭제용 테이블에는 PAYLOAD 열을 포함하지 마세요. 실수로 사용자가 영구 삭제되는 것을 방지하기 위해, 소스 테이블에 페이로드 열이 있으면 동기화가 실패합니다. 그 외의 열은 포함할 수 있지만 Braze에서 무시됩니다.

다음 필드로 테이블을 생성합니다.

필드 이름	유형	모드
UPDATED_AT	TIMESTAMP	REQUIRED
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE
BRAZE_ID	STRING	NULLABLE

통합 실행 중에 적절한 작업이 수행되도록 가져오기 동기화 생성 페이지에서 데이터 유형을 사용자 삭제로 설정하세요. 자세한 내용은 클라우드 데이터 수집으로 사용자 삭제하기를 참조하세요.

경고

고객 프로필 삭제는 취소할 수 없습니다. 삭제 작업은 사용자를 영구적으로 제거하므로 데이터에 불일치가 생길 수 있습니다. 자세한 내용은 고객 프로필 삭제의 영향을 참조하세요.

2단계: 서비스 계정 생성 및 권한 부여

Braze가 테이블에 연결하고 데이터를 읽는 데 사용할 서비스 계정을 GCP에서 생성합니다. 서비스 계정에는 다음 권한이 있어야 합니다.

• BigQuery Connection User: Braze가 연결을 생성할 수 있도록 허용합니다.
• BigQuery User: Braze가 쿼리를 실행하고, 데이터 세트 메타데이터를 읽고, 테이블 목록을 조회할 수 있는 액세스 권한을 제공합니다.
• BigQuery Data Viewer: Braze가 데이터 세트와 그 내용을 볼 수 있는 액세스 권한을 제공합니다.
• BigQuery Job User: Braze가 작업을 실행할 수 있는 액세스 권한을 제공합니다.

3단계: 인증 설정

Braze는 다음 인증 방법 중 하나로 서비스 계정에 액세스할 수 있습니다.

Workload Identity Federation

Workload Identity Federation(WIF)을 사용하면 Braze가 자체 AWS 환경에서 단기 ID로 Google Cloud에 인증한 다음, Braze용으로 생성한 서비스 계정을 가장합니다. 해당 ID를 워크스페이스에 대해서만 신뢰하도록 프로젝트를 구성합니다. 서비스 계정 키를 생성하거나 공유할 필요가 없습니다.

WIF는 Google Cloud 프로젝트당 한 번만 설정합니다. 하나의 WIF 자격 증명으로 BigQuery 소스와 Google Cloud Storage 소스를 모두 지원합니다. Google Cloud Storage 소스에 대해 이미 이 단계를 완료했다면 기존 서비스 계정에 이 소스에 대한 권한을 부여하고 이 섹션의 나머지 내용은 건너뛰세요.

사전 요구 사항

Google Cloud 콘솔에서 이 단계를 완료하려면 Workload Identity 풀을 생성하고, 서비스 계정과 데이터에 대한 IAM(Identity and Access Management) 정책을 관리할 수 있는 권한이 필요합니다. 예를 들어, Workload Identity Pool Admin(roles/iam.workloadIdentityPoolAdmin) 및 Service Account Admin(roles/iam.serviceAccountAdmin) 역할을 사용할 수 있습니다.

워크스페이스의 주체만 신뢰하기

경고

자격 증명 양식에 있는 전체 Braze 주체 Amazon 리소스 이름(ARN)에 액세스 권한을 부여하세요. Braze AWS 역할이나 AWS 계정에는 액세스 권한을 부여하지 마세요. 역할 수준 또는 계정 수준으로 권한을 부여하면 다른 Braze 고객이 회원님의 데이터를 읽을 수 있게 됩니다.

동일한 Braze 인스턴스에 있는 모든 Braze 워크스페이스는 같은 AWS 역할을 사용합니다. 주체 ARN 끝에 있는 세션 이름, 즉 워크스페이스 ID만 회원님에게 고유합니다.

AWS 공급자에 대한 Google의 기본 속성 매핑은 aws_role을 세션 이름이 없는 역할 ARN으로 설정합니다. 따라서 principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN처럼 aws_role 값과 일치하는 ID에 액세스 권한을 부여하면, 회원님의 워크스페이스를 포함해 인스턴스의 모든 Braze 워크스페이스를 신뢰하게 됩니다.

데이터 범위를 워크스페이스로 한정하려면 다음을 따르세요.

• subject가 전체 Braze 주체 ARN인 ID에만 액세스 권한을 부여하세요. 이는 principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN 주체입니다.
• All identities in the pool이나 aws_role 또는 account로 필터링한 ID에는 액세스 권한을 부여하지 마세요.
• AWS 계정이나 역할만 확인하는 속성 조건을 작성하지 마세요.
• google.subject에 대한 기본 속성 매핑인 assertion.arn을 그대로 유지하세요.

Braze 주체 ARN은 워크스페이스와 Braze 인스턴스마다 다르며, Braze는 Snowflake 같은 다른 소스와는 별도의 AWS 역할을 Google 소스에 사용합니다. 항상 연결하려는 워크스페이스의 BigQuery 또는 Google Cloud Storage 자격 증명 양식에서 값을 복사하세요.

Braze 주체 ARN 복사하기

Braze에서 BigQuery 소스 생성을 시작하고 인증 방법으로 Workload Identity Federation을 선택합니다. 자격 증명 양식의 1단계인 Copy the Braze principal ARN에 있는 값을 복사하고, 양식은 열어 둔 상태로 유지하세요.

필드에 Unavailable이 표시되면 회원님의 Braze 인스턴스에서는 WIF를 사용할 수 없습니다. 대신 서비스 계정 키를 사용하세요.

필요한 API 활성화하기

Google Cloud 콘솔에서 APIs & Services > Library로 이동하여 프로젝트에 대해 다음 API를 활성화합니다.

• IAM Service Account Credentials API
• Security Token Service API
• Identity and Access Management (IAM) API

Workload Identity 풀 및 공급자 생성하기

1. IAM & Admin > Workload Identity Federation으로 이동한 다음 Create pool을 선택합니다.
2. 풀 이름(예: “Braze CDI”)을 입력합니다. Pool ID를 기록해 두고 Continue를 선택합니다.
3. Select a provider에서 AWS를 선택합니다.
4. 공급자 이름(예: “Braze AWS”)을 입력하고 Provider ID를 기록해 둡니다.
5. AWS account ID에 Braze 주체 ARN에서 arn:aws:sts:: 뒤에 오는 12자리 숫자를 입력한 다음 Continue를 선택합니다.
6. Configure provider attributes에서 google.subject = assertion.arn을 포함한 기본 매핑을 그대로 유지합니다.
7. Save를 선택합니다.

풀 ID와 공급자 ID는 소문자, 숫자, 하이픈을 사용하여 4~32자로 작성해야 합니다.

공급자를 회원님의 주체로 제한하기(선택 사항)

심층 방어를 위해 공급자가 워크스페이스의 주체만 허용하도록 속성 조건을 추가하세요. 그러면 Google이 서비스 계정 권한을 확인하기 전에 토큰 교환 단계에서 다른 모든 ID를 거부합니다.

1. 풀에서 공급자를 선택한 다음 Edit를 선택합니다.
2. Attribute conditions에서 Add condition을 선택합니다.

3. 다음 조건을 입력하되, BRAZE_PRINCIPAL_ARN을 자격 증명 양식에서 복사한 전체 값으로 바꿉니다.

   
   1
   
    assertion.arn == 'BRAZE_PRINCIPAL_ARN'
   
   

4. Save를 선택합니다.

이 조건은 공급자를 하나의 Braze 워크스페이스 전용으로 만듭니다. 다른 워크스페이스를 연결하려면 해당 워크스페이스용 공급자를 별도로 생성하거나, assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN']처럼 두 주체를 모두 나열하세요.

Braze 주체를 서비스 계정에 바인딩하기

워크스페이스의 주체에 서비스 계정을 가장할 수 있는 권한을 부여합니다.

1. IAM & Admin > Workload Identity Federation으로 이동한 다음 풀을 선택합니다.
2. Grant access를 선택한 다음 Grant access using service account impersonation을 선택합니다.
3. Service account에서 Braze용으로 생성한 서비스 계정을 선택합니다.
4. Select principals에서 Only identities matching the filter를 선택합니다.
5. Attribute name에서 subject를 선택합니다. Attribute value에는 자격 증명 양식의 전체 Braze 주체 ARN을 붙여넣습니다.
6. Save를 선택합니다. Google에서 클라이언트 라이브러리 구성 파일을 다운로드하라는 메시지가 표시되면 Dismiss를 선택합니다. Braze에는 이 파일이 필요하지 않습니다.

이렇게 하면 서비스 계정에 대한 Workload Identity User 역할(roles/iam.workloadIdentityUser)이 다음 형식의 주체에 부여됩니다.

1

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN

확인하려면 서비스 계정을 열고 Permissions 탭을 선택하세요. Workload Identity User 역할에 회원님의 전체 Braze 주체 ARN으로 끝나는 이 주체가 표시되어야 합니다.

경고

All identities in the pool을 선택하지 말고, aws_role로 필터링하지 마세요. Braze 인스턴스의 모든 Braze 워크스페이스는 같은 AWS 역할을 공유하므로, 두 방법 모두 이 워크스페이스 전체와 일치하게 됩니다. 자세한 내용은 워크스페이스의 주체만 신뢰하기를 참조하세요.

이 역할은 서비스 계정에만 부여하세요. 프로젝트 수준으로 부여하면 주체가 프로젝트의 모든 서비스 계정을 가장할 수 있게 됩니다.

IAM 변경 사항이 적용되기까지 몇 분 정도 걸릴 수 있습니다. 액세스 권한을 부여한 직후 연결 테스트가 실패하면 몇 분 기다렸다가 다시 시도하세요.

서비스 계정에는 데이터에 대한 액세스 권한도 필요합니다. 서비스 계정에 이 소스에 대한 권한을 부여했는지 확인하세요. BigQuery와 Google Cloud Storage에 하나의 자격 증명을 사용하는 경우, 두 권한 세트를 모두 같은 서비스 계정에 부여하세요.

Braze에 값 입력하기

Braze 자격 증명 양식으로 돌아가 Google Cloud 콘솔에서 확인한 다음 값을 입력합니다.

Braze는 프로젝트 번호, 풀 ID, 공급자 ID를 결합하여 오디언스를 만듭니다. 오디언스는 Braze의 요청을 어떤 공급자가 검증하는지 Google에 알려줍니다. 기본적으로 공급자는 자체 리소스 이름을 오디언스로 허용합니다. 공급자에 커스텀 허용 오디언스를 설정한 경우 공급자의 전체 리소스 이름을 포함하세요.

Braze의 연결 테스트 방식

Braze에서 연결을 테스트하면 Braze는 구성이 회원님의 워크스페이스만 신뢰하는지도 확인합니다. 테스트 중에 Braze는 다음 형식처럼 모두 0으로 된 테스트 세션 이름으로 동일한 교환을 시도합니다.

1

assumed-role/cdi-gcs-bigquery-sync-<deployment>/000000000000000000000000

구성은 토큰 교환 단계 또는 서비스 계정을 가장하려는 단계에서 이 ID를 거부해야 합니다. 두 단계가 모두 성공하면 구성이 워크스페이스의 주체 이외의 ID를 신뢰하는 것이므로 테스트가 실패합니다. 이 문제를 해결하려면 구성이 워크스페이스 이외의 ID를 신뢰함을 참조하세요.

선택 사항인 속성 조건을 설정한 경우 Google은 토큰 교환 단계에서 테스트 ID를 거부합니다. 그렇지 않은 경우에는 테스트 ID가 서비스 계정을 가장하려고 할 때 Google이 거부합니다. 어느 쪽이든 테스트는 통과합니다.

연결을 테스트할 때마다 Google Cloud 감사 로그에 이 거부된 시도가 표시될 수 있습니다. 이는 예상된 동작입니다. 이 시도는 Braze의 확인 과정에서 발생하며, 누구에게도 데이터에 대한 액세스 권한을 주지 않습니다.

이 테스트 세션만 거부하는 조건을 추가하지 마세요. 이러한 조건은 테스트를 통과하지만 구성은 여전히 다른 Braze 워크스페이스를 신뢰하게 됩니다.

Braze 액세스 제거하기

Braze가 데이터에 액세스하지 못하도록 하려면 서비스 계정의 Permissions 탭에서 Braze 주체에 대한 Workload Identity User 역할을 제거하거나 공급자를 삭제하세요.

gcloud CLI로 설정하기

명령줄을 선호하는 경우, 다음 명령으로 API를 활성화하고, 풀과 공급자를 생성하고, Braze 주체를 서비스 계정에 바인딩할 수 있습니다. 첫 번째 블록의 값을 바꾸고, Braze 주체 ARN은 복사한 그대로 붙여넣으세요.

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

PROJECT_ID="YOUR-PROJECT-ID"
POOL_ID="braze-cdi"
PROVIDER_ID="braze-aws"
SA_EMAIL="YOUR-SERVICE-ACCOUNT-EMAIL"
BRAZE_PRINCIPAL_ARN="PASTE-THE-BRAZE-PRINCIPAL-ARN-FROM-YOUR-CREDENTIAL-FORM"

PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
BRAZE_AWS_ACCOUNT_ID="$(echo "$BRAZE_PRINCIPAL_ARN" | cut -d: -f5)"

gcloud services enable iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
  --project="$PROJECT_ID"

gcloud iam workload-identity-pools create "$POOL_ID" \
  --project="$PROJECT_ID" --location="global" --display-name="Braze CDI"

gcloud iam workload-identity-pools providers create-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --account-id="$BRAZE_AWS_ACCOUNT_ID"

# Optional: restrict the provider to your principal
gcloud iam workload-identity-pools providers update-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --attribute-condition="assertion.arn == '${BRAZE_PRINCIPAL_ARN}'"

gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --project="$PROJECT_ID" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${BRAZE_PRINCIPAL_ARN}"

Service account key

Braze는 서비스 계정의 JSON 키로 인증합니다. 기존 서비스 계정 키 자격 증명은 계속 작동하므로 마이그레이션할 필요가 없습니다.

Google Cloud 콘솔에서 서비스 계정을 열고 키 > 키 추가 > 새 키 만들기로 이동한 다음 JSON을 선택하세요. 그런 다음 키 파일을 다운로드합니다. 이 파일은 소스를 생성할 때 Braze에 업로드하게 됩니다.

또는 gcloud를 사용할 수도 있습니다.

1
2

gcloud iam service-accounts keys create braze-cdi-key.json \
  --iam-account=SERVICE_ACCOUNT_EMAIL

SERVICE_ACCOUNT_EMAIL을 서비스 계정의 이메일 주소로 바꾸세요. 자세한 내용은 서비스 계정 키 만들기 및 삭제를 참조하세요.

4단계: Braze IP에 대한 액세스 허용

네트워크 정책을 사용 중이라면 Braze에 BigQuery 인스턴스에 대한 네트워크 액세스 권한을 부여해야 합니다. Braze 대시보드 지역에 해당하는 다음 IP의 액세스를 허용하세요.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

5단계: Braze 대시보드에서 새 소스 생성

Braze 대시보드에서 데이터 설정 > 클라우드 데이터 수집 > 소스로 이동하여 데이터 소스 추가를 선택한 다음 Google BigQuery를 선택합니다.

5.1단계: BigQuery 연결 정보 및 소스 테이블 추가

소스 이름을 입력한 다음 BigQuery 자격 증명과 구성을 입력합니다.

• 자격 증명 이름에는 Braze에서 이 자격 증명을 식별하는 데 도움이 되는 레이블을 입력합니다.
• 인증 방법으로는 3단계에서 설정한 방법을 선택하고 해당 자격 증명을 입력합니다. Workload Identity Federation의 경우 다음을 입력합니다: Project number, Workload identity pool ID, Provider ID, and Service account email. Service account key의 경우 다음을 입력합니다: JSON key file for the service account.

그런 다음 나머지 구성 필드를 입력합니다.

5.2단계: 연결 테스트 및 소스에 연결

다음으로 연결 테스트를 선택합니다. 테스트에 성공하면 나머지 설정을 완료하고 소스에 연결을 클릭합니다. 연결에 실패하면 문제 해결에 도움이 되는 오류 메시지가 표시됩니다.

6단계: Braze 대시보드에서 새 동기화 생성

데이터 설정 > 클라우드 데이터 수집 > 동기화로 이동하여 데이터 동기화 생성을 선택합니다.

동기화 세부 정보 구성 및 데이터 정의

동기화 이름을 입력합니다. 그런 다음 활성 소스와 동기화 데이터 유형을 선택합니다. 다음으로 비주얼 또는 테이블을 선택하고 소스 테이블을 입력하거나, SQL을 선택하여 커스텀 SQL 쿼리를 작성합니다. 마지막으로 미리 보기 및 검증을 선택합니다.

검증에 성공하면 데이터 미리 보기가 표시됩니다. 계속하려면 다음: 알림을 선택하세요. 검증에 실패하면 문제 해결에 도움이 되는 오류 메시지가 표시됩니다.

참고

다음 단계로 진행하려면 먼저 동기화 검증에 성공해야 합니다. 동기화 생성 페이지를 닫아야 하는 경우 초안으로 저장을 선택하여 진행 중인 작업을 보관하세요.

알림 기본 설정 추가

동기화 오류 알림을 받을 연락처 이메일을 입력합니다. Braze는 이 연락처 정보를 사용하여 예기치 않은 테이블 액세스 손실과 같은 통합 오류에 대한 알림을 보냅니다.

연락처 이메일로는 테이블 누락, 권한 문제 등 전역 또는 동기화 수준의 오류 알림만 전송됩니다. 행 수준 문제에 대한 알림은 전송되지 않습니다. 전역 오류는 동기화 실행을 막는 연결상의 심각한 문제를 나타냅니다.

이러한 문제에는 다음이 포함될 수 있습니다.

• 연결 문제
• 리소스 부족
• 권한 문제
• 카탈로그 티어의 공간 부족(카탈로그 동기화에만 해당)

스케줄 설정

마지막으로 동기화를 비반복 또는 반복으로 구성합니다.

비반복 동기화는 대시보드에서 지금 동기화를 선택하거나 동기화 트리거 엔드포인트를 호출할 때만 실행됩니다.

반복 동기화는 짧게는 5분마다, 길게는 한 달에 한 번까지 실행할 수 있습니다. 기본적으로 대시보드에서 설정할 수 있는 가장 짧은 간격은 15분이며, 이를 통해 웨어하우스 컴퓨팅 비용과 요청량을 관리할 수 있습니다. 5분 간격으로 동기화하려면 Braze 지원팀 또는 고객 성공 매니저에게 문의하세요. Braze는 반복 동기화를 UTC 기준으로 스케줄링합니다.

참고

통합이 초안 상태에서 활성 상태로 전환되려면 먼저 검증에 성공해야 합니다. 생성 페이지를 닫아도 통합은 저장되며, 세부 정보 페이지로 돌아와 변경하고 검증할 수 있습니다.

동기화 실행

활성화된 동기화는 설정 시 구성한 스케줄에 따라 실행됩니다. 스케줄과 별도로 동기화를 실행하거나 최신 데이터를 가져오려면 지금 동기화를 선택하세요. 이 실행은 이후 정기적으로 예약된 동기화에 영향을 주지 않습니다. 데이터가 업데이트될 때 자동으로 동기화를 시작하려면 파이프라인에서 동기화 트리거 엔드포인트를 호출하세요.

추가 통합 또는 사용자 설정(선택 사항)

Braze와 여러 통합을 설정할 수 있습니다. 추가 동기화를 생성할 때 같은 BigQuery 계정에 연결한다면 기존 자격 증명을 재사용할 수 있습니다.

여러 통합에서 같은 사용자를 재사용하는 경우, 모든 활성 동기화에서 해당 사용자를 제거하기 전까지는 Braze 대시보드에서 사용자를 삭제할 수 없습니다.

BigQuery를 연결된 소스로 사용

연결된 소스는 데이터를 Braze로 동기화하는 방식을 대체하는 제로 카피 방식입니다. Braze는 기본 데이터를 복사하지 않고 BigQuery 인스턴스를 직접 쿼리하여 CDI 세그먼트를 구축합니다. 개념, 제한 사항, 비용 영향은 연결된 소스를 참조하세요.

1단계: 서비스 계정 생성 및 권한 부여

Braze가 테이블에 연결하고 데이터를 읽는 데 사용할 서비스 계정을 GCP에서 생성합니다. 서비스 계정에는 다음 권한이 있어야 합니다.

• BigQuery Connection User: Braze가 연결을 생성할 수 있도록 허용합니다.
• BigQuery User: Braze가 쿼리를 실행하고, 데이터 세트 메타데이터를 읽고, 테이블 목록을 조회할 수 있는 액세스 권한을 제공합니다.
• BigQuery Data Viewer: Braze가 데이터 세트와 그 내용을 볼 수 있는 액세스 권한을 제공합니다.
• BigQuery Job User: Braze가 작업을 실행할 수 있는 액세스 권한을 제공합니다.
• bigquery.tables.create: Braze가 세그먼트 새로 고침 중에 임시 테이블을 생성할 수 있는 액세스 권한을 제공합니다.

이 서비스 계정은 CDI 세그먼트 확장에서 사용할 수 있는 테이블 목록을 생성하고, 소스 테이블을 쿼리하여 새 세그먼트를 만드는 데 사용됩니다. 연결된 소스가 생성되면 Braze는 소스 스키마에서 사용자가 사용할 수 있는 모든 테이블의 이름과 설명을 검색합니다.

데이터 세트의 모든 테이블에 대한 액세스 권한을 부여하거나 특정 테이블에만 권한을 부여할 수 있습니다. Braze 역할이 액세스할 수 있는 테이블은 모두 CDI 세그먼트 확장에서 쿼리할 수 있습니다.

Braze에서 세그먼트를 업데이트하기 전에 Braze가 CDI 세그먼트 확장 쿼리 결과로 테이블을 생성할 수 있도록 create table 권한이 필요합니다. Braze는 세그먼트마다 임시 테이블을 하나씩 생성하며, 이 테이블은 Braze가 세그먼트를 업데이트하는 동안에만 유지됩니다.

서비스 계정을 생성하고 권한을 부여한 후에는 3단계: 인증 설정의 방법 중 하나로 Braze가 서비스 계정에 액세스하는 방식을 설정하세요. 이 프로젝트에 이미 워크로드 아이덴티티 제휴를 설정했다면 이를 재사용할 수 있습니다. 기존 서비스 계정에 이 단계의 권한을 부여하세요.

네트워크 액세스 설정은 4단계와 동일합니다.

2단계: Braze에서 연결된 소스 생성

데이터 설정 > 클라우드 데이터 수집 > 연결된 소스로 이동하여 데이터 소스 추가를 선택한 다음 Google BigQuery를 선택합니다.

소스 설정에서 다음을 입력합니다.

• 자격 증명: 자격 증명 이름 및 인증 방법에 해당하는 필드. Workload Identity Federation의 경우 다음을 입력합니다: Project number, Workload identity pool ID, Provider ID, and Service account email. Service account key의 경우 다음을 입력합니다: JSON key file for the service account.
• 구성: 프로젝트 및 데이터 세트

연결된 소스의 이름을 지정합니다. 이 이름은 새 CDI 세그먼트 확장을 생성할 때 사용 가능한 소스 목록에 표시됩니다.

이 소스의 최대 실행 시간을 구성합니다. Braze는 최대 실행 시간을 초과하는 모든 쿼리를 자동으로 중단합니다. 허용되는 최대 실행 시간은 60분이며, 실행 시간을 낮추면 BigQuery 계정에 발생하는 비용을 줄일 수 있습니다. 이 설정은 이 소스를 사용하는 동기화와 CDI 세그먼트 확장을 포함해 이 소스를 통해 실행되는 쿼리에 적용됩니다.

연결 테스트를 선택하여 사용자에게 표시되는 테이블 목록이 예상과 같은지 확인한 다음 완료를 선택합니다. 이제 연결된 소스가 생성되었으며 CDI 세그먼트 확장에서 사용할 준비가 되었습니다.

Braze와 여러 연결된 소스를 설정할 수 있지만, 각 소스는 서로 다른 데이터 세트에 연결하도록 구성해야 합니다. 추가 소스를 생성할 때 같은 BigQuery 계정에 연결한다면 기존 자격 증명을 재사용할 수 있습니다.

기존 열로 페이로드 형식 지정

내부적으로 각 속성을 별도의 열에 저장하는 것을 선호한다면, Braze와의 동기화를 채우기 위해 해당 열을 JSON 문자열로 변환해야 합니다. BigQuery에서 다음 쿼리를 사용해 소스 열을 CDI 필드 형식으로 변환하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
     attribute_2 STRING,
     attribute_3 NUMERIC,
     my_user_id STRING);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        'attribute_1' AS attribute_1,
        'attribute_2'AS attribute_2,
        'yet_another_attribute'AS attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

추가 최적화 지침은 클라우드 데이터 수집 모범 사례를 참조하세요.

문제 해결

연결 테스트가 느리게 실행됨

연결 테스트는 데이터 웨어하우스에서 실행되므로 웨어하우스 용량을 늘리면 속도가 향상될 수 있습니다. 서버리스 SQL 인스턴스를 사용하면 웜업 시간이 최소화되고 쿼리 처리량이 향상되지만, 통합 비용이 약간 높아질 수 있습니다.

사용자에게 테이블을 쿼리할 권한이 없음

이 오류가 발생하면 테이블을 쿼리할 수 있도록 사용자 권한을 추가하세요.

사용량이 커스텀 할당량을 초과함

이 오류가 발생하면 현재 속도로 계속 동기화할 수 있도록 할당량을 업데이트해야 합니다.

{region} 위치에서 테이블을 찾을 수 없음

이 오류가 발생하면 테이블이 올바른 프로젝트와 데이터 세트에 있는지 확인하세요.

잘못된 JWT 서명

이 오류가 발생하면 계정에 BigQuery API 서비스가 활성화되어 있는지 확인하세요.

구성이 워크스페이스 이외의 ID를 신뢰합니다

Workload Identity Federation을 사용하는 경우 연결 테스트가 다음 오류와 함께 실패할 수 있습니다.

Your workload identity pool trusts every Braze customer, not only this workspace. Braze authenticated against it with a test identity (000000000000000000000000) that belongs to no Braze workspace, and your Google Cloud project accepted it, so another Braze customer could read this data. Grant the Workload Identity User role on your service account to the full Braze principal shown on the credential screen (principal://…/subject/<full ARN>) rather than to the role (principalSet://…/attribute.aws_role/…); restricting the pool provider’s attribute condition to that same principal works as well. Then test the connection again.

이 오류는 Braze가 연결을 테스트하는 방법에 설명된 대로 Google이 토큰 교환과 서비스 계정 가장 단계 모두에서 Braze 테스트 ID를 수락했다는 의미입니다. 이 오류는 일반적으로 서비스 계정이 풀의 모든 ID 또는 aws_role로 필터링된 ID에 액세스 권한을 부여할 때 발생합니다.

이 오류를 해결하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 서비스 계정을 열고 Permissions 탭을 선택합니다.
2. principalSet://으로 시작하고 풀을 참조하는 Workload Identity User 역할이 있는 모든 주 구성원을 찾습니다. 각 주 구성원에서 해당 역할을 제거합니다.
3. Braze 주 구성원을 서비스 계정에 바인딩에 설명된 대로 전체 주 구성원에 해당 역할이 있는지 확인합니다.
4. IAM & Admin > IAM으로 이동하여 풀에 대한 프로젝트 수준의 Workload Identity User 권한 부여가 있는지 확인합니다. 있다면 제거합니다.
5. 연결을 다시 테스트합니다.

또는 제공업체를 주 구성원으로 제한(선택 사항)에 설명된 대로 제공업체의 속성 조건을 전체 주 구성원으로 제한할 수도 있습니다. 그러면 Google이 토큰 교환 단계에서 다른 모든 ID를 거부합니다. 다만 이 경우에도 전체 주 구성원에게만 액세스 권한을 부여하는 것을 권장합니다.

Braze가 풀이 이 워크스페이스만 신뢰하는지 확인할 수 없습니다

Workload Identity Federation을 사용하는 경우 연결 테스트가 다음 오류와 함께 실패할 수 있습니다.

Braze could not confirm that your workload identity pool trusts only this workspace. The check needs Google to explicitly refuse an identity that is not yours, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.

Braze가 연결을 테스트하는 방법에 설명된 Braze 검사가 결과를 얻지 못했다는 의미입니다. 예를 들어 네트워크 오류나 일시적인 Google Cloud 오류로 인해 검사가 중단되었을 수 있습니다. 이 오류는 구성이 지나치게 광범위하다는 의미가 아닙니다. 연결을 다시 테스트하세요. 오류가 계속 발생하면 Braze 지원팀에 문의하세요.

Braze가 서비스 계정을 가장할 때 권한이 거부됩니다

Workload Identity Federation을 사용 중이고 연결 테스트가 iam.serviceAccounts.getAccessToken에 대한 권한 오류로 실패하면 다음을 확인하세요.

• 서비스 계정의 Permissions 탭에 같은 워크스페이스의 BigQuery 또는 Google Cloud Storage 자격 증명 양식에서 복사한 전체 Braze 주 구성원 ARN으로 끝나는 주 구성원에 대한 Workload Identity User 역할이 나열되어 있는지
• IAM Service Account Credentials API가 활성화되어 있는지
• 액세스 권한을 부여한 후 몇 분이 지났는지

토큰 교환이 거부됩니다

Workload Identity Federation을 사용 중이고 연결 테스트가 Google Security Token Service 토큰 교환 단계에서 실패하면 다음을 확인하세요.

• Braze에 입력한 프로젝트 번호, 풀 ID, 제공업체 ID가 Google Cloud 구성과 일치하는지
• 제공업체의 AWS 계정 ID가 Braze 주 구성원 ARN의 계정 ID와 일치하는지
• 속성 조건을 설정한 경우, 복사한 그대로의 전체 주 구성원 ARN이 포함되어 있는지
• 커스텀 허용 오디언스를 설정한 경우, 제공업체의 전체 리소스 이름이 포함되어 있는지
• 풀과 제공업체가 활성화되어 있는지

SQL 검사를 실행할 위치

CDI 통합에서 사용하는 것과 같은 테이블 또는 뷰를 대상으로 BigQuery Studio SQL 작업 공간에서 직접 검증 검사를 실행하세요. 자세한 내용은 BigQuery Studio 소개를 참조하세요.

관련 페이지

• 필수 열과 페이로드 형식은 테이블 설정을 참조하세요.
• 동기화 일정 설정과 데이터 포인트 효율성은 모범 사례를 참조하세요.
• 동기화 실행 모니터링은 동기화 로그 및 관측 가능성을 참조하세요.
• 모든 소스에 공통된 질문은 FAQ를 참조하세요.