인증 및 설정
Google Sheets 통합은 Google Sheets API가 활성화된 Google Cloud Platform을 통한 OAuth 2.0 인증을 사용합니다. 에이전트는 스프레드시트 데이터를 프로그래밍 방식으로 읽고, 쓰고, 조작할 수 있어 강력한 데이터 자동화 워크플로우를 가능하게 합니다. 개인 Google 계정과 공유 스프레드시트가 있는 Google Workspace 엔터프라이즈 계정을 모두 지원합니다.필요한 API 범위
- spreadsheets: 스프레드시트를 생성, 읽기, 업데이트 및 삭제하는 완전한 접근 권한.
- spreadsheets.readonly: 데이터 검색 및 분석을 위한 읽기 전용 접근 권한.
- drive: Google Drive에서 스프레드시트를 나열하고 관리하는 접근 권한.
- drive.file: 앱에서 생성하거나 열은 파일에만 접근.
사용 가능한 작업
모든 필요한 권한이 구성되면 툴킷은 다음 작업을 활성화합니다.읽기 작업
- 범위 읽기: 지정된 범위(예: “Sheet1!A1:D10”)에서 셀 값을 검색합니다. A1 표기법과 명명된 범위를 지원합니다.
- 여러 범위 읽기: 단일 요청에서 여러 비연속 범위에서 배치 읽기.
- 셀 값 가져오기: 단일 특정 셀에서 값을 검색합니다.
- 행 가져오기: 행 번호로 전체 행을 읽습니다.
- 열 가져오기: 열 문자로 전체 열을 읽습니다.
- 셀 찾기: 특정 값을 검색하고 해당 위치를 반환합니다.
쓰기 작업
- 범위 쓰기: 2D 배열 데이터로 지정된 범위의 값을 업데이트합니다. 원시 입력 또는 사용자 입력 형식을 지원합니다.
- 행 추가: 기존 데이터를 덮어쓰지 않고 시트 끝에 새 행을 추가합니다.
- 행 삽입: 특정 위치에 새 행을 삽입하고 기존 행을 아래로 이동합니다.
- 셀 업데이트: 공식 또는 고정 데이터로 단일 셀 값을 수정합니다.
- 범위 지우기: 서식을 유지하면서 지정된 범위의 내용을 삭제합니다.
- 행/열 삭제: 시트에서 전체 행 또는 열을 제거합니다.
스프레드시트 관리
- 스프레드시트 생성: 사용자 정의 제목과 초기 시트 구조로 새 Google Sheet를 생성합니다.
- 스프레드시트 복사: 모든 데이터와 서식과 함께 기존 스프레드시트를 복제합니다.
- 스프레드시트 메타데이터 가져오기: 시트 이름, 치수, 보호된 범위 및 속성을 검색합니다.
- 스프레드시트 속성 업데이트: 제목, 로케일, 시간대 및 기본 형식을 수정합니다.
시트 작업
- 시트 추가: 기존 스프레드시트에 새 시트(탭)를 생성합니다.
- 시트 삭제: 스프레드시트에서 시트를 제거합니다.
- 시트 이름 변경: 시트 이름/제목을 변경합니다.
- 시트 복사: 동일하거나 다른 스프레드시트 내에서 시트를 복제합니다.
- 시트 숨기기/표시: 시트 가시성을 제어합니다.
- 시트 순서 변경: 스프레드시트 내에서 탭 순서를 변경합니다.
서식 작업
- 일괄 업데이트: 단일 API 호출로 여러 서식 변경을 적용합니다(색상, 글꼴, 테두리, 정렬).
- 셀 서식 설정: 숫자 형식, 통화, 날짜, 백분율 또는 사용자 정의 형식을 적용합니다.
- 셀 병합: 여러 셀을 단일 셀로 결합합니다.
- 셀 병합 해제: 이전에 병합된 셀을 분할합니다.
- 열 너비 설정: 픽셀 단위로 열 너비를 조정하거나 자동 크기 조정합니다.
- 행 높이 설정: 더 나은 레이아웃을 위해 행 높이를 수정합니다.
- 행/열 고정: 더 쉬운 탐색을 위해 헤더 행 또는 열을 고정합니다.
고급 작업
- 범위 정렬: 오름차순 또는 내림차순으로 열별로 데이터를 정렬합니다.
- 데이터 필터: 데이터 하위 집합을 표시하기 위해 필터 기준을 적용합니다.
- 피벗 테이블 생성: 데이터 분석을 위한 피벗 테이블을 생성합니다.
- 차트 추가: 데이터 범위를 기반으로 차트(막대, 선, 원형, 산점도)를 삽입합니다.
- 명명된 범위 생성: 더 쉬운 참조를 위한 명명된 범위를 정의합니다.
- 데이터 검증: 드롭다운 목록, 숫자 범위 또는 사용자 정의 검증 규칙을 설정합니다.
- 조건부 서식: 규칙 기반 셀 서식을 적용합니다.
구성 옵션
- 값 입력 옵션: RAW(정확한 입력을 유지) 또는 USER_ENTERED(입력한 것처럼 구문 분석) 중 선택합니다.
- 값 렌더 옵션: 값이 반환되는 방식을 제어합니다(FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA).
- 기본 스프레드시트 ID: 반복적인 ID 지정을避免하기 위해 작업에 대한 기본 스프레드시트를 설정합니다.
- 날짜 시간 렌더 옵션: 날짜/시간에 대해 시리얼 번호 또는 서식이 지정된 문자열을 선택합니다.
- 차원: 작업이 ROWS 또는 COLUMNS에 적용되는지 지정합니다.
사용 사례
- 자동화된 보고: 데이터베이스를 쿼리하고, Python으로 결과를 처리하며, 차트가 포함된 서식이 지정된 보고서를 Sheets에 기록합니다.
- 데이터 입력 자동화: 이메일, 문서 또는 양식에서 데이터를 추출하고 스프레드시트 행을 채웁니다.
- 실시간 대시보드: 이해관계자 대시보드를 구동하는 메트릭 시트를 지속적으로 업데이트합니다.
- 재고 관리: ERP 시스템과 협업 Sheets 트래커 간에 제품 데이터를 동기화합니다.
- 예산 추적: 여러 소스의 경비 데이터를 통합 예산 시트에 집계합니다.
- 설문 응답 처리: 양식 응답을 수집하고, Python으로 분석하며, 요약 시트에 인사이트를 기록합니다.
- 프로젝트 상태 보고: Jira/Asana에서 작업 데이터를 가져오고, 서식을 지정하며, 이해관계자가 접근할 수 있는 Sheets에 게시합니다.
- 영업 파이프라인 시각화: CRM 데이터를 계산된 필드와 조건부 서식과 함께 Sheets로 내보냅니다.
모범 사례
- 스프레드시트 ID 사용: 안정성을 위해 이름 대신 스프레드시트 ID(URL에서)로 항상 참조합니다.
- 일괄 작업: 성능을 향상시키기 위해 여러 업데이트를 단일 batchUpdate 호출로 결합합니다.
- 메타데이터 캐싱: 메타데이터 API 호출을 최소화하기 위해 시트 구조 정보를 저장합니다.
- 명명된 범위: 코드를 더 유지 관리하기 쉽게 만들기 위해 중요한 데이터 영역에 명명된 범위를 사용합니다.
- 추가 vs 삽입: 새 데이터를 추가할 때는 append를 사용합니다. 마지막 행을 찾는 것보다 더 빠르고 안전합니다.
- 대용량 데이터셋 읽기: 10,000행 이상 시트의 경우 시간 초과 및 메모리 문제를 방지하기 위해 청크 단위로 읽습니다.
- 공식 처리: 공식을 쓸 때는 RAW 값 입력 옵션을 사용하고 ”=“로 시작합니다.
성능 팁
- 작업을 일괄 처리하고 한 번에 더 큰 범위를 읽어 API 호출을 최소화합니다.
- 적절한 값 렌더 옵션을 사용합니다 - 서식이 필요하지 않을 때는 UNFORMATTED_VALUE가 더 빠릅니다.
- 리소스를 많이 소모하는 과도한 서식 작업을 피합니다.
- 대용량 데이터셋의 경우 API를 반복적으로 읽는 대신 Sheets에서 IMPORTRANGE를 사용하는 것을 고려합니다.
일반적인 문제 및 해결 방법
- 권한 거부: 스프레드시트가 에이전트의 서비스 계정과 공유되었는지 또는 사용자가 접근을 부여했는지 확인합니다.
- 잘못된 범위: A1 표기법 구문을 확인합니다(예: “Sheet1!A1:B10”). 여러 시트 파일에는 시트 이름을 포함합니다.
- 속도 제한 초과: 지수 백오프를 구현합니다. 호출 수를 줄이기 위해 일괄 작업 사용을 고려합니다.
- 데이터 유형 불일치: 데이터 유형이 예상 형식과 일치하는지 확인합니다(문자열이 아닌 숫자).