노드 사용법 익히기 - Google Sheets 노드

이 문서에서는 에이전트리아(Agentria) 의 Google Sheets 노드 사용법을 안내합니다. Google Sheets 노드는 구글 스프레드시트 파일을 만들고, 조회하고, 시트를 추가하고, 셀 값을 읽고 쓰고 지우는 노드입니다. 작업(Task) 항목에서 무엇을 고르느냐에 따라 노드 편집기에 나타나는 입력 항목이 달라집니다.

Google Sheets 노드는 작업 하나당 노드 하나로 동작합니다. 이 문서는 7가지 작업 각각의 기능과 사용 방법을 노드 하나만 사용하는 예제로 안내합니다.

사전 준비

에이전트리아 캔버스 진입 방법은 🔗3단계 핵심 가이드를 참고하시기 바랍니다.

Google Sheets 노드를 사용하려면 먼저 구글 크리덴셜(Credential)을 등록하고 구글 계정을 연동해야 합니다. 등록 방법은 🔗구글 크리덴셜 설정 가이드를 참고하시기 바랍니다. Client ID / Client Secret 방식으로 연동하는 경우, 데이터 액세스 범위에서 Google Sheets API를 검색해 활성화합니다.

• 연동한 구글 계정이 접근할 수 있는 스프레드시트만 다룰 수 있습니다. 다른 사람의 시트를 다루려면 그 시트가 연동한 계정에 공유되어 있어야 합니다.

노드 편집기 공통 구조

Google Sheets 노드를 캔버스에 배치하고 더블 클릭하면 노드 편집기가 열립니다. 어떤 작업을 선택하든 아래 두 가지 규칙이 공통으로 적용됩니다.

• 노드 편집기에는 처음에 크리덴셜과 작업만 보입니다. 그 외 입력 항목(스프레드시트 ID, 범위, 값 등)은 화면에 바로 나타나지 않으며, 변수 추가 버튼을 클릭해 모달에서 필요한 항목을 체크하고 저장해야 노드 편집기에 나타납니다. 필수 항목도 예외가 아니므로, 각 작업에서 필요한 항목을 빠짐없이 체크해야 합니다.

• 어떤 작업이든 출력은 result라는 Object(객체) 값 하나뿐입니다. 구글 스프레드시트 API 응답 형태를 그대로 담고 있어서, 작업에 따라 그 안에 든 내용이 다릅니다. 노드 테스트를 실행한 뒤 출력 패널의 결과 탭에서 result를 펼쳐 안에 어떤 값이 들어있는지 확인하는 것이 가장 정확합니다.

작업 목록

작업 드롭다운에서 아래 7가지 중 하나를 선택합니다.

Append to Sheet와 Update Sheet는 헷갈리기 쉽습니다. Append to Sheet는 어디에 쓸지 스스로 찾아 기존 데이터의 맨 아래 빈 줄부터 붙이고, Update Sheet는 지정한 위치에 정확히 쓰며 그 자리에 있던 값을 덮어씁니다.

스프레드시트 ID

Create Spreadsheet를 제외한 나머지 모든 작업에서 스프레드시트 ID(spreadsheet_id)를 입력해야 합니다. 다룰 구글 스프레드시트 파일을 구분하는 고유한 문자열로, 주소창 URL 안에 들어있습니다.

예를 들어 주소가 https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0라면, /d/와 그다음 / 사이에 있는 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms 부분만 복사합니다.

스프레드시트 ID 항목의 안내 문구에는 "ID 또는 URL"이라고 되어 있지만, 실제로는 URL 전체가 아니라 ID 부분만 넣어야 동작합니다. URL을 그대로 넣으면 노드 실행이 실패합니다.

• 올바른 값: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

• 잘못된 값: https://docs.google.com/spreadsheets/d/1BxiMVs.../edit

Create Spreadsheet로 파일을 방금 만들었다면, 그 결과인 result.spreadsheetId 값을 그대로 사용하면 됩니다.

1. Create Spreadsheet — 스프레드시트 만들기

새 구글 스프레드시트 파일을 만듭니다.

작업에서 Create Spreadsheet를 선택하고, 변수 추가로 아래 항목을 꺼냅니다.

스프레드시트 제목을 비워두면 New Spreadsheet라는 이름으로 만들어집니다.

노드 테스트를 실행하면 결과 탭의 result를 펼쳐 아래 값을 확인할 수 있습니다. 시트 속성·서식 등 세부 정보까지 함께 반환되지만, 실제로 활용하게 되는 값은 아래 두 가지입니다.

이 작업으로 만든 파일에 값을 쓰거나 읽으려면, 다른 작업의 스프레드시트 ID 항목에 result.spreadsheetId의 값을 그대로 입력하면 됩니다.

2. Get Spreadsheet — 파일 정보 조회

파일의 제목과 그 안에 들어있는 시트(탭) 목록을 가져옵니다. 셀 내용은 가져오지 않습니다. 셀 값을 읽으려면 Get Sheet Data를 사용합니다.

작업에서 Get Spreadsheet를 선택하고, 변수 추가로 아래 항목을 꺼냅니다. 새로 등장하는 옵션은 없고, 둘 다 앞서 스프레드시트 ID, 타임아웃에서 다룬 항목입니다.

결과는 Create Spreadsheet와 같은 형태입니다. 결과 탭에서 result를 펼치면 파일 제목은 result.properties.title, 시트(탭) 목록은 result.sheets 배열에서 확인할 수 있습니다. 시트가 여러 개면 배열에도 그만큼 항목이 들어있으며, 각 시트의 이름은 result.sheets[번호].properties.title에 담겨 있습니다.

3. Create Sheet — 시트(탭) 추가

이미 있는 파일 안에 새 시트(탭)를 추가합니다.

작업에서 Create Sheet를 선택하고, 변수 추가로 아래 항목을 꺼냅니다. 새로 등장하는 옵션은 시트 이름(sheet_name)입니다.

시트 이름을 비워두면 Sheet + 번호 형식(예: Sheet3)으로 자동 생성됩니다. 이 번호는 파일 안에서 지금까지 실제로 만들어진 시트 수를 기준으로 계속 증가하며, 중간에 시트를 지워도 줄어들지 않습니다. 예를 들어 Sheet14까지 만든 뒤 전부 지우고 다시 만들어도 다음 이름은 Sheet1이 아니라 Sheet15입니다.

같은 이름의 시트가 이미 있으면 API operation failed: Failed to create sheet (HTTP 400) 오류가 발생합니다. 날짜처럼 매번 달라지는 이름을 쓰거나, Get Spreadsheet로 먼저 시트 목록을 확인하시기 바랍니다.

노드 테스트를 실행하면 결과 탭에서 result → replies → [0] → addSheet → properties 순서로 펼쳐 아래 값을 확인할 수 있습니다.

4. Get Sheet Data — 시트 데이터 읽기

지정한 범위의 셀 값을 읽어옵니다.

작업에서 Get Sheet Data를 선택하고, 변수 추가로 아래 항목을 꺼냅니다.

시트 범위를 비워두면 오류가 발생합니다. 시트 이름을 생략하고 A:Z처럼 열 범위만 입력하면 Sheet1 탭을 대상으로 합니다. 데이터 해석 방법(major_dimension)은 Rows, Columns 중에서 고릅니다. Rows(기본)이면 사람이 보는 표 모양 그대로 한 줄씩 받고, Columns이면 같은 열의 값끼리 모아서 받습니다. 특별한 이유가 없다면 Rows를 그대로 사용합니다.

노드 테스트를 실행하면 결과 탭에서 result를 펼쳐 아래 값을 확인할 수 있습니다.

시트가 아래와 같이 생겼다면,

result.values는 [["이름", "나이", "도시"], ["John", 30, "서울"]]처럼 행마다 배열로 담깁니다.

범위에 값이 하나도 없으면 result에 range, majorDimension만 담기고 values 자체가 아예 없습니다. 뒤에 이어지는 노드가 "values에 배열이 있다"고 전제하면 실패할 수 있으니 빈 경우를 대비해 두시기 바랍니다.

5. Append to Sheet — 데이터 이어붙이기

기존 데이터 맨 아래에 새 줄을 추가합니다. 어디가 마지막 줄인지는 구글이 알아서 찾습니다.

작업에서 Append to Sheet를 선택하고, 변수 추가로 아래 항목을 꺼냅니다. 필드 구성은 6. Update Sheet와 동일합니다.

Update Sheet와 결정적으로 다른 점은 시트 범위의 의미입니다. Append to Sheet에서는 "여기에 써라"가 아니라 "여기서부터 표를 찾아라" 라는 뜻입니다. Sheet1!A:C처럼 열 범위로 넓게 지정하면, 이미 값이 채워진 줄 다음부터 자동으로 이어 붙습니다.

시트 범위로 지정한 열 폭보다 값의 열 개수가 더 많으면, 범위를 벗어난 열까지도 그대로 써집니다. 예를 들어 시트 범위를 Sheet1!A:B(2열)로 줘도 값이 3열짜리면 C열까지 씁니다. 즉 시트 범위의 열 폭은 "여기까지만 써라"는 제한이 아니라, 기존 표를 찾기 위한 기준일 뿐입니다. Sheet1!A2:B3처럼 좁은 범위를 줘도, Sheet1처럼 시트 이름만 줘도 동일하게 동작합니다.

값에는 한 번에 여러 행을 넣어도 됩니다. 예를 들어 [["Alice", 28, "인천"], ["Bob", 34, "대구"]]처럼 두 행을 넣으면 두 행이 한꺼번에 이어 붙습니다.

노드 테스트를 실행하면 결과 탭에서 result를 펼쳐 아래 값을 확인할 수 있습니다.

6. Update Sheet — 데이터 덮어쓰기

지정한 위치에 값을 정확히 그 자리에 씁니다. 원래 있던 값은 사라집니다.

작업에서 Update Sheet를 선택하고, 변수 추가로 아래 항목을 꺼냅니다.

시트 범위와 값의 크기를 맞춰야 합니다. 범위가 3줄인데 값이 5줄이면 오류가 나고, 범위가 3줄인데 값이 2줄이면 남은 3번째 줄은 지워지지 않고 그대로 남습니다. 지우면서 새로 쓰고 싶다면 Clear Sheet로 먼저 비우고 쓰는 편이 안전합니다.

노드 테스트를 실행하면 결과 탭에서 result를 펼쳐 아래 값을 확인할 수 있습니다.

Append to Sheet와 달리 위 값들이 updates로 한 번 더 감싸이지 않고 result 바로 아래에 있습니다.

7. Clear Sheet — 데이터 지우기

지정한 범위의 값만 지웁니다. 시트 자체나 서식(색, 테두리 등)은 그대로 남습니다.

작업에서 Clear Sheet를 선택하고, 변수 추가로 아래 항목을 꺼냅니다. 새로 등장하는 옵션은 없습니다.

제목 행은 남기고 데이터만 비우려면 2번째 줄부터 범위를 지정합니다. Sheet1!A2:Z1000처럼 지정하면 1행의 제목은 남고 2행 이후의 값만 지워집니다.

노드 테스트를 실행하면 결과 탭에서 result를 펼쳐 아래 값을 확인할 수 있습니다.

값만 지워질 뿐 셀 서식(색, 테두리 등)이나 시트 자체는 그대로 남습니다.

범위 표기법

시트 범위(range_name) 항목은 엑셀에서 쓰는 셀 주소 방식과 같습니다. 시트이름!시작칸:끝칸 형태로 입력합니다.

시트 이름에 공백이나 한글이 있으면 작은따옴표로 감싸는 것을 권장합니다. 감싸지 않아도 내부적으로 따옴표가 붙어 정상 동작하지만, 표기를 명확히 하려면 감싸서 쓰는 편이 좋습니다.

• 권장: '매출 요약'!A1:D100

• 따옴표 없이도 동작: 매출 요약!A1:D100

값 (표 데이터) 넣는 법

값(values) 항목은 표 한 장을 통째로 2차원 배열로 적는다고 생각하면 됩니다.

1. 한 줄(행)은 대괄호 [ ]로 묶습니다. 예: ["John", 30, "서울"]

2. 여러 줄은 그 대괄호들을 다시 바깥 대괄호로 묶습니다. 예: [줄1, 줄2, 줄3]

아래 표를 넣고 싶다면,

다음과 같이 씁니다.

[
  ["이름", "나이", "도시"],
  ["John", 30, "서울"],
  ["Jane", 25, "부산"]
]

[
  ["이름", "나이", "도시"],
  ["John", 30, "서울"],
  ["Jane", 25, "부산"]
]

[
  ["이름", "나이", "도시"],
  ["John", 30, "서울"],
  ["Jane", 25, "부산"]
]

한 줄만 넣을 때도 바깥 대괄호가 필요합니다.

• 올바른 예: [["Alice", 28, "인천"]]

• 잘못된 예: ["Alice", 28, "인천"] — 세로로 잘못 들어가거나 오류가 발생할 수 있습니다

글자는 큰따옴표 " "로 감싸고, 숫자는 따옴표 없이 씁니다. 빈 칸은 ""로 둡니다.

칸 하나에 넣을 수 있는 값의 종류는 아래와 같습니다.

날짜·백분율·금액·수식은 값 입력 옵션이 User Entered일 때만 해석됩니다. Raw로 두면 전부 글자 그대로 들어갑니다. 링크는 예외로, User Entered·Raw 어느 쪽이든 URL 형태 문자열이면 자동으로 클릭 가능한 링크가 됩니다. 자세한 비교는 값 입력 옵션에서 다룹니다.

글자 안에 큰따옴표나 줄바꿈을 넣을 때는 앞에 역슬래시 \를 붙입니다.

작은따옴표 '와 쉼표 ,는 글자 안에서 그대로 써도 됩니다.

값 입력 옵션

값 입력 옵션(value_input_option)은 Append to Sheet, Update Sheet 작업에서 넣은 값을 구글이 해석할지, 글자 그대로 둘지 정하는 항목입니다.

Raw를 선택해야 하는 대표적인 경우는 전화번호·우편번호·사번처럼 앞자리 0이 사라지면 안 되는 값을 다룰 때입니다. 그 외에는 기본값 User Entered를 그대로 사용합니다.

같은 값(예: 날짜·백분율·숫자·수식)을 한 줄은 User Entered로, 한 줄은 Raw로 각각 써서 비교하면 차이가 뚜렷합니다. User Entered 줄은 날짜·퍼센트·숫자가 모두 오른쪽 정렬로 표시되어 실제 날짜·숫자 타입으로 인식됐음을 알 수 있고, =SUM(1,2,3) 같은 수식도 계산되어 결과값으로 들어갑니다. Raw 줄은 왼쪽 정렬인 문자열 그대로 저장되어, 수식도 글자 그대로 남습니다.

링크(https://example.com 같은 URL 문자열)는 두 옵션 모두 클릭 가능한 링크로 표시됩니다. 구글 시트가 URL 형태의 문자열을 값 입력 옵션과 무관하게 자동으로 링크화하는 것으로 보입니다.

응답에 수정된 값 포함

응답에 수정된 값 포함(include_values_in_response)은 Append to Sheet, Update Sheet 작업에서 변수 추가로 꺼낼 수 있는 체크박스입니다.

켜면 result.updates 안에 updatedData가 추가되고, 결과 탭에서 펼쳐보면 그 안에 실제로 써진 범위(updatedData.range)와 값(updatedData.values)이 담긴 것을 확인할 수 있습니다.

값 입력 옵션이 User Entered라 구글이 값을 변환해 저장했을 가능성이 있을 때(예: "0123"을 넣었는데 123으로 저장된 경우), 실제로 무엇이 들어갔는지 확인하려면 켭니다. 데이터가 많으면 결과가 그만큼 커지므로 평소에는 꺼두는 편을 권장합니다.

타임아웃

구글의 응답을 기다릴 최대 시간입니다.

• 단위: 초 (기본값 60초)

• 소수점 없이 정수로 입력

넓은 범위를 읽거나 많은 행을 한 번에 쓸 때 시간 초과 오류가 발생하면 이 값을 늘립니다. 그래도 실패한다면 범위를 나눠서 여러 번 처리하는 방법을 검토하시기 바랍니다.

여러 노드로 이어 쓰려면

이 문서의 예제는 노드 하나만 사용해 각 작업의 입력·출력을 확인하는 방식입니다. 실제 워크플로에서는 "새 파일을 만들고 → 그 ID로 값을 쓰는" 것처럼 여러 Google Sheets 노드를 이어서 값을 자동으로 넘겨야 하는 경우가 많습니다.

각 작업의 출력이 result라는 Object 하나에 중첩되어 있어서, spreadsheetId처럼 그 안의 값 하나만 다음 노드의 String 항목(예: spreadsheet_id)에 바로 드래그 앤 드롭으로 연결할 수는 없습니다. 이런 경우 파이썬(Python) 노드에서 Google Sheets 노드를 함수 노드로 연결해 호출하고, result.get("spreadsheetId")처럼 필요한 값만 꺼내 쓰는 방식을 사용합니다. 이 구성은 파이썬 코드 작성이 필요한 고급 활용이라 이 문서에서는 다루지 않습니다.

이 노드로 할 수 없는 것

Google Sheets 노드는 아래 작업을 지원하지 않습니다. 필요하다면 구글 스프레드시트에서 직접 처리해야 합니다.

• 시트(탭) 삭제, 이름 변경, 순서 바꾸기

• 스프레드시트 파일 삭제, 공유 설정 변경

• 셀 서식 지정 (글꼴, 색, 테두리, 조건부 서식)

• 행/열 삽입·삭제, 열 너비 조정

• 차트·피벗 테이블 만들기

• 필터·정렬 적용

자주 하는 실수

다음 단계

🎉 축하합니다! 에이전트리아의 Google Sheets 노드로 7가지 작업을 각각 실행해 봤습니다.

Create Spreadsheet로 만든 파일에 Update Sheet로 제목 행을 쓰고 Append to Sheet로 데이터를 쌓는 것처럼 여러 작업을 이어 쓰는 워크플로도 만들어 보시기 바랍니다.

에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.

당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.

• 더 많은 어빌리티 예제가 궁금하다면 🔗어빌리티 가이드 페이지를 확인하세요.

• 에이전트 예제를 원한다면 🔗에이전트 가이드 페이지를 확인하세요.

자주 묻는 질문

Google Sheets 노드란 무엇인가요?

Google Sheets 노드는 에이전트리아에서 구글 스프레드시트 파일을 만들고, 조회하고, 시트를 추가하고, 셀 값을 읽고 쓰고 지우는 노드입니다. '유틸리티 · 생산성' 카테고리에 속하며, 작업 항목에서 Create Spreadsheet, Get Spreadsheet, Create Sheet, Get Sheet Data, Append to Sheet, Update Sheet, Clear Sheet 중 하나를 선택해 동작을 정합니다.

Google Sheets 노드를 사용하려면 무엇을 준비해야 하나요?

구글 크리덴셜을 등록하고 구글 계정을 연동해야 합니다. 연동 방법은 🔗구글 크리덴셜 설정 가이드를 참고하시기 바랍니다. 연동한 계정이 접근할 수 있는 스프레드시트만 다룰 수 있으므로, 다른 사람의 시트를 다루려면 미리 공유받아야 합니다.

노드 편집기에 스프레드시트 ID 같은 항목이 안 보여요.

Google Sheets 노드는 크리덴셜과 작업만 기본으로 보이고, 나머지 입력 항목은 전부 변수 추가 버튼으로 체크해서 꺼내야 합니다. 필수 항목도 예외가 아니므로, 사용하려는 작업에 필요한 항목을 변수 추가 모달에서 빠짐없이 체크하시기 바랍니다.

Append to Sheet와 Update Sheet는 어떻게 다른가요?

Append to Sheet는 기존 데이터의 맨 아래 빈 줄을 스스로 찾아 새 행을 추가합니다. 반면 Update Sheet는 지정한 범위에 정확히 값을 쓰며, 그 자리에 있던 값은 사라집니다. 로그나 접수 내역처럼 계속 쌓아야 하는 데이터는 Append to Sheet를, 특정 셀이나 영역을 갱신해야 하는 경우는 Update Sheet를 사용합니다.

값 항목에는 표 데이터를 어떤 형식으로 넣나요?

행마다 값을 대괄호로 묶고, 그 행들을 다시 바깥 대괄호로 묶는 2차원 배열 형식으로 입력합니다. 예를 들어 두 행짜리 표는 [["John", 30, "서울"], ["Jane", 25, "부산"]]처럼 씁니다. 한 행만 넣을 때도 바깥 대괄호를 생략할 수 없습니다. 자세한 표기 규칙은 값 (표 데이터) 넣는 법을 참고하시기 바랍니다.

한 노드에서 여러 작업을 처리할 수 있나요?

아니요. Google Sheets 노드 하나는 작업 항목에서 선택한 동작 한 가지만 실행합니다. 여러 작업을 이어서 처리하려면 Google Sheets 노드를 여러 개 배치하고, 노드마다 다른 작업을 선택해 순서대로 연결해야 합니다.