Google Cloud Storage용 클라우드 데이터 수집
이 페이지에서는 클라우드 데이터 수집(CDI)을 사용하여 Google Cloud Storage(GCS)의 데이터를 Braze로 동기화하는 데 필요한 모든 내용을 다룹니다. 생성할 Google Cloud 리소스, Braze에서 소스를 연결하고 동기화를 생성하는 방법, 데이터 유형별 파일 형식, GCS 관련 문제 해결 방법을 설명합니다.
작동 방식
Google Cloud Storage 통합은 스케줄 기반이 아닌 이벤트 기반으로 작동합니다. 버킷에서 새 파일이 확정되면 GCS가 Pub/Sub 주제에 OBJECT_FINALIZE 알림을 게시합니다. Braze는 Pub/Sub 구독에서 이 알림을 받아 새 파일을 수집합니다.
통합에는 다음 리소스가 필요합니다.
- 데이터 저장용 Cloud Storage 버킷
- 새 파일 알림용 Pub/Sub 주제 및 구독
- Braze가 지원되는 인증 방법 중 하나로 액세스하는 서비스 계정
GCP 용어 정의
| 용어 | 정의 |
|---|---|
| Google Cloud 프로젝트 | 프로젝트는 모든 Google Cloud 리소스를 구성하며, 고유한 프로젝트 ID와 프로젝트 번호로 식별됩니다. |
| Cloud Storage 버킷 | 버킷은 Braze가 수집할 데이터 파일을 보관하는 컨테이너입니다. |
| Pub/Sub 주제 | 주제는 Cloud Storage 버킷에서 새 파일 알림을 수신하는 이름이 지정된 리소스입니다. |
| Pub/Sub 구독 | 구독은 주제에 연결되어 해당 주제의 메시지를 전달합니다. Braze는 풀(pull) 구독에서 새 파일 알림을 받습니다. |
| 서비스 계정 | 서비스 계정은 Braze가 버킷과 구독에 액세스할 때 사용하는 비인간 ID입니다. Braze는 워크로드 아이덴티티 제휴를 통해 서비스 계정을 가장하거나, 업로드한 JSON 키를 사용합니다. |
| 워크로드 아이덴티티 제휴 | 워크로드 아이덴티티 제휴(WIF)를 사용하면 Braze가 수명이 짧은 ID로 서비스 계정을 가장하므로 키를 생성하거나 업로드할 필요가 없습니다. |
| IAM 역할 | Identity and Access Management(IAM) 역할은 버킷과 구독에서 서비스 계정에 할당하는 권한 모음입니다. |
Google Cloud에서 클라우드 데이터 수집 설정하기
1단계: Cloud Storage 버킷 생성하기
Google Cloud 콘솔에서 Cloud Storage > Buckets > Create로 이동합니다. 프로젝트 ID와 버킷 이름을 기록해 두세요. Braze에서 소스를 구성할 때 필요합니다. 권한을 IAM으로 관리할 수 있도록 균일한 버킷 수준 액세스를 활성화하는 것을 권장합니다.
2단계: Pub/Sub 주제 및 구독 생성하기
Google Cloud 콘솔에서 Pub/Sub > Topics > Create topic으로 이동합니다. Google이 기본 구독을 생성하도록 하거나 별도로 구독을 생성할 수 있습니다. 그런 다음 해당 주제에 풀(pull) 구독을 생성합니다.
구독 ID를 기록해 두세요. 동기화를 생성할 때 Braze에는 주제가 아닌 구독이 필요합니다. 구독은 반드시 풀 구독이어야 합니다.
이 구독에 데드레터 대기줄을 구성하지 마세요. Braze는 클라우드 데이터 수집 구독에 대해 데드레터 대기줄을 지원하지 않습니다. 자세한 내용은 Google Cloud 설명서의 데드레터 주제를 참조하세요.
3단계: 버킷 알림을 주제로 전송하기
Cloud Storage에서 Pub/Sub로의 알림은 Google Cloud 콘솔에서 생성할 수 없습니다. gcloud(여기에 표시됨), Terraform 또는 JSON API를 사용해야 합니다. 자세한 내용은 Google Cloud 설명서의 Cloud Storage용 Pub/Sub 알림 구성을 참조하세요.
먼저 Cloud Storage 서비스 에이전트에 주제에 게시할 수 있는 권한을 할당한 다음, OBJECT_FINALIZE에 대한 알림을 생성합니다. OBJECT_FINALIZE 이벤트는 버킷에서 새 객체가 생성되거나 확정될 때마다 발생합니다.
# Get the Cloud Storage service agent for your project
gcloud storage service-agent --project=YOUR-PROJECT-ID
# Assign it Pub/Sub Publisher on the topic
gcloud pubsub topics add-iam-policy-binding YOUR-TOPIC \
--project=YOUR-PROJECT-ID \
--member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
--role="roles/pubsub.publisher"
# Create the OBJECT_FINALIZE notification (optionally scope to a folder with --object-prefix)
gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
--topic=YOUR-TOPIC \
--event-types=OBJECT_FINALIZE \
--payload-format=json
YOUR-PROJECT-ID, YOUR-BUCKET-NAME, YOUR-TOPIC을 실제 값으로 바꾸세요. YOUR-PROJECT-NUMBER는 서비스 에이전트 이메일 주소에 포함된 숫자 식별자로, 프로젝트 ID와는 다릅니다. Google Cloud 콘솔의 Dashboard에서 확인하거나 gcloud projects describe YOUR-PROJECT-ID --format="value(projectNumber)"를 실행하여 확인할 수 있습니다.
4단계: 서비스 계정 생성하기
Google Cloud 콘솔에서 IAM & Admin > Service Accounts > Create service account로 이동합니다. 이 예시에서는 계정 이름으로 braze-cdi-gcs를 사용합니다.
5단계: 권한 할당하기
커넥터에는 버킷에 대한 storage.buckets.get, storage.objects.get, storage.objects.list 권한과 구독에 대한 pubsub.subscriptions.consume 권한, 정확히 이 권한들이 필요합니다. 커스텀 역할 또는 사전 정의된 역할로 이 권한을 할당할 수 있습니다.
커스텀 역할: 해당 권한만 포함하는 커스텀 역할을 생성하고 버킷과 구독에 바인딩합니다.
gcloud iam roles create brazeCdiGcs --project=YOUR-PROJECT-ID \
--title="Braze CDI GCS" \
--permissions=storage.buckets.get,storage.objects.get,storage.objects.list,pubsub.subscriptions.consume \
--stage=GA
gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
--member="serviceAccount:[email protected]" \
--role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"
gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
--project=YOUR-PROJECT-ID \
--member="serviceAccount:[email protected]" \
--role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"
사전 정의된 역할: 커스텀 역할 대신 버킷에 roles/storage.objectViewer와 roles/storage.legacyBucketReader를, 구독에 roles/pubsub.subscriber를 할당합니다. objectViewer 역할은 storage.objects.get과 storage.objects.list를 제공하고, legacyBucketReader는 storage.buckets.get을 제공합니다.
6단계: 인증 설정하기
Braze는 다음 인증 방법 중 하나로 서비스 계정에 액세스할 수 있습니다.
| 방법 | Braze의 인증 방식 | Braze에 입력할 내용 |
|---|---|---|
| Workload Identity Federation | Braze impersonates your service account with a short-lived identity, so you don’t create or upload a key. | Project number, Workload identity pool ID, Provider ID, and Service account email |
| Service account key | Braze authenticates with a JSON key that you create for your service account. | JSON key file for the service account |
Workload Identity Federation
Workload Identity Federation(WIF)을 사용하면 Braze가 자체 AWS 환경에서 단기 ID로 Google Cloud에 인증한 다음, Braze용으로 생성한 서비스 계정을 가장합니다. 해당 ID를 워크스페이스에 대해서만 신뢰하도록 프로젝트를 구성합니다. 서비스 계정 키를 생성하거나 공유할 필요가 없습니다.
WIF는 Google Cloud 프로젝트당 한 번만 설정합니다. 하나의 WIF 자격 증명으로 Google Cloud Storage 소스와 BigQuery 소스를 모두 지원합니다. BigQuery 소스에 대해 이미 이 단계를 완료했다면 기존 서비스 계정에 이 소스에 대한 권한을 부여하고 이 섹션의 나머지 내용은 건너뛰세요.
사전 요구 사항
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에서 Google Cloud Storage 소스 생성을 시작하고 인증 방법으로 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 풀 및 공급자 생성하기
- IAM & Admin > Workload Identity Federation으로 이동한 다음 Create pool을 선택합니다.
- 풀 이름(예: “Braze CDI”)을 입력합니다. Pool ID를 기록해 두고 Continue를 선택합니다.
- Select a provider에서 AWS를 선택합니다.
- 공급자 이름(예: “Braze AWS”)을 입력하고 Provider ID를 기록해 둡니다.
- AWS account ID에 Braze 주체 ARN에서
arn:aws:sts::뒤에 오는 12자리 숫자를 입력한 다음 Continue를 선택합니다. - Configure provider attributes에서
google.subject=assertion.arn을 포함한 기본 매핑을 그대로 유지합니다. - Save를 선택합니다.
풀 ID와 공급자 ID는 소문자, 숫자, 하이픈을 사용하여 4~32자로 작성해야 합니다.
공급자를 회원님의 주체로 제한하기(선택 사항)
심층 방어를 위해 공급자가 워크스페이스의 주체만 허용하도록 속성 조건을 추가하세요. 그러면 Google이 서비스 계정 권한을 확인하기 전에 토큰 교환 단계에서 다른 모든 ID를 거부합니다.
- 풀에서 공급자를 선택한 다음 Edit를 선택합니다.
- Attribute conditions에서 Add condition을 선택합니다.
-
다음 조건을 입력하되,
BRAZE_PRINCIPAL_ARN을 자격 증명 양식에서 복사한 전체 값으로 바꿉니다.assertion.arn == 'BRAZE_PRINCIPAL_ARN'
- Save를 선택합니다.
이 조건은 공급자를 하나의 Braze 워크스페이스 전용으로 만듭니다. 다른 워크스페이스를 연결하려면 해당 워크스페이스용 공급자를 별도로 생성하거나, assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN']처럼 두 주체를 모두 나열하세요.
Braze 주체를 서비스 계정에 바인딩하기
워크스페이스의 주체에 서비스 계정을 가장할 수 있는 권한을 부여합니다.
- IAM & Admin > Workload Identity Federation으로 이동한 다음 풀을 선택합니다.
- Grant access를 선택한 다음 Grant access using service account impersonation을 선택합니다.
- Service account에서 Braze용으로 생성한 서비스 계정을 선택합니다.
- Select principals에서 Only identities matching the filter를 선택합니다.
- Attribute name에서 subject를 선택합니다. Attribute value에는 자격 증명 양식의 전체 Braze 주체 ARN을 붙여넣습니다.
- Save를 선택합니다. Google에서 클라이언트 라이브러리 구성 파일을 다운로드하라는 메시지가 표시되면 Dismiss를 선택합니다. Braze에는 이 파일이 필요하지 않습니다.
이렇게 하면 서비스 계정에 대한 Workload Identity User 역할(roles/iam.workloadIdentityUser)이 다음 형식의 주체에 부여됩니다.
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 필드 | 확인 위치 |
|---|---|
| Project number | 콘솔 Dashboard의 Project info 카드. 프로젝트 ID가 아닌 숫자로 된 프로젝트 번호를 사용하세요. |
| Workload identity pool ID | 생성한 풀의 Pool ID |
| Provider ID | 생성한 공급자의 Provider ID |
| Service account email | Service Accounts 페이지에 있는 서비스 계정의 Email |
Braze는 프로젝트 번호, 풀 ID, 공급자 ID를 결합하여 오디언스를 만듭니다. 오디언스는 Braze의 요청을 어떤 공급자가 검증하는지 Google에 알려줍니다. 기본적으로 공급자는 자체 리소스 이름을 오디언스로 허용합니다. 공급자에 커스텀 허용 오디언스를 설정한 경우 공급자의 전체 리소스 이름을 포함하세요.
Braze의 연결 테스트 방식
Braze에서 연결을 테스트하면 Braze는 구성이 회원님의 워크스페이스만 신뢰하는지도 확인합니다. 테스트 중에 Braze는 다음 형식처럼 모두 0으로 된 테스트 세션 이름으로 동일한 교환을 시도합니다.
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은 복사한 그대로 붙여넣으세요.
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를 사용할 수도 있습니다.
gcloud iam service-accounts keys create braze-cdi-key.json \
--iam-account=SERVICE_ACCOUNT_EMAIL
SERVICE_ACCOUNT_EMAIL을 서비스 계정의 이메일 주소로 바꾸세요. 자세한 내용은 서비스 계정 키 만들기 및 삭제를 참조하세요.
Braze에서 클라우드 데이터 수집 설정하기
- Braze에서 데이터 설정 > 클라우드 데이터 수집 > 소스로 이동하여 데이터 소스 추가를 선택한 다음 Google Cloud Storage를 선택합니다.
- 소스 필드를 입력합니다.
- 버킷: 버킷 이름
- 프로젝트 ID: GCP 프로젝트 ID
- 자격 증명: 자격 증명의 이름을 지정하고 6단계에서 설정한 인증 방법을 선택합니다. 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.
- 연결 테스트를 선택한 다음 소스에 연결을 선택합니다.
- 동기화를 생성합니다. 데이터 설정 > 클라우드 데이터 수집 > 동기화로 이동하여 데이터 동기화 생성을 선택합니다. 동기화 이름과 데이터 유형(예: 사용자 속성, 커스텀 이벤트, 구매 이벤트, 카탈로그, 사용자 삭제)을 선택한 다음 다음을 선택합니다.
- 데이터 정의 단계에서 GCS 소스를 선택한 후 다음을 지정합니다.
- Pub/Sub 구독 ID: 2단계의 구독 ID(주제가 아님)
- 폴더 경로(선택 사항): 버킷 내 경로 접두사(공유 버킷에서 폴더 동기화하기 참조)
- 미리 보기 및 유효성 검사를 선택하여 Braze가 구독에 연결하고 수집 가능한 파일을 나열할 수 있는지 확인합니다. 테스트가 성공하면 버킷의 기존 파일이 나열되지만, 해당 파일이 자동으로 동기화되지는 않습니다.
- 오류 알림을 받을 연락처 이메일 주소를 추가합니다. Google Cloud Storage 동기화는 이벤트 기반이므로 스케줄이 필요하지 않습니다. Braze는 새 파일이 업로드되는 대로 수집합니다. 요약을 검토한 다음 동기화 생성을 선택합니다.
공유 버킷에서 폴더 동기화하기
하나의 버킷을 여러 동기화에서 재사용할 수 있지만, 각 동기화는 서로 다른 폴더를 대상으로 해야 하며 전용 Pub/Sub 구독을 각각 가져야 합니다.
동일한 소스 버킷을 공유하는 여러 동기화의 경우, 폴더 경로와 구독 모두 워크스페이스 내 동기화 간에 고유해야 합니다. 2단계와 마찬가지로 이러한 구독에는 데드레터 대기줄을 구성하지 마세요.
공유 버킷에서 동기화하려는 각 폴더에 대해 다음을 수행합니다.
- 동기화의 폴더 필드를 경로 접두사(예:
attributes/)로 설정합니다. Braze는 경로가 해당 접두사로 시작하는 객체만 나열하고 수집합니다. -
해당 폴더용 전용 주제와 접두사 범위의 알림을 생성한 다음, 해당 주제에 구독을 생성합니다.
# One topic per folder gcloud pubsub topics create YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID # Assign the Cloud Storage service agent publisher on the topic gcloud pubsub topics add-iam-policy-binding YOUR-ATTRIBUTES-TOPIC \ --project=YOUR-PROJECT-ID \ --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \ --role="roles/pubsub.publisher" # Notification scoped to the folder with --object-prefix gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \ --topic=YOUR-ATTRIBUTES-TOPIC --event-types=OBJECT_FINALIZE \ --payload-format=json --object-prefix=attributes/ # One subscription per sync gcloud pubsub subscriptions create YOUR-ATTRIBUTES-SUBSCRIPTION \ --topic=YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60
-
5단계와 같이 해당 구독에 대한 consume 권한을 Braze 서비스 계정에 할당합니다.
gcloud pubsub subscriptions add-iam-policy-binding YOUR-ATTRIBUTES-SUBSCRIPTION \ --project=YOUR-PROJECT-ID \ --member="serviceAccount:[email protected]" \ --role="roles/pubsub.subscriber"
5단계에서 커스텀 역할을 생성했다면 대신
--role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"를 사용하세요. - Braze에서 동기화를 생성할 때 이 폴더의 새 Pub/Sub 구독 ID와 폴더 경로를 입력하여 동기화가 해당 폴더의 파일만 수집하도록 합니다.
필수 파일 형식
Cloud Data Ingestion은 JSON, CSV, Parquet 파일을 지원합니다. 필수 열은 데이터 유형에 따라 다릅니다. Braze는 파일 스토리지 공급업체가 적용하는 요구 사항 외에 추가적인 파일 이름 요구 사항을 적용하지 않습니다. 파일 이름은 고유해야 하며, 타임스탬프를 덧붙이면 고유성을 보장하는 데 도움이 됩니다.
데이터 웨어하우스 소스와 달리 파일 스토리지 동기화에서는 UPDATED_AT 열이 필수가 아니며 지원되지도 않습니다.
지원되는 모든 파일 유형의 예시는 braze-examples의 샘플 파일을 참조하세요.
동기화하려는 데이터 유형의 탭을 선택하세요.
각 행에는 정확히 하나의 사용자 식별자와 PAYLOAD 열이 필요합니다. 소스 파일에는 서로 다른 식별자 유형을 사용하는 행이 포함될 수 있지만, 각 행은 하나의 식별자만 사용해야 합니다.
| 식별자 | 설명 |
|---|---|
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 |
사용자의 이메일 주소입니다. 동일한 이메일 주소를 가진 프로필이 여러 개 있는 경우 가장 최근에 업데이트된 프로필이 우선적으로 업데이트됩니다. 이메일과 전화번호를 모두 포함하면 Braze는 이메일을 기본 식별자로 사용합니다. |
PHONE |
사용자의 전화번호입니다. 동일한 전화번호를 가진 프로필이 여러 개 있는 경우 가장 최근에 업데이트된 프로필이 우선적으로 업데이트됩니다. |
PAYLOAD 열에는 Braze의 사용자에게 동기화하려는 필드의 JSON 문자열이 사용자 속성 객체 형식에 따라 포함됩니다.
JSON 예시
{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}
CSV 예시
external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"
소스 파일의 모든 줄에는 유효한 JSON이 포함되어야 합니다. 그렇지 않으면 해당 파일을 건너뜁니다.
커스텀 이벤트는 사용자 속성과 동일한 사용자 식별자 열을 사용합니다. PAYLOAD 열은 이벤트 객체 형식을 따릅니다.
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
소스 파일의 모든 줄에는 유효한 JSON이 포함되어야 합니다. 그렇지 않으면 해당 파일을 건너뜁니다.
구매 이벤트는 사용자 속성과 동일한 사용자 식별자 열을 사용합니다. PAYLOAD 열은 구매 객체 형식을 따릅니다.
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
소스 파일의 모든 줄에는 유효한 JSON이 포함되어야 합니다. 그렇지 않으면 해당 파일을 건너뜁니다.
카탈로그 파일은 사용자 데이터 파일과 다른 식별자를 사용합니다. 카탈로그 동기화를 생성하기 전에 Braze에서 대상 카탈로그를 먼저 생성하세요. 전체 카탈로그 워크플로는 카탈로그 데이터 동기화 및 삭제를 참조하세요.
| 열 | 필수 | 설명 |
|---|---|---|
ID |
예 | 카탈로그 아이템의 고유 식별자입니다. Braze에서 아이템을 생성, 업데이트 또는 삭제하는 데 사용됩니다. |
PAYLOAD |
예 | 동기화할 카탈로그 필드와 값의 JSON 문자열입니다. Braze의 카탈로그 스키마와 일치해야 합니다. |
DELETED |
아니요 | true인 경우 ID가 일치하는 카탈로그 아이템이 Braze의 카탈로그에서 제거됩니다. 생성 또는 업데이트 작업에서는 이 열을 생략하거나 false로 설정하세요. |
JSON 예시
{"id":"85","payload":"{\"product_name\":\"Product 85\",\"price\":85.85}"}
{"id":"86","payload":"{\"product_name\":\"Product 86\",\"price\":86.86}"}
{"id":"1","payload":"{\"product_name\":\"Product 1\",\"price\":1.01}","deleted":true}
DELETED 열이 있는 CSV 예시
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
86,"{""product_name"": ""Product 86"", ""price"": 86.86}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true
DELETED 열이 없는 CSV 예시
ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"
Canvas 트리거는 제로 카피 개인화를 지원합니다. 대상 Canvas 설정 및 고려 사항은 제로 카피 개인화를 참조하세요.
| 필드 | 필수 | 설명 |
|---|---|---|
EXTERNAL_ID |
예, external_id 또는 alias_name 및 alias_label 중 하나 |
업데이트하려는 사용자를 식별합니다. Braze에서 사용하는 external_id 값과 일치해야 합니다. |
ALIAS_NAME 및 ALIAS_LABEL |
예, external_id 또는 alias_name 및 alias_label 중 하나 |
이 두 열은 사용자 별칭 객체를 생성합니다. alias_name은 고유 식별자여야 하며, alias_label은 별칭 유형을 지정합니다. 사용자는 레이블이 다른 여러 별칭을 가질 수 있지만, alias_label당 alias_name은 하나만 가질 수 있습니다. |
PROPERTIES |
예 | Canvas에서 개인화 속성으로 사용할 수 있도록 할 필드의 JSON 문자열입니다. 사용자별 정보를 포함해야 합니다. |
시작하려면 새 동기화를 생성할 때 Canvas 트리거 데이터 유형을 선택하세요.
소스 버킷의 파일을 사용하여 Braze에서 고객 프로필을 삭제하려면 다음을 수행합니다.
- 다른 동기화와 동일한 설정을 사용하여 새 Cloud Data Ingestion 동기화를 생성합니다.
- Braze에서 동기화를 구성할 때 데이터 유형을 사용자 삭제로 설정합니다.
- 사용자 식별자 열만 포함된 파일을 소스 버킷에 업로드합니다.
PAYLOAD열은 포함하지 마세요. 실수로 인한 삭제를 방지하기 위해 페이로드가 있으면 동기화가 실패합니다.
파일의 각 행은 다음 중 하나를 사용하여 정확히 한 명의 사용자를 식별해야 합니다.
| 식별자 | 설명 |
|---|---|
EXTERNAL_ID |
Braze에서 사용하는 external_id와 일치합니다. |
ALIAS_NAME 및 ALIAS_LABEL |
두 열을 함께 사용하여 별칭으로 사용자를 식별합니다. |
BRAZE_ID |
Braze에서 생성한 사용자 ID입니다(기존 사용자만 해당). |
JSON 예시
{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}
CSV 예시
external_id
user-to-delete-001
user-to-delete-002
동기화가 실행되면 Braze는 버킷의 새 파일을 처리하고 해당하는 고객 프로필을 삭제합니다.
카탈로그 아이템 삭제하기
파일 스토리지를 사용하여 카탈로그에서 항목을 제거하려면 다음 단계를 따르세요.
- 카탈로그 데이터를 동기화할 때 사용하는 것과 동일한 동기화를 사용합니다(데이터 유형 카탈로그).
- CSV 또는 JSON 파일에 선택 사항인
deleted(또는DELETED) 열을 추가합니다. - Braze의 카탈로그에서 제거하려는 카탈로그 항목의
deleted를true로 설정합니다.
각 행에는 여전히 ID와 PAYLOAD가 필요합니다. 삭제 대상으로 표시된 행의 경우 페이로드는 최소한으로만 포함해도 됩니다. Braze는 ID를 기준으로 항목을 제거합니다.
동기화가 실행되면 deleted: true가 지정된 행과 일치하는 카탈로그 항목이 Braze에서 삭제됩니다. 전체 카탈로그 동기화 및 삭제 동작에 대한 자세한 내용은 카탈로그 데이터 동기화 및 삭제를 참조하세요.
알아두어야 할 사항
- 소스 버킷 또는 컨테이너에 추가하는 파일은 512 MB를 초과하면 안 됩니다. 이 제한은 Amazon S3, Google Cloud Storage, Azure Blob Storage에 적용됩니다. 512 MB보다 큰 파일은 오류가 발생하며 Braze에 동기화되지 않습니다. Azure Blob Storage 자체는 훨씬 더 큰 파일을 허용하지만, CDI는 모든 파일 스토리지 소스에 동일한 512 MB 제한을 적용합니다.
- 파일당 행 수에는 별도의 제한이 없지만, 동기화 속도를 높이려면 더 작은 파일을 사용하는 것이 좋습니다. 예를 들어 500 MB 파일 하나를 수집하는 데는 100 MB 파일 다섯 개를 따로 수집하는 것보다 시간이 훨씬 오래 걸립니다.
- 특정 시간 동안 업로드할 수 있는 파일 수에는 별도의 제한이 없습니다.
- 파일 내부 또는 파일 간 순서는 지원되지 않습니다. 예상되는 경합 조건을 모니터링하고 있다면 업데이트를 주기적으로 일괄 처리하는 것이 좋습니다.
- CDI는 동기화를 생성한 후에 추가된 파일만 처리합니다. 기존 파일을 사용해 Braze가 버킷에 액세스하고 수집할 파일을 감지할 수 있는지 확인할 수는 있지만, 이러한 파일은 Braze에 동기화되지 않습니다. CDI가 기존 파일을 처리하도록 하려면 동기화하려는 기존 파일을 소스 버킷에 다시 업로드하세요.
문제 해결
파일 업로드 및 처리
CDI는 동기화가 생성된 후에 업로드된 파일만 처리합니다. 새 객체가 생성될 때마다 Pub/Sub 주제로 OBJECT_FINALIZE 메시지가 트리거됩니다. 버킷에 이미 있는 파일을 수집하려면 해당 파일을 다시 업로드하세요.
예기치 않은 파일 오류 처리
파일이 수집되지 않는 경우 다음 사항을 확인하세요.
- 버킷 알림이 존재하는지 확인합니다.
gcloud storage buckets notifications list gs://YOUR-BUCKET-NAME으로 버킷의 알림을 나열할 수 있습니다. - Cloud Storage 서비스 에이전트에 주제에 대한
roles/pubsub.publisher가 있는지 확인합니다. - Braze 서비스 계정에 구독에 대한 consume 권한(
pubsub.subscriptions.consume, 커스텀 역할 또는roles/pubsub.subscriber를 통해 할당됨)이 있는지 확인합니다. - 구독에 데드레터 대기줄이 구성되어 있지 않은지 확인합니다. Braze는 클라우드 데이터 수집 구독에 대해 데드레터 대기줄을 지원하지 않습니다.
자세한 내용은 Google Cloud 설명서의 Cloud Storage용 Pub/Sub 알림을 참조하세요.
구성이 워크스페이스 이외의 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에 액세스 권한을 부여할 때 발생합니다.
이 오류를 해결하려면 다음 단계를 따르세요.
- Google Cloud 콘솔에서 서비스 계정을 열고 Permissions 탭을 선택합니다.
principalSet://으로 시작하고 풀을 참조하는 Workload Identity User 역할이 있는 모든 주 구성원을 찾습니다. 각 주 구성원에서 해당 역할을 제거합니다.- Braze 주 구성원을 서비스 계정에 바인딩에 설명된 대로 전체 주 구성원에 해당 역할이 있는지 확인합니다.
- IAM & Admin > IAM으로 이동하여 풀에 대한 프로젝트 수준의 Workload Identity User 권한 부여가 있는지 확인합니다. 있다면 제거합니다.
- 연결을 다시 테스트합니다.
또는 제공업체를 주 구성원으로 제한(선택 사항)에 설명된 대로 제공업체의 속성 조건을 전체 주 구성원으로 제한할 수도 있습니다. 그러면 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이 포함되어 있는지
- 커스텀 허용 오디언스를 설정한 경우, 제공업체의 전체 리소스 이름이 포함되어 있는지
- 풀과 제공업체가 활성화되어 있는지
잘못된 통합 객체 오류
이 오류는 둘 이상의 워크스페이스에 동일한 클라우드 스토리지 버킷이나 폴더를 가리키는 통합이 있을 때 발생합니다. 각 클라우드 스토리지 위치는 한 번에 하나의 통합에서만 사용할 수 있습니다. 해결 단계는 FAQ를 참조하세요.
관련 페이지
- 필수 열과 페이로드 형식은 테이블 설정을 참조하세요.
- 동기화 일정 설정과 데이터 포인트 효율성은 모범 사례를 참조하세요.
- 동기화 실행 모니터링은 동기화 로그 및 관측 가능성을 참조하세요.
- 모든 소스에 공통된 질문은 FAQ를 참조하세요.