파일 스토리지 통합

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

How it works

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

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

• JSON 파일
• CSV 파일
• 마루 파일
• Attribute, custom event, purchase event, user delete, and catalog data

Prerequisites

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

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

AWS 정의

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

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

1단계: 소스 버킷 만들기

Create a general-purpose S3 bucket with default settings in your AWS account. S3 버킷은 폴더가 고유한 한 여러 동기화에서 재사용할 수 있습니다.

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

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

다음 단계에서 같은 지역에 SQS 대기줄을 만들 것이므로 버킷을 만든 지역을 기록해 두세요.

2단계: SQS 대기열 만들기

생성한 버킷에 개체가 추가되는 시기를 추적할 수 있는 SQS 대기열을 만듭니다. 지금은 기본 구성 설정을 사용하세요.

SQS 대기열은 전 세계적으로 고유해야 합니다(예: CDI 동기화에는 하나만 사용할 수 있고 다른 작업 공간에서 재사용할 수 없음).

이 구성 중에 자주 사용하게 되므로 ARN과 SQS의 URL을 메모해 두세요.

3단계: 액세스 정책 설정

액세스 정책을 설정하려면 고급 옵션을 선택합니다.

다음 문장을 대기줄의 액세스 정책에 추가하되, 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단계에서 만든 버킷에서 속성 > 이벤트 알림으로 이동합니다.
2. 구성에 이름을 지정합니다. 선택 사항으로 Braze가 파일의 하위 집합만 수집하도록 하려면 접두사 또는 접미사를 지정하여 대상을 지정합니다.
3. Under Destination, select SQS queue and provide the ARN of the SQS you created in step 2.

5단계: IAM 정책 만들기

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

1. AWS 콘솔의 IAM 섹션으로 이동하여 탐색 모음에서 정책을 선택한 다음 정책 생성을 선택합니다.
   
   
   
   

2. JSON 탭을 열고 정책 문서 섹션에 다음 코드 스니펫을 입력하고 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. Select Review Policy when you’re finished.

1. Give the policy a name and description, then select Create Policy.

6단계: IAM 역할 만들기

AWS에서 설정을 완료하려면 IAM 역할을 만들고 4단계의 IAM 정책을 여기에 첨부합니다.

1. IAM 정책을 만든 콘솔의 동일한 IAM 섹션에서 역할 > 역할 만들기로 이동합니다.

2. Braze 대시보드에서 Braze AWS 계정 ID를 복사합니다. Go to Cloud Data Ingestion, select Create New Data Sync, and select S3 Import. 3. AWS에서 신뢰할 수 있는 엔터티 선택기 유형으로 다른 AWS 계정을 선택합니다. Braze 계정 ID를 입력합니다. 외부 ID 필요 확인란을 선택합니다. 4. Braze에서 데이터 설정 > 클라우드 데이터 수집으로 이동하여 새 데이터 동기화 만들기를 선택한 다음, 파일 소스 섹션에서 S3 가져오기를 선택합니다. 5. 자동으로 생성된 Braze 계정 ID를 복사합니다.

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

7. 4단계에서 만든 정책을 역할에 첨부합니다. 검색창에서 정책을 검색하고 정책 옆의 확인 표시를 선택하여 첨부합니다. 완료되면 다음을 선택합니다.

역할에 이름과 설명을 입력하고 역할 만들기를 선택합니다.

8. 클라우드 데이터 수집 통합을 만드는 데 필요하므로 생성한 역할의 ARN과 생성한 외부 ID를 기록해 두세요.

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

1. 새 통합 서비스를 만들려면 데이터 설정 > 클라우드 데이터 수집으로 이동하여 새 데이터 동기화 만들기를 선택한 다음, 파일 소스 섹션에서 S3 가져오기를 선택합니다.
2. AWS 설정 프로세스의 정보를 입력하여 새 동기화를 생성합니다. 다음을 지정합니다:

• 역할 ARN
• 외부 ID
• SQS URL(새 통합마다 고유해야 함)
• 버킷 이름
• 폴더 경로(선택 사항, 워크스페이스의 동기화 전체에서 고유해야 함)
• 지역

3. 통합의 이름을 지정하고 이 통합의 데이터 유형을 선택합니다.

4. 액세스 또는 권한 문제로 인해 동기화가 중단되는 경우 알림을 받을 연락처 이메일을 추가하세요. 선택 사항으로 사용자 수준 오류 및 동기화 성공에 대한 알림을 설정합니다.

5. 마지막으로 연결 테스트를 선택하여 Braze가 버킷에 액세스할 수 있는지 확인하고 수집할 수 있는 파일(해당 파일 내의 데이터는 제외)을 나열합니다. 그런 다음 동기화를 저장합니다.

필수 파일 형식

클라우드 데이터 수집은 JSON, CSV 및 Parquet 파일을 지원합니다. Each file must contain one or more of the supported identifier columns and a payload column as a JSON string.

Braze는 AWS에서 시행하는 것 외에 추가적인 파일 이름 요구 사항을 적용하지 않습니다. 파일 이름은 고유해야 합니다. 고유성을 위해 타임스탬프를 추가하는 것이 좋습니다.

사용자 식별자

소스 파일에는 하나 이상의 사용자 식별자 열 또는 키가 포함될 수 있습니다. 각 행에는 하나의 식별자만 포함되어야 하지만 소스 파일에는 여러 식별자 유형이 있을 수 있습니다.

• json attributes
• json custom events
• json purchase events
• csv attributes
• csv catalogs

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\"}"}

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}}"}

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\"}}"}

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

지원되는 모든 파일 형식의 예는 braze-examples의 샘플 파일을 참조하세요.

데이터 삭제

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

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

사용자 삭제하기

S3의 파일을 사용하여 Braze에서 고객 프로필을 삭제하려면 다음과 같이 하세요:

1. 새 클라우드 데이터 수집 동기화를 만듭니다(다른 동기화와 동일한 AWS 및 Braze 설정 ).
2. Braze에서 동기화를 구성할 때 데이터 유형을 사용자 삭제로 설정합니다.
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 동기화를 사용합니다.
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에서 삭제됩니다. 전체 카탈로그 동기화 및 삭제 동작에 대해서는 카탈로그 데이터 동기화 및 삭제를 참조하세요.

알아두어야 할 사항

• Files added to the S3 source bucket should not exceed 512 MB. Files larger than 512 MB will result in an error and won’t be synced to Braze.
• While there is no additional limit on the number of rows per file, we recommend using smaller files to improve how fast your syncs run. For example, a 500 MB file would take considerably longer to ingest than five separate 100 MB files.
• There’s no additional limit on the number of files uploaded in a given time.
• Ordering isn’t supported in or between files. We recommend batching updates periodically if you’re monitoring for any expected race conditions.

문제 해결

파일 업로드 및 처리

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

기존 파일을 사용하여 Braze가 버킷에 액세스하고 수집할 파일을 감지할 수 있는지 확인할 수 있지만, 이 파일은 Braze와 동기화되지 않습니다. CDI가 이를 처리하려면 동기화하려는 기존 파일을 S3에 다시 업로드해야 합니다.

예기치 않은 파일 오류 처리

If you’re observing a high number of errors or failed files, you may have another process adding files to the S3 bucket in a folder other than the target folder for CDI.

When files are uploaded to the source bucket but not in the source folder, CDI will process the SQS notification, but it does not take any action on the file, so this may appear as an error.