66a99e2733
- 접근 등급(Explorer 등)은 서비스 계정을 가진 Google Cloud 프로젝트에 붙는다 — 토큰 입력 불필요 - developer-token 머리글은 무시되고 다음 큰 버전부터 거부 예정이라 보내지 않음 - CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION·AUTHORIZATION_ERROR 안내 추가, 설정 창 안내 문구·문서 갱신 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
295 lines
18 KiB
Python
295 lines
18 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). 광고가 없던 날은 행이 없을 수 있다.
|
|
- 금액 = cost_micros ÷ 1,000,000 을 원 단위로 반올림(구글 광고 비용은 부가세 별도). 계정 통화가 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
|
|
|
|
# 일자별 표(광고비 탭 구글 머리글) 항목 — 순서 = 열 순서. 클릭률·ROAS 합계는 ad_spend.detail_table 이 이름으로 다시 계산.
|
|
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 승인 상태를 확인하세요.",
|
|
"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) -> int:
|
|
return int((Decimal(int(micros)) / 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"]))
|
|
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_COST: amount,
|
|
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
|