파일 스토리지 통합

이 페이지에서는 클라우드 데이터 수집을 설정하여 S3에서 Braze로 관련 데이터를 동기화하는 방법에 대해 설명합니다.

작동 방식

클라우드 데이터 수집(CDI)을 S3에 사용하여 AWS 계정의 하나 이상의 S3 버킷을 Braze와 직접 통합할 수 있습니다. 새 파일이 S3에 게시되면 SQS에 메시지가 게시되고, Braze 클라우드 데이터 수집이 해당 새 파일을 가져옵니다.

클라우드 데이터 수집은 다음을 지원합니다:

• JSON 파일
• CSV 파일
• Parquet 파일
• 속성, 커스텀 이벤트, 구매 이벤트, 사용자 삭제 및 카탈로그 데이터

사전 요구 사항

이 통합에는 다음 리소스가 필요합니다:

• 데이터 저장을 위한 S3 버킷
• 새 파일 알림을 위한 SQS 대기줄
• Braze 액세스를 위한 IAM 역할

AWS 정의

먼저 이 작업에서 사용되는 용어를 정의합니다.

AWS에서 클라우드 데이터 수집 설정하기

1단계: 소스 버킷 생성

AWS 계정에서 기본 설정으로 범용 S3 버킷을 생성합니다. S3 버킷은 폴더가 고유한 한 여러 동기화에서 재사용할 수 있습니다.

기본 설정은 다음과 같습니다:

• ACL 비활성화
• 모든 퍼블릭 액세스 차단
• 버킷 버전 관리 비활성화
• SSE-S3 암호화
  • SSE-S3는 유일하게 지원되는 서버 측 암호화 유형입니다. Amazon KMS 암호화는 지원되지 않습니다.

버킷을 생성한 리전을 기록해 두세요. 다음 단계에서 동일한 리전에 SQS 대기줄을 생성합니다.

2단계: SQS 대기줄 생성

생성한 버킷에 객체가 추가되는 시점을 추적하기 위해 SQS 대기줄을 생성합니다. 지금은 기본 구성 설정을 사용합니다.

SQS 대기줄은 전역적으로 고유해야 합니다(예: CDI 동기화에 하나만 사용할 수 있으며 다른 워크스페이스에서 재사용할 수 없습니다).

중요

버킷을 생성한 리전과 동일한 리전에 이 SQS를 생성해야 합니다.

SQS 대기줄의 ARN과 URL을 기록해 두세요. 이 구성 과정에서 자주 필요합니다.

3단계: 액세스 정책 설정

액세스 정책을 설정하려면 Advanced options를 선택합니다.

대기줄의 액세스 정책에 다음 구문을 추가합니다. YOUR-BUCKET-NAME-HERE를 버킷 이름으로, YOUR-SQS-ARN을 SQS 대기줄 ARN으로, YOUR-AWS-ACCOUNT-ID를 AWS 계정 ID로 바꿔야 합니다:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "Sid": "braze-cdi-s3-sqs-publish",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "YOUR-SQS-ARN",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "YOUR-AWS-ACCOUNT-ID"
    },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
    }
  }
}

4단계: S3 버킷에 이벤트 알림 추가

1. 1단계에서 생성한 버킷에서 Properties > Event notifications로 이동합니다.
2. 구성에 이름을 지정합니다. 선택적으로 Braze에서 파일의 하위 집합만 수집하려면 접두사 또는 접미사를 지정할 수 있습니다.
3. Destination에서 SQS queue를 선택하고 2단계에서 생성한 SQS의 ARN을 입력합니다.

참고

S3 버킷의 루트 폴더에 파일을 업로드한 후 일부 파일을 버킷 내 특정 폴더로 이동하면 예기치 않은 오류가 발생할 수 있습니다. 대신 접두사에 있는 파일에 대해서만 이벤트 알림을 보내도록 변경하고, 해당 접두사 외부의 S3 버킷에 파일을 배치하지 않거나, 접두사 없이 통합을 업데이트하여 모든 파일을 수집할 수 있습니다.

5단계: IAM 정책 생성

Braze가 소스 버킷과 상호 작용할 수 있도록 IAM 정책을 생성합니다. 시작하려면 계정 관리자로 AWS 관리 콘솔에 로그인합니다.

1. AWS 콘솔의 IAM 섹션으로 이동하여 탐색 바에서 Policies를 선택한 다음 Create Policy를 선택합니다.
   
   
   
   

2. JSON 탭을 열고 Policy Document 섹션에 다음 코드 스니펫을 입력합니다. YOUR-BUCKET-NAME-HERE를 버킷 이름으로, YOUR-SQS-ARN-HERE를 SQS 대기줄 이름으로 바꿔야 합니다:

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
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:GetQueueUrl",
                "sqs:ReceiveMessage",
                "sqs:GetQueueAttributes"
            ],
            "Resource": "YOUR-SQS-ARN-HERE"
        }
    ]
}

3. 완료되면 Review Policy를 선택합니다.

4. 정책에 이름과 설명을 입력한 다음 Create Policy를 선택합니다.

6단계: IAM 역할 생성

AWS에서 설정을 완료하려면 IAM 역할을 생성하고 5단계에서 만든 IAM 정책을 연결합니다.

1. IAM 정책을 생성한 콘솔의 동일한 IAM 섹션에서 Roles > Create Role로 이동합니다.

2. AWS에서 신뢰할 수 있는 엔터티 선택기 유형으로 Another AWS Account를 선택합니다. Braze 계정 ID를 입력합니다. Require external ID 체크박스를 선택합니다.
3. Braze에서 데이터 설정 > 클라우드 데이터 수집 > 소스로 이동하여 데이터 소스 추가를 선택한 다음 파일 소스 섹션에서 Amazon S3를 선택합니다.
4. 자동으로 생성된 Braze 계정 ID를 복사합니다.

6. AWS에서 계정 ID를 붙여넣고 Next를 선택합니다.

7. 4단계에서 생성한 정책을 역할에 연결합니다. 검색 바에서 정책을 검색하고 정책 옆의 체크 표시를 선택하여 연결합니다. 완료되면 Next를 선택합니다.

역할에 이름과 설명을 입력하고 Create Role을 선택합니다.

8. 생성한 역할의 ARN과 생성된 외부 ID를 기록해 두세요. 클라우드 데이터 수집 통합을 생성할 때 필요합니다.

Braze에서 클라우드 데이터 수집 설정하기

1. 먼저 Braze 대시보드에서 새 소스를 생성합니다. 데이터 설정 > 클라우드 데이터 수집 > 소스로 이동하여 데이터 소스 추가를 선택한 다음 Amazon S3를 선택합니다.
2. 소스 이름을 지정하고 AWS 설정 과정에서 얻은 정보를 입력하여 새 소스를 생성합니다. 다음 항목을 지정합니다:

• 역할 ARN
• 외부 ID
• 버킷 이름
• 리전

3. 연결 테스트를 선택하여 Braze가 버킷에 접근할 수 있는지 확인합니다. 테스트가 성공하면 소스에 연결을 선택합니다. 연결에 실패하면 문제 해결에 도움이 되는 오류 메시지가 표시됩니다.

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

5. 동기화 이름을 지정합니다. 그런 다음 활성 S3 소스를 선택하고 동기화할 소스 테이블을 입력합니다. 데이터 유형을 선택하고 연결 테스트를 선택합니다.

1. AWS 설정 과정에서 얻은 나머지 정보를 입력합니다. 다음 항목을 지정합니다:
   • SQS URL(새 통합마다 고유해야 합니다)
   • 폴더 경로(선택 사항, 워크스페이스 내 동기화 간에 고유해야 합니다)
2. 데이터 유형을 선택하고 연결 테스트를 선택하여 Braze가 수집 가능한 파일 목록을 조회할 수 있는지 확인합니다(파일 내부의 데이터가 아닌 파일 목록). 성공하면 다음: 알림을 선택합니다.
3. 접근 또는 권한 문제로 동기화가 중단될 경우 알림을 받을 연락처 이메일을 추가합니다. 선택적으로 사용자 수준 오류 및 동기화 성공에 대한 알림을 활성화할 수 있습니다.
4. 동기화를 생성합니다.

필수 파일 형식

클라우드 데이터 수집은 JSON, CSV, Parquet 파일을 지원합니다. 필수 열은 데이터 유형에 따라 다릅니다:

• 사용자 데이터(속성, 커스텀 이벤트, 구매 이벤트)는 사용자 식별자와 페이로드를 사용합니다
• 카탈로그 데이터는 카탈로그 식별자를 사용합니다

카탈로그 데이터에 S3를 사용하는 경우, 카탈로그별 요구 사항과 동작에 대해서는 이 페이지와 함께 카탈로그 데이터 동기화 및 삭제를 참조하세요.

Braze는 AWS에서 적용하는 것 이상의 추가 파일 이름 요구 사항을 적용하지 않습니다. 파일 이름은 고유해야 합니다. 타임스탬프를 추가하면 고유성을 보장하는 데 도움이 됩니다.

지원되는 모든 파일 유형(속성, 커스텀 이벤트, 구매, 카탈로그, 사용자 삭제)의 예시는 braze-examples의 샘플 파일을 참조하세요.

사용자 식별자

사용자 데이터 동기화(속성, 커스텀 이벤트, 구매 이벤트)의 경우, 소스 파일의 각 행에는 정확히 하나의 사용자 식별자와 PAYLOAD 열이 필요합니다. 소스 파일에는 서로 다른 식별자 유형을 가진 행이 포함될 수 있지만, 각 개별 행은 하나만 사용해야 합니다.

식별자 외에도 각 행에는 Braze에서 사용자에게 동기화하려는 필드의 JSON 문자열을 포함하는 PAYLOAD 열이 있어야 합니다.

참고

데이터 웨어하우스 소스와 달리, UPDATED_AT 열은 파일 스토리지 동기화에서 필수도 아니고 지원되지도 않습니다.

카탈로그 식별자

카탈로그 동기화의 경우, 소스 파일에 다음 열이 포함되어야 합니다. 카탈로그 파일은 사용자 데이터 파일과 다른 식별자를 사용합니다.

예시

• json 속성
• json 커스텀 이벤트
• json 구매 이벤트
• csv 속성
• csv 카탈로그

1
2
3
4
5
6
7
{"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\"}"}
{"external_id":"s3-qa-3","payload":"{\"name\": \"5P44M\", \"age\": 15, \"subscriber\": true, \"retention\": {\"previous_purchases\": 7, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600838\"}"}
{"external_id":"s3-qa-4","payload":"{\"name\": \"WMYS7\", \"age\": 11, \"subscriber\": true, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600844\"}"}
{"external_id":"s3-qa-5","payload":"{\"name\": \"KCBLK\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 11, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600850\"}"}
{"external_id":"s3-qa-6","payload":"{\"name\": \"T93MJ\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 10, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600856\"}"}

중요

소스 파일의 모든 줄에는 유효한 JSON이 포함되어야 하며, 그렇지 않으면 파일이 건너뛰어집니다.

1
2
{"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이 포함되어야 하며, 그렇지 않으면 파일이 건너뛰어집니다.

1
2
{"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이 포함되어야 하며, 그렇지 않으면 파일이 건너뛰어집니다.

1
2
3
4
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""}"
s3-qa-load-2-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""EP1U0"", ""age"": 99, ""subscriber"": false, ""retention"": {""previous_purchases"": 23, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598822""}"

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

선택적 DELETED 열을 포함합니다. DELETED가 true이면 해당 카탈로그 항목이 Braze의 카탈로그에서 제거됩니다. 필수 열의 전체 목록은 카탈로그 식별자를 참조하세요. 삭제 동작에 대해서는 카탈로그 항목 삭제를 참조하세요. 포괄적인 카탈로그 설정 흐름(대상 카탈로그 생성 및 동기화 동작 포함)에 대해서는 카탈로그 데이터 동기화 및 삭제를 참조하세요.

데이터 삭제

S3용 클라우드 데이터 수집은 파일 업로드를 통해 사용자 및 카탈로그 항목 삭제를 지원합니다. 각각에 대해 별도의 동기화 및 파일 형식을 사용하세요.

• 사용자 삭제 – 데이터 유형을 Delete Users로 설정하여 동기화를 생성하고, 사용자 식별자만 포함된 파일(페이로드 없음)을 업로드합니다.
• 카탈로그 항목 삭제 – 기존 카탈로그 동기화를 사용하고 deleted(또는 DELETED) 열을 추가하여 제거할 항목을 표시합니다.

사용자 삭제

S3의 파일을 사용하여 Braze에서 고객 프로필을 삭제하려면:

1. 새 클라우드 데이터 수집 동기화를 생성합니다(다른 동기화와 동일한 AWS 및 Braze 설정).
2. Braze에서 동기화를 구성할 때 Data Type을 Delete Users로 설정합니다.
3. 사용자 식별자 열만 포함된 파일을 S3 버킷에 업로드합니다. PAYLOAD 열은 포함하지 마세요. 실수로 인한 삭제를 방지하기 위해 페이로드가 있으면 동기화가 실패합니다.

파일의 각 행은 다음 중 하나를 사용하여 정확히 한 명의 사용자를 식별해야 합니다:

중요

사용자 삭제는 영구적이며 되돌릴 수 없습니다. 제거하려는 사용자만 포함하세요. 자세한 내용은 클라우드 데이터 수집으로 사용자 삭제를 참조하세요.

예시 – JSON(사용자 삭제):

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

예시 – CSV(사용자 삭제):

1
2
3
external_id
user-to-delete-001
user-to-delete-002

동기화가 실행되면 Braze는 버킷의 새 파일을 처리하고 해당 고객 프로필을 삭제합니다.

카탈로그 항목 삭제

파일 스토리지를 사용하여 카탈로그에서 항목을 제거하려면:

1. 카탈로그 데이터 동기화에 사용하는 것과 동일한 S3 동기화를 사용합니다(데이터 유형 Catalogs).
2. CSV 또는 JSON 파일에 선택적 deleted(또는 DELETED) 열을 추가합니다.
3. Braze의 카탈로그에서 제거하려는 카탈로그 항목에 대해 deleted를 true로 설정합니다.

각 행에는 여전히 ID와 PAYLOAD가 필요합니다. 삭제로 표시된 행의 경우 페이로드는 최소한으로 설정할 수 있으며, Braze는 ID를 기준으로 항목을 제거합니다.

예시 – JSON(카탈로그 항목 삭제):

{"id":"85","payload":"{\"product_name\": \"Product 85\", \"price\": 85.85}"}
{"id":"1","payload":"{\"product_name\": \"Product 1\", \"price\": 1.01}","deleted":true}

예시 – CSV(카탈로그 항목 삭제):

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

동기화가 실행되면 deleted: true로 표시된 행에 해당하는 카탈로그 항목이 Braze에서 삭제됩니다. 전체 카탈로그 동기화 및 삭제 동작에 대한 자세한 내용은 카탈로그 데이터 동기화 및 삭제를 참조하세요.

알아두어야 할 사항

• S3 소스 버킷에 추가하는 파일은 512 MB를 초과할 수 없습니다. 512 MB보다 큰 파일은 오류가 발생하며 Braze에 동기화되지 않습니다.
• 파일당 행 수에 대한 추가 제한은 없지만, 동기화 속도를 개선하기 위해 더 작은 파일을 사용하는 것을 권장합니다. 예를 들어, 500 MB 파일 하나를 수집하는 것보다 100 MB 파일 다섯 개를 수집하는 것이 훨씬 빠릅니다.
• 특정 시간 내에 업로드할 수 있는 파일 수에 대한 추가 제한은 없습니다.
• 파일 내부 또는 파일 간 순서 지정은 지원되지 않습니다. 예상되는 경합 조건을 모니터링하는 경우 업데이트를 주기적으로 일괄 처리하는 것을 권장합니다.

문제 해결

파일 업로드 및 처리

CDI는 동기화가 생성된 후에 추가된 파일만 처리합니다. 이 과정에서 Braze는 새로 추가된 파일을 감지하고, 이를 통해 SQS에 새 메시지가 트리거됩니다. 그러면 새 파일을 처리하기 위한 새로운 동기화가 시작됩니다.

기존 파일을 사용하여 Braze가 버킷에 접근하고 수집할 파일을 감지할 수 있는지 검증할 수 있지만, 해당 파일은 Braze에 동기화되지 않습니다. CDI가 이러한 파일을 처리하려면 동기화하려는 기존 파일을 S3에 다시 업로드해야 합니다.

예기치 않은 파일 오류 처리

오류 또는 실패한 파일이 많이 발생하는 경우, CDI 대상 폴더가 아닌 다른 폴더에 파일을 추가하는 별도의 프로세스가 S3 버킷에서 실행되고 있을 수 있습니다.

파일이 소스 버킷에 업로드되었지만 소스 폴더에 업로드되지 않은 경우, CDI는 SQS 알림을 처리하지만 해당 파일에 대해 아무런 작업도 수행하지 않으므로 오류로 표시될 수 있습니다.

S3 알림 또는 SQS 대상 권한과 관련된 문제(예: 대상 유효성 검사 오류)인 경우 AWS 설명서를 참조하세요:

• Amazon S3 콘솔을 사용하여 이벤트 알림 활성화 및 구성
• 대상에 이벤트 알림 메시지 게시 권한 부여
• Amazon SQS 문제 해결