5eaeee2f57
- 광고비 = cost_micros ÷ 10^6 × 1.1 원 반올림(쿠팡 청구금액과 같은 부가세 포함 기준) - ROAS 는 구글 화면 값 그대로(전환 가치 ÷ 부가세 별도 비용), 일자별 표에 광고비(부가세 포함)·비용(부가세 별도) 둘 다 - 설정·광고비 화면 안내와 문서 갱신 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
303 lines
19 KiB
Python
303 lines
19 KiB
Python
"""구글 광고(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
|