문서 작성 과정을 자동화하고 싶다면 Google Docs API를 활용하는 게 가장 확실한 방법이에요. 보고서를 매번 수기로 만드는 대신, 코드로 문서를 생성하고 내용을 채워 넣으면 반복 작업을 크게 줄일 수 있거든요. 처음 시작할 때 알아둘 기본 사용법을 정리해볼게요.
Google Cloud 프로젝트 생성과 API 활성화
Google Docs API를 사용하려면 먼저 Google Cloud Console에서 프로젝트를 생성해야 해요. 프로젝트를 만든 뒤에는 API 라이브러리에서 ‘Google Docs API’를 검색해 활성화 버튼을 눌러줘야 사용할 수 있는 상태가 돼요.
문서를 생성하고 내용을 다루려면 Docs API뿐 아니라 파일 목록 조회나 폴더 이동을 위해 Google Drive API도 함께 활성화하는 경우가 많아요. 두 API는 서로 다른 역할을 하지만 실무에서는 세트로 쓰이는 경우가 흔해요.
OAuth 2.0 인증 설정하기
API를 호출하려면 인증 정보가 필요해요. Google Cloud Console의 ‘사용자 인증 정보’ 메뉴에서 OAuth 클라이언트 ID를 생성하고, 데스크톱 앱이나 웹 애플리케이션 등 사용 목적에 맞는 애플리케이션 유형을 선택해야 해요.
서버 간 자동화 작업이라면 서비스 계정을 만들어 JSON 키 파일을 발급받는 방식이 더 편리해요. 서비스 계정은 사용자 로그인 없이도 프로그램이 독립적으로 인증할 수 있다는 장점이 있어서, 정기적으로 실행되는 배치 작업에 특히 적합해요.
인증 범위(scope) 설정도 중요한데, 문서 편집이 필요하면 `https://www.googleapis.com/auth/documents` 범위를, 파일 접근까지 필요하면 Drive 관련 범위를 함께 지정해야 해요.
클라이언트 라이브러리 설치와 초기화
Python을 기준으로 하면 `google-api-python-client`, `google-auth-httplib2`, `google-auth-oauthlib` 세 패키지를 설치하는 게 기본이에요. 설치 후에는 인증 정보를 불러와 `build()` 함수로 Docs API 서비스 객체를 생성하는 과정을 거쳐요.
다른 언어를 쓴다면 Node.js의 `googleapis` 패키지, Java의 `google-api-client` 라이브러리처럼 각 언어별 공식 클라이언트가 마련돼 있어서, 사용하는 개발 환경에 맞춰 선택하면 돼요.
문서 생성과 텍스트 삽입
새 문서를 만들 때는 `documents.create()` 메서드를 호출하면서 제목을 지정해주면 돼요. 문서가 생성되면 고유한 documentId가 반환되는데, 이후 모든 편집 작업은 이 ID를 기준으로 이루어져요.
텍스트를 삽입할 때는 `documents.batchUpdate()` 메서드를 사용해요. 이 메서드는 여러 편집 요청을 한 번에 묶어서 처리할 수 있다는 게 특징인데, 예를 들어 텍스트 삽입과 서식 적용을 하나의 요청 배열에 담아 한 번의 API 호출로 처리할 수 있어요.
- insertText 요청 – 특정 위치(index)에 원하는 문자열을 삽입할 때 사용하는 기본 요청이에요.
- updateTextStyle 요청 – 삽입한 텍스트에 굵게, 기울임, 색상 등의 서식을 적용할 때 사용해요.
- insertTable 요청 – 문서 안에 표를 삽입해야 할 때 활용하는 요청 유형이에요.
실전에서 자주 겪는 이슈
batchUpdate로 여러 요청을 순서대로 보낼 때는 인덱스(index) 계산에 주의해야 해요. 앞선 요청에서 텍스트를 삽입하면 뒤따르는 요청의 인덱스 위치가 밀리기 때문에, 요청 순서와 인덱스를 정확히 계산하지 않으면 원하지 않는 위치에 텍스트가 들어가는 경우가 흔해요.
또한 무료 할당량을 초과하면 API 호출이 제한되는데, Google Cloud Console의 할당량 관리 페이지에서 현재 사용량을 확인할 수 있어요. 대량의 문서를 자동 생성하는 서비스를 만든다면 이 할당량 한도를 미리 파악해두는 게 안전해요.
정리하면 Google Docs API는 Cloud 프로젝트 생성과 API 활성화, OAuth 인증 설정, 클라이언트 라이브러리 초기화 과정을 거쳐 사용할 수 있어요. 문서 생성 후에는 batchUpdate로 텍스트 삽입과 서식 적용을 처리하되, 인덱스 계산과 할당량 관리에 유의하면서 문서 자동화를 구현할 수 있어요.