먼저 확인할 차이
Endpoint 바꾸기
Braze path 앞에 노티플라이 프로젝트 prefix를 붙입니다.catalog_name, item_id, field_name은 노티플라이에서 catalogName, itemId, fieldName으로 표현되지만 실제 URL 값과 역할은 같습니다.
카탈로그
아이템
PUT은 전달한 아이템의 전체 값을 교체하며, 아이템이 없으면 만듭니다. PATCH는 기존 아이템의 전달한 필드만 바꾸며 없는 ID는 404를 반환합니다. 배열 필드에는 Braze와 같은 $add, $remove 연산을 사용할 수 있습니다.
필드와 셀렉션
노티플라이 셀렉션 생성 요청에서는 Braze의
external_id와 source를 제거합니다. 필터 값에는 null을 사용할 수 없으며, 필드 타입별 허용 연산자는 Catalog REST API 시작하기를 따릅니다.
인증 코드 바꾸기
Braze REST API key를 요청마다 직접 보내는 대신, 노티플라이/authenticate에서 인증 토큰을 발급받아 재사용합니다. 토큰 유효 시간은 1시간입니다.
운영 코드에서는 인증 토큰을 요청마다 새로 발급하지 말고 만료 전까지 메모리에 캐시하세요. Access Key, Secret Key, 토큰과 인증 응답 본문은 로그에 남기지 마세요. 자세한 내용은 API 시작하기를 참고하세요.
생성 요청 변환하기
Braze의catalogs[0] 객체에 data_classification을 추가합니다. 필드 순서는 유지하고, 첫 번째 필드가 id:string인지 확인합니다.
- 필드가 500개를 넘으면 사용하지 않는 필드를 제거하거나 카탈로그를 분리합니다.
- 카탈로그·필드·아이템 ID는 최대 250자이며 영문 대소문자, 숫자, 하이픈, 밑줄만 사용합니다.
array값은 문자열 배열이며 최대 100개입니다.geo값은[longitude, latitude]순서입니다.time값은 ISO 8601 문자열 또는 Unix seconds입니다. 저장될 때 UTC ISO 8601 문자열로 정규화됩니다.object의 key에는 점(.)과 달러 기호($)를 사용할 수 없습니다.- 문자열 값은 최대 5,000자, 아이템 한 개는 최대 1 MiB입니다.
응답 처리 바꾸기
성공 응답
Braze 단건 생성은 다음처럼 성공 메시지를 반환합니다.data에 반환합니다.
response.message === "success" 또는 status === 202만 확인한다면, 노티플라이에서는 response.error === null과 엔드포인트별 200·201을 확인하도록 바꿔야 합니다.
오류 응답
Braze의errors[]를 파싱하던 코드는 노티플라이의 error.code, error.message, 선택적인 error.details를 읽도록 바꿉니다.
error.code를 기준으로 처리하세요. details가 있으면 field 또는 path로 잘못된 입력을 표시할 수 있습니다.
페이지네이션
두 API 모두 한 번에 최대 50개 아이템을 반환합니다. 노티플라이는 다음 cursor를 응답 본문과Link 헤더에 함께 제공합니다.
Link header만 따라가던 코드는 그대로 header를 사용할 수 있습니다. 새 구현에서는 data.next_cursor가 null이 될 때까지 요청해도 됩니다. cursor 값은 API 내부 형식이므로 해석하거나 직접 만들지 마세요.
데이터 옮기기
1. Braze 자산 조사
먼저 다음을 기록합니다.- 카탈로그 이름, 설명, 필드 순서와 타입
- 아이템 수와 전체 데이터 크기
- 메시지에서 사용하는
catalog_items,catalog_selection_itemsLiquid - 셀렉션 이름, 필터, 정렬, 결과 개수
- 카탈로그를 쓰는 batch job, webhook, 운영 도구와 API key 권한
- 필드가
id포함 500개 이하인지, JSON 중첩이 50단계 이하인지 - object key에
.또는$가 없는지와 개인 식별 정보가 포함되지 않았는지
2. Braze 아이템 내보내기
GET /catalogs/{catalog_name}/items를 호출하고 Link header의 rel="next"가 없어질 때까지 50개씩 수집합니다. 내보낸 JSON과 아이템 수를 변경하지 않은 원본 증빙으로 보관합니다.
이관 파일은 암호화된 저장소에 두고 작업 담당자에게만 최소 권한을 부여하세요. 보관 기한을 정해 검증과 되돌리기 기간이 끝나면 삭제합니다. 개인 식별 정보를 발견하면 이관을 중단하고 파일을 격리한 뒤 해당 필드를 제거하거나 유저 속성으로 분리하세요. 파일 내용이나 인증 정보를 티켓, 채팅, 애플리케이션 로그에 붙이지 마세요.
3. 노티플라이 카탈로그 만들기
Braze 필드 정의에data_classification: "non_personal"을 추가해 POST /v1/projects/{projectId}/catalogs로 생성합니다. 같은 이름으로 다시 만들면 충돌하므로 재실행 전에 기존 생성 여부를 조회하세요.
4. 아이템 가져오기
이관이 끝날 때까지 Braze를 기준 원본으로 유지합니다. 내보낸 아이템을 최대 50개씩 나누고, 요청 본문이 4 MiB에 가까우면 묶음 크기를 더 줄입니다. 반복 실행이 필요한 전체 복사는 일괄PUT /catalogs/{catalogName}/items가 안전합니다. 같은 ID는 전체 교체하고 없는 ID는 만듭니다. 새 아이템만 허용하고 중복을 오류로 잡아야 할 때만 POST를 사용하세요.
각 묶음마다 카탈로그 이름, 메서드, 정렬한 아이템 ID, 아이템 수, 요청 본문 hash, 시작·완료 시각, 결과 상태를 체크포인트에 기록합니다. 한 요청의 변경은 트랜잭션으로 처리되므로 200 응답을 받은 뒤에만 완료로 표시합니다.
응답을 받지 못했거나 500을 받았다면 바로 같은 POST를 반복하지 마세요. 단건 GET /items/{itemId}로 해당 묶음의 반영 여부를 확인하고 빠진 아이템만 다시 보냅니다. PUT은 전체 요청 본문을 반복 적용할 수 있습니다. 재시도 간격은 지수 방식으로 늘리고 무작위 지연을 더해 다음처럼 처리합니다.
401: 인증 토큰을 새로 발급한 뒤 재시도- 네트워크 timeout·
500: 반영 여부를 조회한 뒤 제한적으로 재시도 400·403·404·409·413: 입력, 권한, 대상, 중복, 묶음 크기를 고치기 전에는 자동 재시도하지 않음
5. 셀렉션 복원하기
아이템 적재가 끝난 뒤 조사 단계에서 기록한 셀렉션을POST /catalogs/{catalogName}/selections로 하나씩 만듭니다. Braze 요청의 external_id와 source는 제거하고, 필드 타입별 operator와 null 제한을 적용합니다.
성공한 셀렉션 이름과 요청 hash를 200 응답 뒤 체크포인트에 기록하세요. 노티플라이 공개 API에는 셀렉션 목록·수정 엔드포인트가 없습니다. timeout으로 결과를 모르면 해당 셀렉션을 사용하는 Liquid를 테스트해 먼저 존재 여부와 결과를 확인합니다. 정의가 잘못된 경우에만 영향 범위를 확인한 뒤 DELETE하고 다시 만드세요.
이후 아이템이나 필드를 변경하면 저장된 셀렉션 결과는 같은 요청 안에서 다시 계산됩니다.
6. 검증하기
- 노티플라이
GET /catalogs의num_items가 Braze에서 내보낸 아이템 수와 같은지 확인합니다. - 모든 페이지를 다시 조회해 ID 집합, 요청 본문 hash, 주요 필드 값을 비교합니다.
- 메시지 미리보기에서 실제 운영에 쓰는 Liquid를 실행합니다.
- 없는 ID, 빈 배열,
null, 한글·이모지,time,geo, object, array 값을 포함한 경계 사례를 확인합니다. - 셀렉션별 아이템 수와 정렬 결과를 비교합니다. 정렬을 생략한 셀렉션은 무작위 결과이므로 동일 순서를 기대하지 않습니다.
- 미해결 묶음과 셀렉션 체크포인트가 없는지 확인합니다.
7. 호출 경로 전환하기
- 조회와 메시지 렌더링은 Braze를 계속 사용한 채, 쓰기는 Braze에 먼저 적용하고 노티플라이에 같은 변경을 보냅니다. 노티플라이 실패는 재처리 대기열에 기록합니다.
- 사전에 정한 관찰 기간 동안 아이템 수·hash·주요 값·셀렉션 결과와 API 오류를 비교합니다.
- 불일치와 미해결 재처리가 없을 때 조회 경로와 메시지 Liquid를 노티플라이로 전환합니다.
- 전환 후 불일치, 지속적인 API 오류, Liquid 렌더링 오류가 생기면 조회 경로를 Braze로 되돌리고 노티플라이 전용 쓰기를 중지한 뒤 체크포인트에서 다시 동기화합니다.
- 되돌리기 기간이 지나고 양쪽이 계속 일치하면 Braze 쓰기를 중단합니다.
- Braze Catalog 삭제는 별도 승인과 백업 확인 후 진행합니다.
