# Braze Connected Content와 Sheet2API로 구글 시트 데이터 연결하기 (2026 업데이트)

> 출처: https://retn.kr/blog/braze-connected-contents/ · 수정 2026-10-16 · 리텐션 주식회사

Braze Connected Content와 Sheet2API로 구글 시트 데이터를 캠페인에 연결하는 방법입니다. 2026년 10월 Braze 문서 기준으로 캐시 문법, 인증, 응답 제한을 고쳤습니다.

[Braze Connected Content](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call?ref=retn.kr)는 메시지를 렌더링하는 순간 외부 API를 호출하고, 그 응답을 메시지에 넣는 기능입니다. Sheet2API는 Google Sheets를 JSON API로 바꿔 주는 서비스입니다. 두 도구를 함께 쓰면 개발 리소스가 적은 CRM 팀도 시트에서 관리하는 데이터를 캠페인에 연결할 수 있습니다. 처음 구현할 때는 Tomas Gurovich의 미디엄 글을 참고했습니다. 운영하면서 Braze의 응답 용량 제한과 리다이렉트 제약을 만났고, 지금 구조로 바꿨습니다.

이 글은 Braze Connected Content를 안정적으로 운영하기 위한 구조, 제한, 설정 순서를 정리한 실무 가이드입니다. 2026년 10월 16일에 Braze 공식 문서와 Sheet2API 요금 페이지를 다시 확인했습니다. 캐시 문법(`:cache_max_value` → `:cache_max_age`), 인증 방법, Braze 제품 이름(CDI)을 바로잡았습니다.

## 데이터 통합의 필요성과 Sheet2API의 역할

[Sheet2API](https://sheet2api.com/?ref=retn.kr)는 Google Sheets나 Excel Online 시트를 JSON API로 바꿉니다. 시트의 첫 행은 컬럼 이름이어야 합니다. 시트의 탭마다 엔드포인트가 하나씩 생깁니다. 2026년 10월 16일 기준 Sheet2API에는 무료 플랜이 없습니다. 모든 플랜은 카드를 등록하고 7일 무료 체험으로 시작합니다. 가장 낮은 Starter 플랜은 연 결제 기준 월 £29.99이고, 월 10,000회 요청을 줍니다. 할당량을 넘으면 API가 429 오류를 돌려줍니다. 저희도 요청량이 늘면서 비용 부담을 느꼈습니다([브레이즈 중·고수로 가는 방법](/blog/braze-road-to-master/)). ([Sheet2API 요금](https://sheet2api.com/pricing/?ref=retn.kr), [Sheet2API 문서](https://sheet2api.com/documentation/?ref=retn.kr))

요청 수는 수신자 수보다 많을 수 있습니다. Braze는 수신자 한 명에게 같은 Connected Content 호출을 여러 번 보낼 수 있습니다. 예를 들어 이메일은 HTML, 일반 텍스트, AMP 버전을 따로 렌더링합니다. URL에 `{{${user_id}}}` 같은 사용자별 값을 넣으면 Braze가 캐시를 건너뛸 수 있습니다. 발송 규모가 크면 Sheet2API 월 할당량을 먼저 계산하세요. ([Make a Connected Content API call — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call?ref=retn.kr), [Cache Connected Content responses — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/caching_responses?ref=retn.kr))

## Connected Content의 응답 제한: 1MB, 2초, 리다이렉트

Braze Connected Content 응답은 1MB까지 받습니다. Braze는 1MB를 넘는 응답을 캐시하지 않습니다. 서버가 2초 안에 응답하지 않으면 Braze는 내용을 넣지 않습니다. 엔드포인트가 404를 돌려주면 그 자리에는 빈 문자열이 들어갑니다. 그래서 시트 전체를 한 번에 받지 말고 필요한 행과 열만 받으세요. Sheet2API는 API 안에 검색·필터 기능이 있습니다. ([Make a Connected Content API call — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call?ref=retn.kr), [Cache Connected Content responses — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/caching_responses?ref=retn.kr))

## 리다이렉트 문제

Connected Content는 리다이렉트를 따라가지 않습니다. Braze는 2xx 응답만 성공으로 봅니다. 엔드포인트가 301이나 302를 돌려주면 메시지에서 그 부분이 비어 보입니다. Postman은 리다이렉트를 자동으로 따라갑니다. 그래서 Postman에서 되는 URL이 Braze에서는 실패할 수 있습니다. Connected Content에는 항상 최종 URL을 넣으세요. ([Make a Connected Content API call — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call?ref=retn.kr))

Google Apps Script 웹 앱을 중간 API로 쓸 때도 같은 문제가 생깁니다. Apps Script 콘텐츠 서비스는 응답을 script.googleusercontent.com의 일회성 URL로 리디렉션합니다. Braze는 이 리디렉션을 따라가지 않습니다. 그래서 Apps Script 웹 앱 URL은 Connected Content 엔드포인트로 바로 쓸 수 없습니다. 반면 Sheet2API 예시 엔드포인트는 리다이렉트 없이 바로 200 JSON 응답을 돌려줍니다(2026-10-16 curl 확인). ([콘텐츠 서비스 — Google Apps Script](https://developers.google.com/apps-script/guides/content?hl=ko&ref=retn.kr))

## 카탈로그 기능의 한계

Braze Cloud Data Ingestion(CDI)은 데이터 웨어하우스 테이블을 Braze 카탈로그로 동기화합니다. BigQuery, Snowflake, Redshift, Databricks, Microsoft Fabric을 지원합니다. 데이터가 이미 웨어하우스에 있다면 CDI + 카탈로그를 먼저 검토하세요. 웨어하우스가 없다면 시트 + Connected Content로 빠르게 실험하고, 계속 쓰는 데이터만 카탈로그로 옮기는 순서를 권합니다. CDI 설정은 [BigQuery ↔ Braze 연동 가이드](/blog/bigquery-to-braze/)에, 카탈로그와 Connected Content를 함께 쓰는 예시는 [브레이즈 커머스 추천 시스템 글](/blog/recommendation-system/)에 정리했습니다. ([Braze Cloud Data Ingestion — Braze Docs](https://www.braze.com/docs/user_guide/data/unification/cloud_ingestion?ref=retn.kr))

## 구현 과정: Step by Step

아래 절차는 개발 의존을 줄이고, 빠르게 테스트하고, 안정적으로 운영하기 위한 최소 순서입니다.

### 1단계: Sheet2API 설정

첫 단계는 시트 구조를 고정하는 것입니다. 컬럼 이름이 바뀌면 Braze 템플릿의 필드 이름도 함께 바뀌어야 합니다. 테스트용 시트와 운영용 시트를 나누세요.

1. **Google Sheets 문서 준비**: 사용할 데이터가 포함된 Google Sheets 문서를 준비합니다.
1. **Sheet2API에 가입**: [Sheet2API 웹사이트](https://sheet2api.com/?ref=retn.kr)에 접속하여 가입합니다. 모든 플랜은 7일 무료 체험으로 시작하고, 카드 등록이 필요합니다.
1. **API 엔드포인트 생성**: Sheet2API 대시보드에서 필요한 API 엔드포인트를 생성합니다.
1. **읽기 권한만 켜기**: Sheet2API는 기본값으로 읽기·생성·수정·삭제를 모두 허용합니다. 계정 페이지의 Configure API > API Permissions에서 읽기(Read)만 남깁니다.
1. **인증 켜기**: 인증을 켜면 Sheet2API는 HTTP Basic 인증을 요구합니다. 사용자 이름과 비밀번호는 다음 단계에서 Braze에 저장합니다.

### 2단계: Braze Connected Content 태그 작성

두 번째 단계는 Braze 메시지에 Connected Content 태그를 쓰는 것입니다. 인증 정보는 템플릿에 직접 쓰지 마세요. Braze의 Settings > Credential Management에 Basic 인증 자격 증명으로 저장하고, 태그에서 `:basic_auth`로 부르세요. Braze는 GET 요청 응답을 기본 5분 동안 캐시합니다. `:cache_max_age`로 캐시 시간을 최소 5분에서 최대 4시간까지 정할 수 있습니다. 캐시는 보장되지 않습니다. 엔드포인트가 반복 호출을 견딜 수 있어야 합니다. ([Make a Connected Content API call — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call?ref=retn.kr), [Cache Connected Content responses — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/caching_responses?ref=retn.kr))

```
<code class="language-liquid">{% connected_content https://sheet2api.com/v1/your_api_endpoint
  :basic_auth sheet2api_credential
  :cache_max_age 14400
  :save data
%}
</code>
```

- `your_api_endpoint`: Sheet2API에서 만든 엔드포인트 경로로 바꿉니다.
- `sheet2api_credential`: Credential Management에 저장한 Basic 인증 자격 증명 이름으로 바꿉니다. Sheet2API 인증을 켜지 않았다면 이 줄을 지웁니다.
- `:cache_max_age 14400`: 응답을 최대 4시간(14,400초) 캐시합니다. 허용 범위는 300초~14,400초입니다.
- 2023년 판의 `:headers { "Authorization": "Basic ..." }` 방식도 동작합니다. 다만 자격 증명이 템플릿에 그대로 남습니다.

```
<code>{{data[0].field_name}}</code>
```

- `field_name`: JSON 응답에서 원하는 필드의 이름으로 대체합니다.

응답이 비었을 때 메시지를 보내지 않으려면 `abort_message`를 씁니다. Braze는 중단한 메시지를 발송 수에 넣지 않습니다. ([Abort Connected Content — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/aborting_connected_content?ref=retn.kr))

```
<code class="language-liquid">{% if data[0] == nil %}
{% abort_message('Sheet2API returned no row') %}
{% endif %}
</code>
```

### 3단계: 캠페인 테스트 및 실행

마지막 단계는 테스트 세그먼트에 먼저 보내는 것입니다. Preview & Test에서 미리보기를 만들고 View details를 누르면 Connected Content Debugger가 열립니다. 여기서 실제 요청과 응답을 확인합니다. Postman이나 curl로 같은 요청을 보내서 응답을 비교하는 방법도 Braze 문서가 권합니다. ([Make a Connected Content API call — Braze Docs](https://www.braze.com/docs/user_guide/messaging/design_and_edit/personalize/connected_content/making_an_api_call?ref=retn.kr))

## 운영 체크리스트: 성과와 안정성을 동시에 관리하는 방법

Connected Content는 데이터 정확성, 호출 안정성, 성과 추적 세 가지를 주 단위로 점검합니다.

- API 응답 성공률 99% 이상 유지 여부를 주 단위로 확인합니다.
- 핵심 필드 누락률(예: 가격, 재고, 추천 문구)을 1% 미만으로 관리합니다.
- 캠페인별 CTR, CVR, 매출 uplift를 통제군과 함께 기록합니다.
- 캐시 만료 정책 변경 시 응답 시간과 오류율 변화를 동시에 모니터링합니다.
- Sheet2API 월 요청 할당량 대비 사용량을 주 단위로 확인합니다. 할당량을 넘으면 Sheet2API가 429를 돌려주고 메시지의 해당 부분이 비게 됩니다.

## 자주 묻는 질문 (FAQ)

**Q1. Connected Content와 카탈로그 중 무엇을 먼저 써야 하나요?
**빠른 검증이 목적이면 Connected Content + 외부 API를 먼저 씁니다. 데이터가 웨어하우스에 있고 계속 쓸 데이터라면 CDI + 카탈로그로 옮깁니다.

**Q2. 1MB 제한을 넘지 않으려면 무엇을 줄여야 하나요?
**필요한 행과 열만 돌려주도록 응답을 줄이세요. 사용자별로 필요한 행만 검색해서 받는 방법이 가장 확실합니다. Braze는 1MB를 넘는 응답을 받지 않고, 캐시하지도 않습니다.

**Q3. 리다이렉트 없는 URL은 어떻게 검증하나요?
**터미널에서 `-L` 옵션 없이 `curl -i <URL>`을 실행합니다. 첫 줄이 200이면 Braze에서도 동작합니다. 301이나 302가 나오면 Location 헤더의 최종 URL을 Connected Content에 넣으세요. Postman은 리다이렉트를 자동으로 따라가므로 이 확인에 맞지 않습니다.

**Q4. KPI는 어떤 순서로 봐야 하나요?
**1순위는 API 성공률, 2순위는 메시지 렌더링 성공률, 3순위는 CTR·CVR 증분입니다. 기술 지표가 흔들리면 성과 지표를 해석할 수 없습니다.

이 포스팅이 데이터 통합에 관심 있는 여러분에게 도움이 되길 바랍니다. Sheet2API를 통한 Braze와 Google Sheets의 통합은 비용 효율적이며, 복잡한 데이터 요구 사항을 충족시키는 강력한 방법입니다. [Sheet2API를 통해 시작하기](https://sheet2api.com/?ref=retn.kr)

2026-10-16 업데이트: 2025년 11월에는 Sheet2API 대신 LLM과 Apps Script로 자동화하겠다고 적었습니다. 다시 확인해 보니 Apps Script 웹 앱은 Connected Content 엔드포인트로 바로 쓸 수 없습니다. 응답이 리디렉션되기 때문입니다. Apps Script를 쓴다면 데이터 방향을 바꾸세요. Apps Script의 UrlFetchApp으로 시트 데이터를 Braze 카탈로그 API에 보내고, 메시지에서는 카탈로그를 읽으면 됩니다. 시트 데이터를 발송 순간에 바로 읽어야 한다면 Sheet2API처럼 최종 URL에서 바로 응답하는 서비스가 여전히 필요합니다. ([UrlFetchApp — Google Apps Script](https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app?hl=ko&ref=retn.kr), [Catalogs endpoints — Braze Docs](https://www.braze.com/docs/api/endpoints/catalogs?ref=retn.kr))

## 📚 더 읽어보기

- [Braze to BigQuery, BigQuery to Braze: CDI와 Currents로 양방향 연동하기](/blog/bigquery-to-braze/)
- [멘탈 모델 3가지로 5분 만에 브레이즈 커머스 추천 시스템 완성하기](/blog/recommendation-system/)
- [브레이즈(Braze) 초급 벗어나 중·고수로 가는 방법](/blog/braze-road-to-master/)
- [개발자 없이 브레이즈 API 트리거 캠페인 쓰기](/blog/api-campaign/)
- [Braze Custom HTML In-App Message, 이제 개발자 없이 직접 만들어보세요](/blog/braze-custom-html-in-app-message/)