Google Sheets
B1 Export는 B1.church용 공식 Google Sheets 애드온입니다. 모든 스프레드시트에 사이드바를 추가하여 B1 교회에서 사람, 기부, 그룹 또는 출석을 명명된 탭으로 내보냅니다 — 필요할 때마다 한 번의 클릭으로 내보냅니다. 애드온은 사용자의 Google 계정 내에서 완전히 실행됩니다. 각 내보내기가 하는 읽기 전용 API 호출 외에는 ChurchApps 서버에 도달하지 않습니다.
시작하기 전에
- 내보낼 스프레드시트에 대한 편집 권한이 있는 Google 계정
- B1 API 키를 발급할 수 있는 교회 관리자(또는 내보낼 데이터에 대한 읽기 권한이 있는 사람)
- Google Workspace Marketplace에서 설치된 B1 Export 애드온
내보낼 수 있는 항목
| 메뉴 항목 | 시트 탭 | 데이터 |
|---|---|---|
| 사람 내보내기 | B1 People | ID, 표시 이름, 이름, 성, 이메일, 멤버십 상태 |
| 기부 내보내기 | B1 Donations | ID, 사람 ID, 날짜, 금액, 방법, 배치 ID |
| 그룹 내보내기 | B1 Groups | ID, 이름, 카테고리, 멤버 수 |
| 출석 내보내기 | B1 Attendance | ID, 사람 ID, 방문 날짜, 예배 ID, 그룹 ID |
각 내보내기는 명명된 탭의 콘텐츠를 바꿉니다 — 내보내기를 다시 실행하면 추가된 행이 아닌 새로운 스냅샷을 얻습니다. 스프레드시트의 다른 탭은 영향을 받지 않습니다.
설정
1. 올바른 범위로 B1 API 키 생성
- B1Admin에서 설정 → 개발자 → API 키로 이동합니다.
- 새 API 키를 클릭하고 이름을 "Sheets Export"로 지정한 후 내보낼 항목의 읽기 범위를 부여합니다:
- 사람 내보내기를 위한
people:read - 기부를 위한
donations:read - 그룹을 위한
groups:read - 출석을 위한
attendance:read
- 사람 내보내기를 위한
- 내보내기만 수행하는 키는
settings:write가 필요하지 않습니다 — 해당 범위는 웹훅을 등록하는 커넥터(Zapier / Make)에만 필요합니다. 이 키를 좁게 유지하세요. - 저장하고
cak_…키를 복사합니다.
2. 애드온 설치
- 내보낼 스프레드시트를 엽니다.
- 확장 프로그램 → 애드온 → 애드온 가져오기.
- B1 Export를 검색하고 설치합니다. Google은 시트 및 외부 HTTP에 대한 액세스를 부여하도록 요청합니다(애드온이 B1 API를 호출할 수 있도록).
설치 후 이 Google 계정으로 열려는 모든 스프레드시트의 확장 프로그램 메뉴 아래에 B1 Export 항목이 나타납니다.
3. 키 연결
- 확장 프로그램 → B1 Export → 연결…(또는 처음 열기 후 메뉴 모음에서 B1 Export → 연결...).
- API 키를 사이드바에 붙여넣고, 기본 URL을
https://api.churchapps.org로 둡니다(스테이징에 대해 테스트하는 경우 제외) 그리고 저장을 클릭합니다. - 연결 테스트를 클릭합니다 — 녹색 "연결 성공"은 키가 작동함을 확인합니다.
키는 사용자별 속성(PropertiesService.getUserProperties())에 저장됩니다 — Google 계정에만 연결되며 시트에 기록되지 않으며 스프레드시트의 다른 편집자에게 보이지 않습니다.
내보내기 실행
다음 중 하나:
- 메뉴에서 — 확장 프로그램 → B1 Export → 사람 내보내기(또는 기부 / 그룹 / 출석)
- 사이드바에서 — 사이드바 열기(연결...) 및 해당 데이터세트 버튼 클릭
토스트는 완료될 때 확인합니다 — "N 행이 'B1 People'에 기록됨."
위에 보고서 작성
내보낸 탭은 일반 Google Sheets 데이터입니다. 탭을 참조하는 자신의 분석을 작성하세요:
=SUMIF('B1 Donations'!E:E, "card", 'B1 Donations'!D:D)를 사용하여 카드 기부를 합계하는 요약 탭=FILTER('B1 People'!A:F, 'B1 People'!F:F = "Member")를 사용한 멤버만 필터링된 보기B1 Attendance에서 데이터를 가져오는 출석 추세의 차트
내보내기를 다시 실행하면 기본 탭이 새로고침되고 공식이 자동으로 업데이트됩니다.
반복적인 내보내기 예약
애드온은 기본적으로 온디맨드입니다. 주간 또는 월간 내보내기의 경우 Apps Script의 내장 시간 기반 트리거를 사용하세요:
- 스프레드시트의 확장 프로그램 → Apps Script(애드온의 바인딩 스크립트 열기).
- 왼쪽 사이드바의 ⏰ 트리거 아이콘을 클릭합니다.
exportPeople(또는 내보내기 함수)에 대해 트리거 추가 — 시간 기반 선택, 주 타이머, 예: 매주 월요일 오전 6시.
내보내기는 Google 계정 아래 백그라운드에서 실행됩니다. API 키가 회전되거나 취소되면 트리거가 다음 실패 시 이메일로 알려줍니다.
권한 및 개인정보
- 애드온은
spreadsheets.currentonly(열려 있는 스프레드시트만 터치 가능) 및script.external_request만 요청합니다(UrlFetchApp이 B1 API를 호출할 수 있도록). Drive, Gmail 또는 기타 Google 데이터를 볼 수 없습니다. - B1 API 키는 사용자별로 저장됩니다 — 같은 스프레드시트의 다른 편집자는 볼 수 없습니다.
- 모든 B1 API 호출은
Authorization: Bearer cak_…로 HTTPS를 통해 이루어집니다.
문제 해결
- "API 키 설정되지 않음" — **확장 프로그램 → B1 Export → 연결...**을 열고 키를 붙여넣으세요.
- "B1이 API 키를 거부했습니다(401)" — 키가 취소되었거나 잘못되었습니다. 다시 발급하고 다시 붙여넣으세요.
- "이 API 키는 /giving/donations에 대한 권한이 없습니다(403)" — 키에
donations:read가 없습니다. B1Admin에서 키의 범위를 업데이트하세요. - 실행 후 시트가 새로고침되지 않음 — 올바른 탭 이름(
B1 People등)을 보고 있는지 확인하세요. 내보내기는 탭이 없으면 생성합니다. - "할당량 초과됨" — Apps Script는
UrlFetchApp에 대해 사용자별 일일 할당량을 부과합니다(일반적으로 하루에 수천 개의 호출). 많은 기록이 있는 큰 교회는 여러 날에 걸쳐 내보내기를 분할하거나 Make / 대용량 동기화를 위한 사용자 정의 통합을 사용해야 할 수 있습니다.
애드온 사용자 정의
애드온은 오픈소스입니다 — Apps Script 프로젝트는 B1Integrations/GoogleSheetsAddon/ 저장소에 있습니다. 우리가 내보내지 않는 열, 추가 데이터세트 또는 다른 출력 형식이 필요한 경우 거기에서 문제 또는 PR을 열어주세요.
참고도 보기
- Zapier — 온디맨드 내보내기 대신 실시간 동기화
- Make — 더 복잡한 변환을 사용한 동기화
- API 키(개발자 참조)