본문으로 건너뛰기
SheetForge

Google 시트 설정 — 서비스 계정 및 JSON 키

SheetForge는 두 가지 모드로 Google 시트를 읽는다.

  • ExportUrl은 자격 증명이 필요 없다: 링크로 시트를 공유하고, 각 탭의 #gid= 값을 등록한 다음 임포트하면 된다. 읽기 전용이다.
  • SheetsApi는 Google 서비스 계정으로 인증하며, 그 밖의 모든 것 — 비공개 시트, 쓰기 반영(reflect), Push — 을 가능하게 한다.

이 페이지는 SheetsApi 설정을 처음부터 끝까지 안내한다 — 서비스 계정 생성, JSON 키 다운로드, 스프레드시트를 그 계정과 공유하기, 그리고 SheetForge가 그 키를 가리키게 하기까지. Google Cloud 사전 경험은 전혀 필요 없다 — 모든 단계는 웹 브라우저 안에서 이루어지며 비용은 전혀 들지 않는다.

전체 흐름:

  1. Google Cloud 프로젝트를 생성한다.
  2. 그 안에서 Google Sheets API를 활성화한다.
  3. 서비스 계정을 생성한다.
  4. 계정의 JSON 키를 다운로드한다.
  5. 스프레드시트를 그 계정의 이메일 주소와 공유한다.
  6. SheetForge가 그 키를 가리키게 한다.

1. Google Cloud 프로젝트 생성

  1. console.cloud.google.com을 열고 Google 계정으로 로그인한다 — 스프레드시트를 소유한 계정일 필요는 없다. 개인 계정은 항상 동작한다. 일부 회사의 Google Workspace 조직은 정책으로 서비스 계정 키 다운로드를 비활성화하는데, 이 경우 4단계가 조직 정책 에러로 실패한다(아래 "문제가 발생했다면" 참고). 처음 방문하면 콘솔에 도달하기 위해 서비스 약관 동의 프롬프트를 수락해야 한다.
  2. 상단 바에서 프로젝트 선택기(Google Cloud 로고 옆의 드롭다운)를 클릭한 다음 New project를 클릭한다.
  3. 아무 이름이나 입력하고(예: sheetforge-sheets) Create를 클릭한다. organization과 location은 기본값 그대로 둔다.
  4. "project created" 알림이 나타나면, 선택기에서 새 프로젝트를 선택한다. 아래의 모든 과정은 이 프로젝트 안에서 이루어지므로, 계속 선택된 상태를 유지해야 한다.

프로젝트는 API 설정을 담는 컨테이너일 뿐이다. 생성은 무료이며, 이 가이드에서의 Sheets API 사용에도 비용이 들지 않는다.

2. Google Sheets API 활성화

  1. 왼쪽 메뉴(☰)를 열고 APIs & Services ▸ Library로 이동한다.
  2. Google Sheets API를 검색해 결과를 연다.
  3. Enable을 클릭한다. 버튼에 Manage라고 쓰여 있다면 API가 이미 활성화된 것이다 — 할 일이 없다.

3. 서비스 계정 생성

서비스 계정은 자신만의 이메일 주소를 가진 기계 신원이다. SheetForge는 이 신원으로 로그인한다 — 사용자의 개인 Google 비밀번호는 전혀 관여하지 않는다.

  1. APIs & Services ▸ Credentials로 이동한다.
  2. + Create credentials ▸ Service account를 클릭한다.
  3. 이름을 입력한다(예: sheetforge-reader). 계정 ID는 자동으로 채워진다. Create and continue를 클릭한다.
  4. "Grant this service account access to project"와 "Grant users access" 단계는 선택 사항이다 — 둘 다 건너뛰고 Done을 클릭한다. 스프레드시트에 대한 접근 권한은 프로젝트 역할이 아니라 시트를 공유하는 것(5단계)으로 부여된다.
  5. 콘솔이 OAuth consent screen 설정을 제안하더라도 무시한다 — 서비스 계정은 이를 사용하지 않는다.

4. JSON 키 다운로드

  1. Credentials 페이지로 돌아가서, 방금 생성한 서비스 계정을 클릭한다("Service accounts" 아래).
  2. Keys 탭을 연다.
  3. Add key ▸ Create new key를 클릭하고, JSON을 선택한 다음 Create를 클릭한다.
  4. 브라우저가 sheetforge-sheets-1a2b3c.json과 같은 이름의 파일을 다운로드한다. 이것이 유일한 사본이다 — Google은 재다운로드를 위해 이를 보관하지 않는다. 파일을 잃어버렸다면, Keys 탭에서 그 키를 삭제하고 새로 생성하라.

이 파일을 비밀번호처럼 다루어라:

  • Unity 프로젝트와 저장소 바깥의 어딘가로 옮긴다. 예: C:/keys/sheetforge.json.
  • 결코 Assets/ 아래에 두지 마라 — 그 안의 모든 것은 프로젝트와 함께 커밋되며, 우연한 참조(또는 Resources/StreamingAssets 폴더)가 이를 빌드로 실어 나를 수 있다.
  • 키가 유출되면, Keys 탭에서 삭제하고(즉시 폐기된다) 새로 생성한다.

5. 스프레드시트를 서비스 계정과 공유

키만으로는 아무 권한도 주어지지 않는다. 서비스 계정은 자신과 명시적으로 공유된 시트만 읽을 수 있다 — 사람인 협업자와 정확히 동일하다.

  1. 다운로드한 JSON 파일을 아무 텍스트 에디터로 열고 client_email 값을 복사한다. sheetforge-reader@sheetforge-sheets.iam.gserviceaccount.com과 같은 형태다.
  2. Google Sheets에서 스프레드시트를 열고 Share를 클릭한다.
  3. 주소를 붙여넣고 역할을 선택한다:
    • 임포트만 한다면 Viewer로 충분하다.
    • 쓰기 반영 — 작성 reflect와 Push — 에는 Editor가 필요하다.
  4. "Notify people"를 끄고(그 주소에는 받은편지함이 없다) 확인한다.
  5. Google이 조직 바깥으로 공유한다고 경고하더라도 확인을 진행한다 — 서비스 계정은 어떤 조직에도 속하지 않는다.

이 단계를 건너뛰는 것이 가장 흔한 설정 실수다 — 그러면 키가 아무리 정확해도 모든 요청이 권한 에러로 실패한다.

6. SheetForge가 키를 가리키게 하기

  1. 임포트 설정 에셋에서, source를 GoogleSheet로, access mode를 SheetsApi로 설정한다.
  2. spreadsheetId에 시트 URL의 긴 ID를 채운다: https://docs.google.com/spreadsheets/d/<this part>/edit.
  3. SheetForge에게 키 파일의 위치를 알려준다. 두 가지 방법 중 하나로:
    • 권장 — 환경 변수. **SHEETFORGE_SHEETS_KEY**를 JSON 파일의 절대 경로로 설정한다. 각 개발자가 자신의 것을 설정하며, 어떤 경로도 저장소에 들어가지 않고, 설정 필드보다 우선한다.
      • Windows에서는 터미널에서 setx SHEETFORGE_SHEETS_KEY "C:\keys\sheetforge.json"을 실행한 다음 Unity 와 Unity Hub를 재시작한다(이미 실행 중인 프로세스는 예전 환경을 그대로 유지한다).
      • macOS/Linux에서는 셸 프로필에서 export하고 그 셸에서 Unity를 시작하거나, macOS에서는 launchctl setenv를 사용한다.
    • 또는 — 설정 필드. serviceAccountKeyPath에 경로를 넣되, 저장소 바깥을 가리키게 한다.
  4. Tools ▸ SheetForge ▸ 데이터 스튜디오에서 ↓ 시트에서 가져오기를 누른다. 성공한 리포트는 전체 체인 — 프로젝트, API, 계정, 공유, 키 — 이 동작하고 있다는 뜻이다.

문제가 발생했다면

  • 권한 에러(PERMISSION_DENIED / 403): 시트가 client_email 주소와 공유되지 않은 것이다(5단계) — ID는 실제 스프레드시트를 가리키지만 서비스 계정이 볼 수 없다.
  • Requested entity was not found(404): spreadsheetId가 잘못된 것이다 — 시트 URL에서 /d/와 /edit 사이의 부분을 정확히 복사하라.
  • "Service account key creation is disabled" / 4단계에서의 조직 정책 에러: 사용자의 Google Workspace 조직이 iam.disableServiceAccountKeyCreation을 강제하고 있다. 관리자에게 이 프로젝트에 대한 키 생성을 허용해 달라고 요청하거나, 개인 Google 계정으로 프로젝트를 생성한다 — 시트를 누가 소유했든, 그 프로젝트의 서비스 계정과 스프레드시트를 공유할 수 있다.
  • "Google Sheets API has not been used in project … or it is disabled": 키를 발급한 프로젝트에서 API가 활성화되지 않은 것이다(2단계) — 다른 프로젝트가 아니라 그 프로젝트에서 활성화하라. 방금 활성화한 API는 전파되기까지 몇 분이 걸릴 수 있다.
  • 키 파일을 찾을 수 없음: 경로에 오타가 있거나, 환경 변수가 생기기 전에 Unity가 시작된 것이다 — 변수를 설정한 다음 Unity와 Unity Hub를 재시작하라.
  • 키가 유출되었거나 분실됨: 서비스 계정의 Keys 탭에서 삭제하고, 새 JSON 키를 생성한 다음 파일을 교체하라. 그 밖의 어떤 것도 바뀌지 않는다 — 이메일 주소와 시트 공유는 그대로 유효하다.

관련 페이지