728x90

Google API 사용법: Google Cloud Console의 API 활성화 및 인증 정보 설정 단계별 가이드

1. Google Cloud Console 접속 및 프로젝트 생성
- 1-1. 접속
- 1-2. 프로젝트 생성
2. 결제 계정 연결 (일부 API 필수)
3. API 활성화
- 3-1. API 라이브러리 이동
- 3-2. 원하는 API 검색
- 3-3. API 선택 후 “사용” 클릭하여 활성화
4. 인증 정보 생성
- 4-1. 인증 정보 메뉴 이동
- 4-2. 인증 정보 만들기
- 4-3. 일반적인 선택 예시
5. API 호출을 위한 코드 예시
- Python 예시 (Google Drive API)
6. IAM & 보안 설정
7. 로깅 및 사용량 확인
참고 사항
예시로 많이 사용하는 Google API
Client ID / Client Secret이 필요한 인증 방식
- OAuth 2.0 인증 (사용자 인증 기반 API 호출)
- 용도
Client ID / Client Secret이 필요 없는 인증 방식
- 서비스 계정 (Service Account)
- API 키 (API Key)
인증 방식 요약
인증 방식 사용 시점
OAuth 2.0 인증 플로우 구성도
서비스 계정 인증 (JWT 기반 인증) 예시 (Python)
- 2-1. 라이브러리 설치
- 2-2. 코드 예시 (Google Sheets API)
3. API Key 제한 설정
- 3-1. API 키 생성
- 3-2. API 키 제한 설정
- 설정 방법
인증 방식 요약
추가 고려사항
OAuth 인증 토큰 발급 및 저장 전략
- 목적
- 발급 흐름 요약
- 저장 전략
- 보안 고려
- 자동 갱신 로직
서비스 계정 Google Workspace 위임 설정
- 목적
- 전제 조건
- 단계별 설정
API Key 쿼터 초과/제한 우회 전략
- 상황
- 우회 전략
인증 실패 시 오류 유형 및 대처 방법
- 공통 대처 팁
최적화 전략 요약
Keywords

Google API를 사용하여 프로그램을 개발하려면 Google Cloud Console(GCP Console)을 통해 API를 활성화하고 인증 정보를 생성하는 것이 필수입니다. 아래에 단계별로 구체적인 설정 및 사용 방법을 안내드리겠습니다.

1. Google Cloud Console 접속 및 프로젝트 생성

1-1. 접속

주소: https://console.cloud.google.com
Google 계정으로 로그인

1-2. 프로젝트 생성

상단의 프로젝트 선택 버튼 클릭
“프로젝트 만들기” 클릭
프로젝트 이름 입력 (예: my-api-project)
조직과 위치 선택 (개인 사용자는 기본값 그대로 가능)
“만들기” 클릭

2. 결제 계정 연결 (일부 API 필수)

좌측 메뉴에서 결제 > 결제 계정 만들기
카드 정보 입력 후 결제 계정 생성
프로젝트에 결제 계정 연결
→ [IAM & 관리자 > 설정] 또는 [프로젝트 설정]에서 변경 가능

3. API 활성화

3-1. API 라이브러리 이동

메뉴 > API 및 서비스 > 라이브러리

3-2. 원하는 API 검색

예: Google Drive API, YouTube Data API, Google Maps API, Gmail API 등

3-3. API 선택 후 “사용” 클릭하여 활성화

4. 인증 정보 생성

4-1. 인증 정보 메뉴 이동

메뉴 > API 및 서비스 > 사용자 인증 정보

4-2. 인증 정보 만들기

+ 사용자 인증 정보 만들기 클릭 후 선택:
- API 키: 공개 API용 (보안 취약)
- OAuth 클라이언트 ID: 사용자 권한 필요 시
- 서비스 계정 키: 서버 간 통신/자동화 용도

4-3. 일반적인 선택 예시

백엔드 서버 또는 자동화 스크립트 → 서비스 계정
- 역할: 기본적으로 프로젝트 > 편집자 또는 해당 API 권한
- 키 유형: JSON 선택 후 생성
- 생성된 JSON 키는 다운로드하여 코드에서 사용

5. API 호출을 위한 코드 예시

Python 예시 (Google Drive API)

pip install google-api-python-client google-auth google-auth-oauthlib google-auth-httplib2

from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']
SERVICE_ACCOUNT_FILE = 'service-account-key.json'

creds = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)

service = build('drive', 'v3', credentials=creds)

results = service.files().list(pageSize=10).execute()
items = results.get('files', [])

for item in items:
    print(f"{item['name']} ({item['id']})")

6. IAM & 보안 설정

서비스 계정 권한 제어:
- 메뉴 > IAM & 관리자 > IAM
- 해당 서비스 계정에 필요한 역할(Role) 추가
API 제한 설정 (필요시)
- API 키의 경우, IP 주소, referrer, API 제한을 걸어야 보안 강화 가능

7. 로깅 및 사용량 확인

메뉴 > API 및 서비스 > 사용량
메뉴 > 로그 탐색기 (Logging): 오류/성공 요청 기록 확인

참고 사항

구분	설명
서비스 계정	서버 간 작업, 자동화에 적합
OAuth 클라이언트	사용자 로그인, 인증이 필요한 API용
API 키	공개 서비스에 사용 가능하나 보안 취약
과금 주의	일부 API는 무료 할당량 초과 시 비용 발생

예시로 많이 사용하는 Google API

API 명	설명
Google Drive API	구글 드라이브 파일 관리
Gmail API	메일 송수신, 필터 관리
Google Calendar API	일정 생성, 조회
Google Sheets API	스프레드시트 자동화
YouTube Data API	유튜브 콘텐츠/통계 조회
Vision API	이미지 분석
Translation API	다국어 번역

Client ID / Client Secret이 필요한 인증 방식

OAuth 2.0 인증 (사용자 인증 기반 API 호출)

사용자 로그인이 필요한 API에서 사용
예시:
- Gmail API (사용자 이메일 조회/전송)
- Google Calendar API (사용자의 일정 생성/조회)
- Google Drive API (사용자의 파일 접근)
- YouTube Data API (사용자의 채널/영상 정보 조회)
Client ID / Secret은 OAuth 클라이언트 생성 시 자동 발급

용도

웹 애플리케이션, 모바일 앱, 데스크탑 앱, SPA(단일 페이지 앱) 등에서 로그인 후 사용자 데이터에 접근할 때 사용

Client ID / Client Secret이 필요 없는 인증 방식

서비스 계정 (Service Account)

사용자 개입 없이 서버 간 자동화 작업에 적합
예시:
- Google Sheets API를 이용한 서버 백그라운드 데이터 기록
- Cloud Storage 버킷 접근
- Cloud Vision 이미지 분석 자동화
인증: JSON 형식의 서비스 계정 키로 진행
→ Client ID/Secret 없이 인증

API 키 (API Key)

인증이 비교적 단순한 공개 API에 사용
예시:
- Google Maps API
- Google Places API
- Custom Search JSON API
브라우저 또는 앱에서 직접 API 호출 가능
→ Client ID/Secret 없이 API Key만으로 인증

인증 방식 요약

인증 방식	Client ID / Secret 필요	설명
OAuth 2.0	필요	사용자 로그인 후 데이터 접근 (예: Gmail, Calendar)
서비스 계정	불필요	백엔드 서버, 자동화 작업에 사용
API 키	불필요	단순 공개 API 접근 (지도, 검색 등)

인증 방식 사용 시점

사용 목적	권장 인증 방식	이유
사용자 로그인 후 권한이 필요한 API 사용	OAuth 2.0 (Client ID / Secret 필요)	사용자의 명시적 동의 필요
서버 간 백엔드 자동화	서비스 계정 (JSON 키)	사용자 개입 없음, 안전한 자동화 가능
지도, 검색 등 브라우저/앱에서 직접 호출	API 키	간단하고 빠른 인증, 단 보안 주의 필요

OAuth 2.0 인증 플로우 구성도

적용 대상: 사용자 인증이 필요한 Google API (예: Gmail, Calendar, Drive)

sequenceDiagram
    participant 사용자 브라우저
    participant 앱
    participant Google 서버

    사용자 브라우저 ->> 앱: Google OAuth URL로 리디렉션
    앱 ->> 사용자 브라우저: Google 로그인 화면 표시
    사용자 브라우저 ->> Google 서버: 사용자 동의
    Google 서버 ->> 사용자 브라우저: 승인 코드 발급 (auth code)
    사용자 브라우저 ->> 앱: 승인 코드 전달
    앱 ->> Google 서버: 승인 코드 전송
    Google 서버 ->> 앱: Access Token, Refresh Token 발급
    앱 ->> Google 서버: Access Token으로 Google API 호출

Refresh Token이 있으면 Access Token 재발급 가능

서비스 계정 인증 (JWT 기반 인증) 예시 (Python)

적용 대상: 백엔드 서버, 자동화 작업
사용 예시: Google Sheets, Drive, Vision API 등

2-1. 라이브러리 설치

pip install google-auth google-auth-oauthlib google-auth-httplib2 google-api-python-client

2-2. 코드 예시 (Google Sheets API)

from google.oauth2 import service_account
from googleapiclient.discovery import build

# 서비스 계정 키 JSON 경로
SERVICE_ACCOUNT_FILE = 'service-account-key.json'

# 필요한 권한 범위 설정
SCOPES = ['https://www.googleapis.com/auth/spreadsheets.readonly']

# 서비스 계정으로 인증 객체 생성
creds = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES
)

# API 클라이언트 생성
service = build('sheets', 'v4', credentials=creds)

# 스프레드시트 데이터 가져오기
spreadsheet_id = 'your-spreadsheet-id'
range_name = 'Sheet1!A1:D10'
result = service.spreadsheets().values().get(
    spreadsheetId=spreadsheet_id, range=range_name).execute()

print(result.get('values', []))

3. API Key 제한 설정

적용 대상: Google Maps, Places, Custom Search 등 API 키 기반 서비스
보안을 위해 반드시 설정할 것

3-1. API 키 생성

GCP Console → API 및 서비스 → 사용자 인증 정보 → + 사용자 인증 정보 만들기 → API 키

3-2. API 키 제한 설정

IP 주소 제한
- 서버에서 호출 시 유효
- 예: 192.168.0.0/24, 203.0.113.5
HTTP referrer 제한
- 웹사이트에서 호출 시 사용
- 예: https://example.com/*
앱 패키지 이름/서명 제한
- Android/iOS 앱에서 호출 시 사용
API 제한
- 이 키로 호출 가능한 API 명시적으로 설정

설정 방법

사용자 인증 정보 > 해당 API 키 클릭
“애플리케이션 제한 사항”, “API 제한 사항” 설정

인증 방식 요약

방식	토큰 종류	사용 위치	보안	갱신 필요 여부
OAuth 2.0	Access + Refresh Token	사용자 앱	높음	Refresh Token 사용
서비스 계정	JWT → Access Token	서버/자동화	높음	자동
API 키	Key 문자열	클라이언트	낮음 (제한 설정 필요)	없음

추가 고려사항

OAuth 인증 토큰 발급 및 저장 전략
서비스 계정 Google Workspace 위임 설정
API Key 쿼터 초과/제한 우회 전략
인증 실패 시 오류 유형 및 대처 방법

OAuth 인증 토큰 발급 및 저장 전략

목적

사용자 인증 후 발급되는 access_token과 refresh_token을 안전하게 저장하고 갱신하는 전략

발급 흐름 요약

사용자가 로그인 및 동의
authorization code 수신
access_token, refresh_token 발급
DB 등에 저장하여 이후 API 호출에 사용

저장 전략

항목	저장 위치	비고
`access_token`	메모리/DB (단기)	유효기간 1시간 내외
`refresh_token`	암호화된 DB	장기 저장 필요, 유효기간 없음 (단, 사용 안 하면 만료됨)

보안 고려

refresh_token은 반드시 암호화 저장 (예: AES256)
사용자별 식별 정보와 함께 저장 (user_id, email 등)
토큰 유출 방지를 위한 로그 감시 필요

자동 갱신 로직

access_token 만료 시 refresh_token으로 새 access_token 요청
실패 시 재로그인 유도

서비스 계정 Google Workspace 위임 설정

목적

서비스 계정이 Google Workspace 도메인의 사용자를 가장해서 API를 호출하는 기능
(예: admin@example.com의 Gmail에 접근)

전제 조건

Google Workspace 관리자 권한 필요
서비스 계정에 도메인 전체 위임(Domain-wide Delegation) 설정 필요

단계별 설정

서비스 계정 생성 시 ‘도메인 전체 위임’ 활성화
Admin Console > 보안 > API 제어 > 도메인 전체 위임
- 클라이언트 ID 등록
- 위임할 범위 입력 (comma-separated scopes)
  
  예:
```
https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/calendar
```
코드에서 사용자 지정

from google.oauth2 import service_account

creds = service_account.Credentials.from_service_account_file(
    'key.json',
    scopes=['https://www.googleapis.com/auth/gmail.readonly'],
    subject='admin@example.com'  # 위임받을 사용자
)

API Key 쿼터 초과/제한 우회 전략

상황

Google API는 API Key 단위로 일일 쿼터, 분당 요청 제한이 있음

우회 전략

프로젝트 분할
- GCP 프로젝트를 여러 개 생성 → 각각 API Key 발급
- 로드 밸런싱 방식으로 순차 사용
서버 캐싱
- 동일 요청에 대해 Redis/Memcached 등으로 캐시 적용
- 불필요한 반복 호출 차단
요청 간 rate-limit 조절
- sleep, backoff 로 호출 속도 제어
- 예: 10 req/sec → 3 req/sec로 제한
Premium API 고려
- Custom Search 등 일부 API는 유료 플랜에서 더 높은 쿼터 제공

API Key 오류 감지 시 자동 전환 로직

keys = ['KEY1', 'KEY2', 'KEY3']
for key in keys:
    response = call_google_api(key)
    if not response.is_quota_exceeded():
        break

인증 실패 시 오류 유형 및 대처 방법

오류 코드	의미	원인	대처 방법
`401 Unauthorized`	인증 실패	잘못된 토큰, 만료	access_token 갱신, 재로그인 유도
`403 Forbidden`	권한 없음	scope 미지정, 접근 금지 리소스	OAuth 범위 확인, 서비스 계정 권한 확인
`400 Bad Request`	잘못된 요청	파라미터 누락, 포맷 오류	요청 구조 확인
`429 Too Many Requests`	요청 제한 초과	rate limit 초과	딜레이, API Key 순환
`403 quotaExceeded`	쿼터 초과	일일 사용량 초과	대체 키 사용, GCP 할당량 증가 신청

공통 대처 팁

Google API Response의 error.message, error.code 반드시 로깅
재시도 로직 도입 (exponential backoff 권장)
사용자에게 명확한 에러 메시지 안내

최적화 전략 요약

항목	요약
OAuth 토큰 전략	access/refresh 구분 저장, 자동 갱신 처리, 보안 저장 필수
서비스 계정 위임	관리자 설정 후 subject 사용, 도메인 전체 위임 설정
API Key 쿼터 우회	프로젝트 분산, 캐시, rate limit, 자동 전환 로직
오류 대처	코드별 원인 분석, 재시도 로직, 사용자 메시지 제공

Keywords

OAuth 2.0, 서비스 계정, API 키, 인증 토큰, Google Cloud Console, Access Token, Refresh Token, API 호출, 보안 설정, 쿼터 관리

728x90

'IT Best Practise > Technical' 카테고리의 다른 글

지수 백오프 (Exponential Backoff): 안정적 재시도 전략 (0)	2025.05.15

GilliLab - TechLog