Google Sheets 데이터 소스 구성
Google Sheets 데이터 소스는 오프라인 동기화를 통해 Google 스프레드시트의 데이터를 읽어 플랫폼 내장 데이터 웨어하우스에 쓰는 데 사용됩니다. 이 문서에서는 Google 측 권한 부여 준비, 데이터 소스 구성, 동기화 계획 생성, 작업 플로우 연결 방법을 소개합니다.
사용 제한 및 사전 준비
구성을 시작하기 전에 다음 제한 사항과 사전 조건을 확인하십시오.
- Google Sheets는 데이터 소스로만 사용할 수 있으며, 데이터 목적지로는 사용할 수 없고 Google 스프레드시트에 데이터를 다시 쓰지도 않습니다.
- 시스템은 Google Sheets 상단에 표시되는 열 문자(A, B, C 등)에
col_접두사를 자동으로 붙여 소스 필드 이름을 생성합니다. 예를 들어 A열은col_A, B열은col_B가 됩니다. 모든 소스 필드의 타입은 문자열이므로, 필드 매핑 시 타겟 테이블의 요구 사항에 맞게 필드를 변환하거나 조정하십시오. - Google Cloud 프로젝트, 서비스 계정, JSON 키를 생성할 수 있는 Google 계정이 필요하며, 대상 Google 스프레드시트를 서비스 계정과 공유할 수 있는 권한이 있어야 합니다.
- 플랫폼 실행 환경에서 Google Sheets API와 Google Drive API에 접근할 수 있어야 합니다.
| 환경 설정 방식 | 적용 시나리오 | 설정 요구 사항 |
|---|---|---|
| 환경 구분 없음 | 개발 환경과 운영 환경이 같은 서비스 계정을 공유 | JSON 키 하나만 업로드 |
| 독립 환경 설정 | 개발 환경과 운영 환경이 서로 다른 서비스 계정을 사용 | 키를 각각 업로드. 두 계정 모두 이름이 같은 Google 스프레드시트와 시트에 접근할 수 있어야 함 |
독립 환경 설정에서는 설정과 미리보기에 개발 환경 자격 증명을, 운영 작업에 운영 환경 자격 증명을 사용합니다. 두 환경의 스프레드시트 이름, 시트 이름, 공유 권한을 미리 확인하십시오.
Google Cloud와 Google Sheets에서 권한 부여 완료
Google Sheets 데이터 소스는 서비스 계정으로 서버 측 인증을 수행하므로 OAuth 동의 화면, 클라이언트 ID, 콜백 주소, 도메인 전체 위임을 구성할 필요가 없습니다.
- Google Cloud 프로젝트 생성 또는 선택. Google Cloud Console에 접속하여 기존 프로젝트를 선택하거나 새 프로젝트를 생성합니다.
- 필요한 API 사용 설정. API 및 서비스 > 라이브러리에서 Google Sheets API와 Google Drive API를 각각 검색하여 사용 설정합니다. 전자는 셀 데이터를 읽는 데, 후자는 스프레드시트를 찾고 파일 메타데이터를 읽는 데 사용합니다.
- 서비스 계정 생성. IAM 및 관리자 > 서비스 계정으로 이동하여 Google Sheets 읽기 전용 서비스 계정을 생성합니다. 현재 연동에서는 서비스 계정에 프로젝트 Owner, Editor, Drive Admin 등 광범위한 역할을 부여할 필요가 없습니다.
- JSON 키 생성. 해당 서비스 계정의 키 탭을 열고 키 추가 > 새 키 만들기 > JSON을 선택한 후 키 파일을 다운로드하여 안전하게 보관합니다.
- 대상 스프레드시트 공유. 읽어야 할 Google 스프레드시트를 열고 오른쪽 상단의 공유를 클릭한 후, JSON 파일의
client_email을 입력하고 권한으로 뷰어를 선택하여 공유를 완료합니다.
서비스 계정에 대상 Google 스프레드시트의 보기 권한을 부여합니다.
읽어야 할 각 스프레드시트는 서비스 계정과 직접 공유하거나 상위 폴더를 통해 접근 권한을 상속받아야 합니다. API를 사용 설정하는 것만으로는 스프레드시트 접근 권한이 자동으로 부여되지 않습니다.
Service Account JSON에는 민감한 자격 증명이 포함되어 있으므로 키를 코드 저장소, 로그, 그룹 채팅, 티켓에 올리지 마십시오. 키가 유출된 경우 Google Cloud에서 즉시 사용 중지하거나 삭제한 후 다시 생성하십시오.
키를 생성할 수 없다면 Google Cloud 관리자에게 조직 정책 iam.disableServiceAccountKeyCreation을 확인하도록 요청하십시오. iam.gserviceaccount.com 주소와 스프레드시트를 공유할 수 없다면 Google Workspace 관리자에게 Drive 외부 공유 정책을 확인하도록 요청하십시오.
Google Sheets 데이터 소스 생성
- 데이터 개발 플랫폼 > 통합 > 데이터 소스로 이동하여 새 데이터 소스를 클릭합니다.
- GoogleSheets를 선택하고 데이터 소스 이름과 비고를 입력합니다.
- 환경 구분 없음 또는 독립 환경 설정을 선택합니다. 독립 환경 설정에서는 개발 환경과 운영 환경을 각각 설정해야 합니다.
- Service Account JSON에 Google Cloud에서 다운로드한 원본
.json파일을 업로드합니다. - 연결 테스트를 클릭합니다. 연결 가능이 표시되면 완료를 클릭합니다.
Service Account JSON을 업로드하고 연결 테스트 결과가 연결 가능인지 확인합니다.
| 구성 항목 | 설명 |
|---|---|
| Service Account JSON | Google Cloud에서 다운로드한 원본 JSON 키 파일을 업로드합니다. 플랫폼이 자동으로 검증합니다. |
| 환경 구분 없음 | 개발 환경과 운영 환경이 현재 키를 공유 |
| 독립 환경 설정 | 개발 환경과 운영 환경의 키를 각각 관리. 두 환경 모두 각각 연결 테스트를 통과해야 함 |
저장된 데이터 소스를 편집할 때는 페이지에 마스킹된 서비스 계정 이메일만 표시되며 개인 키는 다시 표시되지 않습니다. 키를 교체하려면 새 JSON 파일을 다시 업로드하고 연결을 다시 테스트하십시오.
오프라인 동기화 계획 생성
- 데이터 개발 플랫폼 > 통합 > 오프라인 동기화로 이동하여 통합 방안 생성을 클릭합니다.
- 데이터 소스에서 GoogleSheets와 생성한 데이터 소스를 선택합니다.
- 읽을 Google 스프레드시트와 그 안의 시트를 차례로 선택합니다. 목록에는 현재 서비스 계정이 접근 권한을 가진 항목만 표시됩니다.
- 열 범위를 입력합니다. 범위에는 열 문자만 포함합니다. 예:
A:F,F:F,AA:ZZZ. 시스템이 자동으로 대문자로 변환합니다. - 파일 읽기 규칙을 펼치고 스프레드시트 내용에 따라 헤더 건너뛰기를 설정합니다. 켜면 2행부터, 끄면 1행부터 읽습니다.
- 소스 데이터 미리보기를 클릭하여 선택한 범위, 행 수, 데이터 내용이 예상과 일치하는지 확인합니다.
스프레드시트, 시트, 열 범위를 선택한 후 소스 데이터 미리보기로 읽기 결과를 확인합니다.
열 범위에는 행 번호나 시트 이름을 포함하지 않습니다. A1:F, A:F50000, 工作表1!A:F, 그리고 시작 열이 끝 열보다 큰 F:A는 모두 유효하지 않은 형식입니다.
독립 환경 설정에서는 운영 실행 시 운영 환경 서비스 계정으로 이름이 같은 Google 스프레드시트와 시트를 찾습니다. 이름이 중복되거나 없거나 권한이 부여되지 않은 경우 운영 작업이 실패할 수 있습니다.
필드 매핑 및 동기화 검증
데이터 소스 설정을 완료한 후 플랫폼 내장 데이터 웨어하우스의 타겟 테이블을 선택하고 필드 매핑을 설정합니다. Google Sheets 필드는 열 문자에 따라 생성되며, 예를 들어 A열은 col_A, B열은 col_B에 대응하고 타입은 모두 문자열입니다.
- 데이터 목적지에서 타겟 테이블을 선택하거나 생성하고, 비즈니스 요구에 따라 쓰기 방식을 설정합니다.
- 필드 매핑에서 소스 필드를 타겟 필드에 매핑합니다. 타겟 필드 타입이 다르면 먼저 필요한 타입 변환을 수행합니다.
- 계획 이름, 담당자, 비고를 입력한 후 저장합니다.
- 수동 실행을 클릭하고 실행 기록에서 작업이 성공했는지 확인한 후, 타겟 테이블에서 행 수, 필드 순서, 데이터 내용을 확인합니다.
| 증상 | 확인 항목 |
|---|---|
| 연결 테스트 실패 | 업로드한 파일이 완전한 서비스 계정 JSON인지, 키가 사용 중지되거나 삭제되지 않았는지, Google Sheets API와 Google Drive API가 사용 설정되어 있는지 확인 |
| 대상 Google 스프레드시트를 찾을 수 없음 | 스프레드시트가 JSON의 client_email과 공유되어 있고 권한이 최소 뷰어인지 확인 |
| 시트를 찾을 수 없음 | 시트가 삭제되지 않았는지 확인. 독립 환경에서는 운영 계정이 이름이 같은 스프레드시트와 시트에 접근할 수 있는지 확인 |
| 열 범위 오류 | 열 문자만 입력하고 시작 열이 끝 열보다 크지 않은지 확인. 범위가 시트의 읽기 가능 범위를 벗어나지 않았는지 확인 |
| 429 또는 요청 속도 제한 안내 | 잠시 후 다시 시도하고 Google API 할당량과 작업 동시 실행 수 확인 |
작업 플로우에 연결
수동 검증에 성공하면 오프라인 동기화 계획을 작업 플로우에 연결하여 스케줄링 주기에 따라 자동으로 실행할 수 있습니다.
- 저장된 오프라인 동기화 계획을 열고 작업 플로우에 연결을 클릭합니다.
- 대상 작업 플로우를 선택합니다.
- 노드 이름을 입력하고 실행 모드를 선택한 후, 필요에 따라 담당자와 비고를 설정합니다. 노드 타입과 통합 계획은 자동으로 채워집니다.
- 노드 생성 및 연결을 클릭합니다. 연결에 성공하면 작업 플로우로 이동을 클릭하여 노드 위치와 상하위 의존성을 확인할 수 있습니다.
- 작업 플로우를 저장하고 배포를 완료합니다. 운영 스케줄링에는 운영 환경의 데이터 소스 설정이 사용됩니다.
동기화 계획이나 데이터 소스를 변경하려면 먼저 기존 작업 플로우의 의존성을 검토하고, 수정 후 검증을 한 번 더 실행하십시오.