[Next.js] Google Sheets API 연동 방법

Google Sheets API 연동 방법

들어가며

• Next.js에서 Google Sheets API를 연동하는 방법을 간단하게 정리해본다.

 

방법

① Google Cloud Console에서 새로운 프로젝트 생성하기

• 아래의 Google Cloud Console에 접속한다.
  • 구글 계정으로 로그인해야 하고, Google Cloud Console 가입을 해야할 수도 있다.

Google 클라우드 플랫폼

 

 

• 그리고 새로운 프로젝트를 생성한다.
  
  • 새로운 프로젝트는 페이지 상단 왼쪽의 사각형 버튼을 클릭하여 생성할 수 있다.
    • 이전에 프로젝트를 생성하지 않았을 경우, 임의의 프로젝트 이름이 생성되어 있다.

새로운 프로젝트를 생성하는 모습

 

• 알림창에서 프로젝트 생성 여부를 확인할 수 있다. @[프로젝트 선택]@을 클릭하여 생성된 프로젝트로 이동한다.

 

② Google Sheets API 활성화하기

• 생성한 프로젝트에 들어온 후, 상단의 검색창에 @API@를 검색한 후, @[API 및 서비스]@를 클릭한다.

 

• 왼쪽 사이드바의 @[라이브러리]@ 탭을 클릭한다.

 

• 검색창에 @sheets@ 를 검색한다. 그리고 표시되는 @Google Sheets API@ 항목을 클릭한다.

 

• @[사용]@ 버튼을 클릭한다.

 

• 이제 Google Sheets API를 사용할 수 있게 되었다.

 

③ 서비스 계정 생성하기

• 이제 페이지 왼쪽 상단에 있는 @[탐색 메뉴]@ 햄버거 버튼을 눌러준다.
• 사이드바가 표시되면, @[IAM 및 관리자]@ > @[서비스 계정]@을 클릭해준다.

[IAM 및 관리자] → [서비스 계정]

 

• @[+ 서비스 계정 만들기]@ 버튼을 클릭해서 서비스 계정을 만들어준다.

 

• @서비스 계정 이름@, @서비스 계정 ID@ 등등을 입력해준다.
  • @서비스 계정 ID@의 경우, 향후 구글 시트 문서에서 공유할 대상인 이메일의 ID로 사용된다. 
• 그리고 각 멤버별 권한을 설정해준다.
  • 본인의 경우 @소유자@로 설정해준다.
  • 필요에 따라 다른 멤버들을 추가하여 권한을 부여할 수 있다.

 

• 서비스 계정이 생성된 것을 확인해준다.

 

 

생성한 서비스 계정은 향후 구글 시트 문서에서 초대될 것이다. (편집자 권한) API 연동 작업은 이 계정을 통해서 이루어지며, 이 계정이 해당 문서에 내용을 추가하는 방식으로 API 연동 작업이 이루어진다.

 

 

③ 인증 정보 키 파일(json) 다운로드 받기

• 생성한 서비스 계정 정보가 있는 행의 @[이메일]@ 컬럼의 셀을 클릭한다.

 

• 상단의 @[키]@ 탭을 클릭한 후, 새로운 키를 생성해준다.
  • 키 유형은 @JSON@으로 해준다.

 

• 키가 생성되면 자동으로 인증 정보가 담긴 키 파일(@.json@)이 다운로드 된다.

 

• 키 파일의 내용은 다음과 같이 구성되어 있다.

 

인증 정보 키 파일.json

{
  "type": "service_account",
  "project_id": "spread-sheet-465108",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n ... \n-----END PRIVATE KEY-----\n",
  "client_email": "sheet-practice@spread-sheet-465108.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/sheet-practice%40spread-sheet-465108.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

 

 

④ Google Sheets에서 새로운 문서 생성 및 서비스 계정 초대하기

• Google Sheets 문서를 생성해준다.

Google Sheets: 온라인 스프레드시트 & 템플릿 | Google Workspace

 

새로운 스프레드시트를 생성해주는 모습

 

• 새로운 문서 페이지에 들어온 후, 문서 제목을 설정해준다.
• 그리고 우측 상단에 있는 @[공유]@ 버튼을 클릭하여, ②에서 생성한 서비스 계정 이메일을 넣어준다.
  • 권한은 반드시 @편집자@로 해준다.
• 그리고 @[전송]@ 버튼을 클릭한다.

 

• 그리고 A1부터 필요한 만큼까지 테이블 헤더를 적어준다.
  • API 연동을 통해 추가되는 내용들은 A2를 시작으로 아래 방향으로 추가될 것이다.

테이블 헤더를 설정해준다.

 

⑤ 인증 정보 키 파일 내용을 환경 변수에 넣기

• ③에서 생성한 인증 정보 키 파일(json)을 환경 변수(@.env@)에 추가해주는 작업이다.
• 다운로드 받은 인증 정보 키 파일(json)을 그대로 불러와서 인증 처리를 해줄 수도 있지만, 보안 관련 문제가 있을 수 있으므로 환경 변수에 추가하여 불러오는 것이 좋다.
• 키 안의 내용을 이스케이프 처리 후 문자열로 처리해도 되지만, JSON 변환 시, 파싱(Parsing) 오류가 빈번하게 발생한다.
• 배포 환경에서 안전하게 환경 변수 형식으로 불러와지도록 하기 위해 다음과 같이 base64 인코딩 처리를 해준다.

 

base64 형식으로 디코딩하기

• 터미널에 아래 명령을 실행하여 인증 정보가 담긴 키 파일(@credentials.json@)의 내용을 base64 형식으로 디코딩한다.

$ base64 -w 0 credentials.json > credentials_base64.txt

 

• @credentials_base64.txt@ 파일 안에 있는 내용을 복사해서 프로젝트 최상단 경로(@/@)의 환경 변수 파일(@.env@) 안에 넣어준다.

 

.env.local

# Google API
GOOGLE_CREDENTIALS_BASE64=ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3Vu...

 

• base64로 인코딩 된 데이터를 다시 JSON 형식으로 디코딩 하려면, 다음과 같이 사용하면 된다.

import { google } from "googleapis";
import fs from "fs";

const base64Credentials = process.env.GOOGLE_CREDENTIALS_BASE64;

if (!base64Credentials) {
  throw new Error("Missing GOOGLE_CREDENTIALS_BASE64 env variable");
}

// Base64 디코딩
const decodedCredentials = Buffer.from(base64Credentials, "base64").toString("utf-8");
const credentials = JSON.parse(decodedCredentials);

// Google 인증 객체 생성
const auth = new google.auth.GoogleAuth({
  credentials,
  scopes: ["https://www.googleapis.com/auth/spreadsheets"],
});

 

⑥ Google Sheets 문서 ID 환경 변수에 넣기

• ④에서 생성한 Google Sheets 문서의 ID 또한 환경 변수(@.env@) 파일에 넣어준다.
• 시트 문서의 ID는 문서 URL에서 @/d/@와 @/edit@ 사이에 있는 값이다.
  • 아래의 예시의 경우, @asdkSndaskdnaSADnkasdnaSADasdY@가 문서 ID이다.

https://docs.google.com/spreadsheets/d/asdkSndaskdnaSADnkasdnaSADasdY/edit?gid=0#gid=0

 

.env.local

SPREADSHEET_ID=asdkSndaskdnaSADnkasdnaSADasdY

 

⑦ API 연동 코드 작성하기

• 아래의 예제 코드는 Next.js 14 버전 기준으로 작성되었다.
• 다양한 사용법이나 다른 플랫폼에서 사용하려면 아래의 API 문서를 참고한다.

Google Sheets API 개요  |  Google for Developers

 

/pages/api/write-to-sheet.js

• @range@ (✅) 부분을 자신의 시트 설정에 맞게 수정해준다.

import { google } from "googleapis";

export async function POST(req: Request) {
  try {
    const { writer } = await req.json();
    if (!writer) {
      return new Response(JSON.stringify({ message: "writer는 필수입니다." }), { status: 400 });
    }

    // 인증키 가져오기
    const base64 = process.env.GOOGLE_CREDENTIALS_BASE64;
    if (!base64) throw new Error("Missing credentials");

    // 디코딩 (JSON)
    const credentials = JSON.parse(Buffer.from(base64, "base64").toString("utf-8"));
    credentials.private_key = credentials.private_key?.replace(/\\n/g, "\n");

    const auth = new google.auth.GoogleAuth({
      credentials,
      scopes: ["https://www.googleapis.com/auth/spreadsheets"],
    });

    const sheets = google.sheets({ version: "v4", auth });
    const spreadsheetId = process.env.SPREADSHEET_CONTACT_ID!;
    const date = new Date().toLocaleString("ko-KR", { timeZone: "Asia/Seoul" });

    await sheets.spreadsheets.values.append({
      spreadsheetId,
      range: "시트1!A2:B",    // ✅
      valueInputOption: "USER_ENTERED",
      requestBody: { values: [[writer, date]] },
    });

    return Response.json({ message: "등록 완료!" });
  } catch (err) {
    console.error("Google Sheets Error:", err);
    return new Response(JSON.stringify({ message: "서버 오류!" }), { status: 500 });
  }
}

 

사용 예제 코드

const submitWriter = async () => {
  const res = await fetch("/api/write-to-sheet", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ writer: "홍길동" }),
  });

  const data = await res.json();
  if (res.ok) {
    console.log("성공:", data.message);
  } else {
    console.error("실패:", data.message);
  }
};

 

 

참고 사이트

JavaScript 빠른 시작  |  Google Sheets  |  Google for Developers

Google Sheets API  |  Google for Developers