"""구글 광고(Google Ads API) — 날짜별 광고비·ROAS·보고서 항목. 인증(2026-10-15 사용자: 서비스 계정 Explorer 승인) - 서비스 계정 JSON 키로 OAuth 액세스 토큰(scope adwords)을 받는다 — JWT 를 google-auth 로 서명하고 토큰 교환은 httpx. 서비스 계정 이메일을 구글 광고 계정(또는 관리자 MCC 계정) → 관리 → 액세스 및 보안 → 사용자에 추가해 두어야 한다 (2024-11 부터 도메인 전체 위임 없이 직접 추가 가능). - **개발자 토큰은 2026-09-09 폐지** — API 접근 등급(Explorer 등)은 서비스 계정을 가진 Google Cloud 프로젝트에 붙는다 (Cloud Console → Google Ads API Overview 에서 신청). developer-token 머리글은 지금은 무시되고 다음 큰 버전부터 거부되므로 보내지 않는다(입력칸도 없음, 예전에 저장한 값은 쓰지 않음). - 요청 머리글: Authorization(Bearer) · login-customer-id(MCC 를 거쳐 들어갈 때만). - Explorer 등급은 운영 계정 조회(보고서)가 되고 하루 작업 수 한도가 있다 — 우리는 가져오기 한 번에 요청 1~2개. 조회(REST googleAds:searchStream, GAQL) SELECT customer.currency_code, segments.date, metrics.cost_micros, metrics.impressions, metrics.clicks, metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date BETWEEN 'from' AND 'to' - 날짜는 광고 계정 시간대 기준(한국 계정이면 KST). 광고가 없던 날은 행이 없을 수 있다. - 금액(광고비) = **부가세 포함**(2026-10-15 사용자 요청) = cost_micros ÷ 1,000,000 × 1.1 을 원 단위로 반올림 (구글 광고 비용은 부가세 별도 — 쿠팡 광고비처럼 부가세 포함으로 맞춘다). 계정 통화가 KRW 가 아니면 저장하지 않는다. - ROAS(%) = 전환 가치 ÷ 비용(부가세 별도) × 100 — 구글 광고 화면 "전환 가치/비용"과 같은 값 그대로, 비용이 0 이면 없음. - 나머지 항목(노출수·클릭수·클릭률·전환수·전환 가치)은 광고비 탭 구글 머리글 → 일자별 표. API 버전은 설정 칸(기본 DEFAULT_VERSION) — 구글은 버전을 약 1년 뒤 종료하므로 종료 안내가 오면 설정에서 올린다. """ from __future__ import annotations import json import re import threading import time from datetime import date from decimal import ROUND_HALF_UP, Decimal from typing import Any import httpx from ..adapters.base import AdapterContext, ApiError, AuthFailed, CredentialField, NotConfigured from .base import AdDay, AdSource SCOPE = "https://www.googleapis.com/auth/adwords" API_BASE = "https://googleads.googleapis.com" DEFAULT_VERSION = "v26" # 2026-10 기준 최신(구글 광고 API 는 매월 부 버전·분기마다 새 버전) TOKEN_URI = "https://oauth2.googleapis.com/token" MAX_DAYS = 366 VAT = Decimal("1.1") # 광고비 = 구글 비용 + 부가세 10% # 일자별 표(광고비 탭 구글 머리글) 항목 — 순서 = 열 순서. 클릭률·ROAS 합계는 ad_spend.detail_table 이 이름으로 다시 계산. M_SPEND, M_COST = "광고비(부가세 포함)", "비용(부가세 별도)" M_IMPR, M_CLICKS, M_CTR, M_CONV, M_VALUE, M_ROAS = "노출수", "클릭수", "클릭률(%)", "전환수", "전환 가치", "ROAS(%)" # 구글 오류 코드 → 고칠 곳 안내(오류 문구 뒤에 붙임) _HINTS = { "CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION": "서비스 계정이 속한 Google Cloud 프로젝트에 운영 계정 접근 승인이 없습니다. " "Cloud Console → Google Ads API Overview 에서 그 프로젝트의 Explorer 이상 승인을 확인하세요.", "AUTHORIZATION_ERROR": "API 접근 승인 문제입니다. 서비스 계정이 속한 Cloud 프로젝트의 Google Ads API 승인 상태를 확인하세요.", "INVALID_LOGIN_CUSTOMER_ID": "[로그인 고객 ID(MCC)] 칸 문제입니다. 서비스 계정을 광고 계정에 직접 추가했다면 이 칸을 비우세요" "(칸을 지우고 [연결 테스트] → [저장]). MCC 에 추가했다면 서비스 계정을 추가한 그 MCC 번호여야 하고, " "고객 ID 의 광고 계정이 그 MCC 아래에 있어야 합니다.", "USER_PERMISSION_DENIED": "서비스 계정이 이 광고 계정에 권한이 없습니다. 구글 광고 → 관리 → 액세스 및 보안에 서비스 계정 이메일을 " "사용자로 추가했는지, 관리자(MCC) 계정에 추가했다면 [로그인 고객 ID]에 MCC 번호를 넣었는지 확인하세요.", "CUSTOMER_NOT_ENABLED": "광고 계정이 사용 중지(취소·미완료) 상태입니다.", "NOT_ADS_USER": "서비스 계정이 구글 광고 사용자로 등록돼 있지 않습니다(액세스 및 보안에서 추가).", "INVALID_CUSTOMER_ID": "고객 ID 가 올바르지 않습니다(광고 계정 오른쪽 위 123-456-7890 형태 번호).", "CUSTOMER_NOT_FOUND": "고객 ID 의 광고 계정을 찾을 수 없습니다.", "SERVICE_ACCOUNT_NOT_ALLOWED": "이 계정은 서비스 계정 접근을 허용하지 않습니다.", } _token_lock = threading.Lock() _token_cache: dict[str, tuple[str, float]] = {} # (서비스 계정 이메일, 키 ID) → (액세스 토큰, 만료 시각) def _digits(value: str) -> str: return re.sub(r"[\s\-]", "", value or "") def _http(ctx: AdapterContext) -> httpx.Client: """HTTP 클라이언트 — 테스트가 바꿔 끼운다.""" return httpx.Client(timeout=ctx.timeout_sec) def parse_service_account(raw: str) -> dict[str, Any]: """서비스 계정 JSON 키 → dict. 형식이 틀리면 ValueError(문구에 키 내용을 넣지 않는다).""" try: info = json.loads(raw) except (TypeError, ValueError): raise ValueError("서비스 계정 키가 JSON 형식이 아닙니다(구글 클라우드에서 내려받은 .json 파일 내용을 통째로 붙여 넣으세요).") from None if not isinstance(info, dict) or info.get("type") != "service_account": raise ValueError("서비스 계정 키가 아닙니다(\"type\": \"service_account\" 인 JSON 이어야 합니다).") for k in ("client_email", "private_key"): if not str(info.get(k) or "").strip(): raise ValueError(f"서비스 계정 키에 {k} 가 없습니다.") return info def _won(micros: int, rate: Decimal = Decimal(1)) -> int: """마이크로 단위 금액 × rate → 원(반올림). rate=VAT 면 부가세 포함.""" return int((Decimal(int(micros)) * rate / Decimal(1_000_000)).quantize(Decimal(1), rounding=ROUND_HALF_UP)) def _num(v: Any) -> Decimal: """REST 응답 숫자(int64 는 문자열, double 은 숫자, 0 은 아예 빠짐) → Decimal.""" if v is None or v == "": return Decimal(0) return Decimal(str(v)) def _google_error(resp: httpx.Response) -> tuple[str, str]: """구글 오류 응답 → (오류 코드 이름, 사람이 읽을 문구). searchStream 오류는 배열에 싸여 올 수 있다.""" try: body = resp.json() except ValueError: return "", f"HTTP {resp.status_code}" if isinstance(body, list): body = next((b for b in body if isinstance(b, dict) and b.get("error")), body[0] if body else {}) err = (body or {}).get("error") or {} if isinstance(err, str): # 토큰 교환 오류 {"error": "invalid_grant", "error_description": "..."} return err, str((body or {}).get("error_description") or err) code_name, message = "", str(err.get("message") or f"HTTP {resp.status_code}") for d in err.get("details") or []: for e in (d or {}).get("errors") or []: ec = e.get("errorCode") or {} if ec: code_name = str(next(iter(ec.values()))) if e.get("message"): message = str(e["message"]) break if code_name: break return code_name, message class GoogleAdsSource(AdSource): code = "google" name = "구글 광고" docs_url = "https://developers.google.com/google-ads/api/docs/oauth/service-accounts" note = ("구글 광고 API 로 날짜별 광고비(비용)·ROAS(전환 가치 ÷ 비용)·노출수·클릭수·전환을 가져옵니다. " "준비: ① Google Cloud 서비스 계정 JSON 키(그 Cloud 프로젝트가 Google Ads API Explorer 이상 승인) " "② 구글 광고 → 관리 → 액세스 및 보안 → 사용자에 서비스 계정 이메일 추가(읽기 권한이면 충분). " "개발자 토큰은 2026-09-09 폐지돼 필요 없습니다.") def credential_fields(self) -> list[CredentialField]: return [ CredentialField("customer_id", "고객 ID(광고 계정)", placeholder="123-456-7890", help="광고비를 가져올 광고 계정 번호(구글 광고 화면 오른쪽 위). 하이픈은 있어도 됩니다."), CredentialField("login_customer_id", "로그인 고객 ID(MCC)", required=False, placeholder="비워 두면 광고 계정에 직접 접근", help="서비스 계정을 관리자(MCC) 계정에 추가해 그 아래 광고 계정을 볼 때만 MCC 번호를 넣습니다."), CredentialField("service_account_json", "서비스 계정 키(JSON)", secret=True, multiline=True, help="Google Cloud → IAM → 서비스 계정 → 키 → JSON 으로 받은 파일 내용을 통째로 붙여 넣습니다. " "저장 후에는 화면에 다시 보이지 않습니다."), CredentialField("api_version", "API 버전", required=False, placeholder=DEFAULT_VERSION, help=f"비워 두면 {DEFAULT_VERSION}. 구글이 버전 종료를 알리면 새 버전(예: v27)으로 바꿉니다."), ] def validate_credentials(self, values: dict[str, str]) -> list[str]: errors = super().validate_credentials(values) for key, label in (("customer_id", "고객 ID"), ("login_customer_id", "로그인 고객 ID")): v = (values.get(key) or "").strip() if v and v != "__stored__" and not re.fullmatch(r"\d{10}", _digits(v)): errors.append(f"{label}는 숫자 10자리여야 합니다(예: 123-456-7890).") sa = (values.get("service_account_json") or "").strip() if sa and sa != "__stored__": try: parse_service_account(sa) except ValueError as exc: errors.append(str(exc)) ver = (values.get("api_version") or "").strip() if ver and ver != "__stored__" and not re.fullmatch(r"v\d{2,3}", ver): errors.append("API 버전은 v26 처럼 v 뒤에 숫자로 입력하세요.") return errors # ── 인증 ────────────────────────────────────────────── def _access_token(self, ctx: AdapterContext, client: httpx.Client) -> str: try: info = parse_service_account(ctx.credentials.get("service_account_json")) except ValueError as exc: raise NotConfigured(str(exc)) from None cache_key = f"{info['client_email']}|{info.get('private_key_id', '')}" with _token_lock: hit = _token_cache.get(cache_key) if hit and hit[1] > time.time() + 120: return hit[0] from google.auth import crypt, jwt # noqa: WPS433 — google-auth(requirements) try: signer = crypt.RSASigner.from_service_account_info(info) except Exception: # noqa: BLE001 — 키 내용은 문구에 넣지 않는다 raise AuthFailed("서비스 계정 키의 private_key 를 읽을 수 없습니다(JSON 파일 내용을 그대로 붙여 넣었는지 확인).") from None now = int(time.time()) token_uri = str(info.get("token_uri") or TOKEN_URI) assertion = jwt.encode(signer, {"iss": info["client_email"], "scope": SCOPE, "aud": token_uri, "iat": now, "exp": now + 3600}) try: resp = client.post(token_uri, data={"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion.decode() if isinstance(assertion, bytes) else assertion}) except httpx.HTTPError as exc: raise ApiError(f"구글 인증 서버에 연결하지 못했습니다({type(exc).__name__}).") from None if resp.status_code != 200: name, msg = _google_error(resp) raise AuthFailed(f"서비스 계정 인증 실패({name or resp.status_code}): {msg[:200]} — 키가 삭제·사용 중지되지 않았는지 확인하세요.") body = resp.json() token = str(body.get("access_token") or "") if not token: raise AuthFailed("구글 인증 서버가 액세스 토큰을 주지 않았습니다.") with _token_lock: _token_cache[cache_key] = (token, time.time() + int(body.get("expires_in") or 3600)) return token def _search(self, ctx: AdapterContext, query: str) -> list[dict[str, Any]]: """GAQL 한 번 — searchStream 응답(묶음 배열)의 results 를 이어 붙여 돌려준다.""" self.require_configured(ctx) cid = _digits(ctx.credentials.get("customer_id")) if not re.fullmatch(r"\d{10}", cid): raise NotConfigured("고객 ID 는 숫자 10자리여야 합니다.") version = (ctx.credentials.get("api_version") or "").strip() or DEFAULT_VERSION with _http(ctx) as client: token = self._access_token(ctx, client) headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"} # 개발자 토큰 없음(2026-09-09 폐지) login = _digits(ctx.credentials.get("login_customer_id")) if login: headers["login-customer-id"] = login ctx.progress.check() try: resp = client.post(f"{API_BASE}/{version}/customers/{cid}/googleAds:searchStream", headers=headers, json={"query": query}) except httpx.HTTPError as exc: raise ApiError(f"구글 광고 API 에 연결하지 못했습니다({type(exc).__name__}).") from None if resp.status_code == 404: raise ApiError(f"구글 광고 API 버전 {version} 을(를) 쓸 수 없습니다(종료됐을 수 있음) — 실적 설정에서 API 버전을 최신으로 바꾸세요.") if resp.status_code != 200: name, msg = _google_error(resp) hint = _HINTS.get(name, "") text = f"구글 광고 API 오류({name or resp.status_code}): {msg[:200]}" + (f" — {hint}" if hint else "") raise (AuthFailed if resp.status_code in (401, 403) else ApiError)(text) try: batches = resp.json() except ValueError: raise ApiError("구글 광고 API 응답을 읽을 수 없습니다.") from None if isinstance(batches, dict): batches = [batches] out: list[dict[str, Any]] = [] for b in batches or []: out.extend((b or {}).get("results") or []) return out # ── 연결 테스트 · 가져오기 ───────────────────────────── def test_connection(self, ctx: AdapterContext) -> str: rows = self._search(ctx, "SELECT customer.id, customer.descriptive_name, customer.currency_code, " "customer.time_zone FROM customer LIMIT 1") c = (rows[0].get("customer") if rows else None) or {} currency = c.get("currencyCode") or "?" msg = f"연결됨 — {c.get('descriptiveName') or '광고 계정'} · 통화 {currency} · 시간대 {c.get('timeZone') or '?'}" if currency != "KRW": msg += " (원화 계정이 아니라 광고비를 가져올 수 없습니다)" return msg def fetch_days(self, ctx: AdapterContext, start: date, end: date) -> list[AdDay]: if end < start: start, end = end, start if (end - start).days + 1 > MAX_DAYS: raise ApiError(f"한 번에 {MAX_DAYS}일까지 가져올 수 있습니다.") rows = self._search( ctx, "SELECT customer.currency_code, segments.date, metrics.cost_micros, metrics.impressions, metrics.clicks, " "metrics.conversions, metrics.conversions_value FROM customer " f"WHERE segments.date BETWEEN '{start.isoformat()}' AND '{end.isoformat()}'", ) sums: dict[date, dict[str, Decimal]] = {} for r in rows: cur = ((r.get("customer") or {}).get("currencyCode") or "").upper() if cur and cur != "KRW": raise ApiError(f"광고 계정 통화가 {cur} 입니다 — 원화(KRW) 계정만 광고비로 가져옵니다.") raw_day = (r.get("segments") or {}).get("date") try: day = date.fromisoformat(str(raw_day)) except ValueError: continue m = r.get("metrics") or {} acc = sums.setdefault(day, {"cost": Decimal(0), "impr": Decimal(0), "clicks": Decimal(0), "conv": Decimal(0), "value": Decimal(0)}) acc["cost"] += _num(m.get("costMicros")) acc["impr"] += _num(m.get("impressions")) acc["clicks"] += _num(m.get("clicks")) acc["conv"] += _num(m.get("conversions")) acc["value"] += _num(m.get("conversionsValue")) out: list[AdDay] = [] for day in sorted(sums): a = sums[day] amount = _won(int(a["cost"]), VAT) # 광고비 = 부가세 포함 cost = a["cost"] / Decimal(1_000_000) roas = (a["value"] / cost * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if cost > 0 else None ctr = (a["clicks"] / a["impr"] * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if a["impr"] > 0 else None metrics = { M_SPEND: amount, M_COST: _won(int(a["cost"])), M_IMPR: int(a["impr"]), M_CLICKS: int(a["clicks"]), M_CTR: float(ctr) if ctr is not None else None, M_CONV: float(a["conv"].quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)), M_VALUE: int(a["value"].quantize(Decimal(1), rounding=ROUND_HALF_UP)), M_ROAS: float(roas) if roas is not None else None, } out.append(AdDay(day=day, amount=amount, roas=roas, metrics=metrics)) return out