i|dZddlZddlmZddlmZddlmZddl m Z ddl m Z e e ZdZgd ZGd d Zy) u Google Ads API 클라이언트 모듈 Usage: from utils.google_ads_client import GoogleAdsClient client = GoogleAdsClient() campaigns = client.list_campaigns() N)Any)GoogleAdsClient)GoogleAdsException) load_env_keys) get_loggerz/home/jay/workspace/.env.keys)zmetrics.impressionszmetrics.clickszmetrics.cost_microsz metrics.ctrzmetrics.average_cpczmetrics.conversionsceZdZdZefdeddfdZedede fdZ dZ de fd Z d+d e dee fd Zd ede fd Z d,dede dede fdZd edede fdZd edefdZ d-d edzd e dee fdZ d,d edede dede f dZdedede fdZdedefdZd+ded e dee fdZdedee dee fdZdededede fdZ d.d ed!ed"ed#eedzd$edzd%edzdee fd&Zded'eed(eed)ede f d*Zy)/ruGoogle Ads API 클라이언트 env_keys_pathreturnNcx||_t|gd}|Dcgc]$}tjj |r#|&}}|rt d|tjd|_tjd|_tjd|_tjd|_ tjd|_ tj|j |j|j|jdd |_ tjd |jy cc}w) u GoogleAdsClient 초기화. Args: env_keys_path: .env.keys 파일 경로 (기본값: /home/jay/workspace/.env.keys) Raises: ValueError: 필수 환경변수가 누락된 경우 )GOOGLE_ADS_DEVELOPER_TOKENGOOGLE_ADS_CLIENT_IDGOOGLE_ADS_CLIENT_SECRETGOOGLE_ADS_REFRESH_TOKENGOOGLE_ADS_CUSTOMER_IDu필수 환경변수 누락: r r rrrT)developer_token client_id client_secret refresh_tokenuse_proto_plusu1GoogleAdsClient 초기화 완료 (customer_id=%s)N)_env_keys_pathrosenvironget ValueError_developer_token _client_id_client_secret_refresh_token _customer_id_GoogleAdsClientload_from_dict_clientloggerinfo)selfr required_keyskmissings H/home/jay/workspace/.worktrees/task-2116-dev1/utils/google_ads_client.py__init__zGoogleAdsClient.__init__&s,m$ ,E2::>>!3D1EE ;G9EF F " +G H**%;< jj)CD jj)CDJJ'?@'66#'#8#8!__!%!4!4!%!4!4"&      GIZIZ[)Fs $D7D7objc t|dr&t|drddlm}||jdSt|dr@|jj Dcic]\}}|j dr||c}}St|Scc}}w) u/SDK proto-plus 객체를 순수 dict로 변환. __class___pbr) MessageToDictT)preserving_proto_field_name__dict___)hasattrgoogle.protobuf.json_formatr/r.r1items startswithdict)r+r/r'vs r)_to_dictzGoogleAdsClient._to_dictTsv 3 $e)< A dK K 3 #%(\\%7%7%9STQcARAqDS SCyTs B 6B c8|jjdS)uGoogleAdsService 반환.GoogleAdsService)r" get_service)r%s r)_get_ga_servicezGoogleAdsClient._get_ga_service`s||''(:;;cd} |j}|j|j|}t|}|siS|d}|j}t |j |j|j|j|j|jjd}tjd|j|S#t$r}tj!d|d}~wwxYw)uo 광고 계정 상태 및 예산 정보를 반환한다. GAQL로 customer 리소스를 조회하여 계정 이름, 통화, 시간대 등을 반환한다. Returns: dict: id, descriptive_name, currency_code, time_zone, auto_tagging_enabled 포함 dict Raises: GoogleAdsException: API 호출 실패 시 a- SELECT customer.id, customer.descriptive_name, customer.currency_code, customer.time_zone, customer.auto_tagging_enabled, customer.status FROM customer LIMIT 1  customer_idqueryr)iddescriptive_name currency_code time_zoneauto_tagging_enabledstatusu,계정 정보 조회 완료 (customer_id=%s)u계정 정보 조회 실패: %sN)r=searchrlistcustomerstrrCrDrErFrGrHnamer#debugrerror) r%rB ga_serviceresponserowsrowrKresultes r)get_account_infoz GoogleAdsClient.get_account_infohs   --/J!((T5F5Fe(TH>D q'C||H(++&$,$=$=!)!7!7%//(0(E(E"//.. F LLGIZIZ [M!  LL:A >  s;C B C C0C++C0limitc 2d|d} |j}|j|j|}g}|D]}|j}|j t |j |j|jj|jj|j|j|jjdtjdt!||S#t"$r}tj%d|d}~wwxYw)ud 캠페인 목록을 반환한다. Args: limit: 최대 반환 개수 (기본값 25) Returns: list[dict]: 캠페인 정보 목록 (id, name, status, advertising_channel_type, start_date, end_date 포함) Raises: GoogleAdsException: API 호출 실패 시 ag SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, campaign.start_date, campaign.end_date, campaign_budget.amount_micros FROM campaign ORDER BY campaign.id LIMIT r@rCrMrHadvertising_channel_type start_dateend_datebudget_amount_microsu%캠페인 목록 조회 완료: %d건u"캠페인 목록 조회 실패: %sN)r=rIrcampaignappendrLrCrMrHr[r\r]campaign_budget amount_microsr#rNlenrrO) r%rWrBrPrQrTrSr_rUs r)list_campaignszGoogleAdsClient.list_campaignss '    --/J!((T5F5Fe(THF << !(++. ( "*//"6"64<4U4U4Z4Z&.&9&9$,$5$5030C0C0Q0Q   LL@#f+ NM!  LL=q A  sC(C11 D:DD campaign_idc2d|d} |j}|j|j|}t|}|st d||d}|j }t |j|j|jj|jj|j|j|jjd}tj!d||S#t"$r} tj%d|| d } ~ wwxYw) u7 단일 캠페인 정보를 반환한다. Args: campaign_id: 캠페인 ID Returns: dict: 캠페인 상세 정보 Raises: GoogleAdsException: API 호출 실패 시 ValueError: 해당 캠페인을 찾을 수 없는 경우 aT SELECT campaign.id, campaign.name, campaign.status, campaign.advertising_channel_type, campaign.start_date, campaign.end_date, campaign_budget.amount_micros FROM campaign WHERE campaign.id = z LIMIT 1 r@u)캠페인을 찾을 수 없습니다: id=rrZu캠페인 조회 완료: id=%su#캠페인 조회 실패 (id=%s): %sN)r=rIrrJrr_rLrCrMrHr[r\r]rarbr#rNrrO) r%rerBrPrQrRrSr_rTrUs r) get_campaignzGoogleAdsClient.get_campaigns  !"- .    --/J!((T5F5Fe(TH>D #L[M!Z[[q'C||H(++& "//..,4,M,M,R,R&11$--(+(;(;(I(IF LL9; GM!  LL> Q O  sC'C00 D9DDrM budget_amountrHc0 |jjd}|jjd}|j}|d|_||_|jj jj|_ |j|j|g}|jdj}|jjd} |jjd} | j} || _|jj j|| _|jj j j"| _|| _d| j(_d| j(_| j/|j| g} | jdj} | j1d d }|| |||d }t2j5d |||S#t6$r}t2j9d |d}~wwxYw)u 새 캠페인을 생성한다. (검색 캠페인 기본값) 예산을 먼저 생성한 뒤 캠페인에 연결한다. Args: name: 캠페인 이름 budget_amount: 일일 예산 (마이크로 단위, 1원 = 1,000,000 micros) status: 초기 상태 (기본값: PAUSED) Returns: dict: 생성된 캠페인 resource_name 및 id 포함 dict Raises: GoogleAdsException: API 호출 실패 시 CampaignBudgetServiceCampaignBudgetOperation_budgetrA operationsrCampaignServiceCampaignOperationT/)rC resource_namerMrHr^u&캠페인 생성 완료: id=%s name=%su캠페인 생성 실패: %sN)r"r<get_typecreaterMrbenumsBudgetDeliveryMethodEnumSTANDARDdelivery_methodmutate_campaign_budgetsrresultsrsCampaignStatusEnumrHAdvertisingChannelTypeEnumSEARCHr[ranetwork_settingstarget_google_searchtarget_search_networkmutate_campaignssplitr#r$rrO)r%rMrhrHbudget_servicebudget_operationbudgetbudget_responsebudget_resource_namecampaign_servicecampaign_operationr_campaign_responsersrerTrUs r)create_campaignzGoogleAdsClient.create_campaigns,+ !\\556MNN#||445NO %,,F!F'*FK#0F %)\\%7%7%P%P%Y%YF ",DD --,-EO$3#:#:1#=#K#K  $||778IJ !%!6!67J!K )00H HM"ll00CCFKHO04 0B0B0]0]0d0dH -';H $=AH % % :>BH % % ; 0 A A --./!B! .55a8FFM'--c226K"!. (5 F KK@+t TM!  LL6 :  sG-G00 H9HHparamsc  |jjd}|jjd}|j}|j |j ||_g}d|vr|d|_|jdd|vr<|jjj|d|_ |jdddl m }|jj|j!||j#|j |g}|j$dj } || |d } t&j)d ||| S#t*$r} t&j-d || d } ~ wwxYw) uC 기존 캠페인을 업데이트한다. Args: campaign_id: 캠페인 ID **params: 업데이트할 필드 (name, status 등) Returns: dict: 업데이트된 resource_name 포함 dict Raises: GoogleAdsException: API 호출 실패 시 rorprMrHrfield_mask_pb2pathsrmrCrsupdated_fieldsu.캠페인 업데이트 완료: id=%s fields=%su)캠페인 업데이트 실패 (id=%s): %sN)r"r<rtupdate campaign_pathrrsrMr`rvr|rHgoogle.protobufr update_maskCopyFrom FieldMaskrr{r#r$rrO) r%rerrrr_field_mask_pathsrrQrsrTrUs r)update_campaignzGoogleAdsClient.update_campaign@sh #||778IJ !%!6!67J!K )00H%5%C%CDDUDUWb%cH "!  &v  ''/6!"&,,"4"4"G"GxHX"Y ''1 6  * * 3 3N4L4LSc4L4d e'88 --./9H%,,Q/==M!!."2F KKH+Wg hM!  LLDkST U  sE E E3E..E3cr |jjd}|jjd}|j|j|}||_|j |j|gtjd|y#t$r}tjd||d}~wwxYw)u  캠페인을 삭제한다 (상태를 REMOVED로 변경). Args: campaign_id: 삭제할 캠페인 ID Returns: bool: 삭제 성공 여부 Raises: GoogleAdsException: API 호출 실패 시 rorprmu(캠페인 삭제 완료 (REMOVED): id=%sTu#캠페인 삭제 실패 (id=%s): %sN) r"r<rtrrremoverr#r$rrO)r%rerrrsrUs r)delete_campaignzGoogleAdsClient.delete_campaignps #||778IJ !%!6!67J!K ,::4;L;LkZM(5  %  - - --./ .  KKBK P!  LL> Q O  B B B6B11B6c pd}|rd|}d|d|d} |j}|j|j|}g}|D]}|j} |j t | j | j| jj| jj| jt |jj |jjdtjdt||S#t$r} tj!d | d } ~ wwxYw) u 광고그룹 목록을 반환한다. Args: campaign_id: 지정 시 해당 캠페인의 광고그룹만 반환. None이면 계정 전체 광고그룹 반환. limit: 최대 반환 개수 (기본값 25) Returns: list[dict]: 광고그룹 정보 목록 (id, name, status, campaign_id, cpc_bid_micros 포함) Raises: GoogleAdsException: API 호출 실패 시 zWHERE campaign.id = a SELECT ad_group.id, ad_group.name, ad_group.status, ad_group.type, ad_group.cpc_bid_micros, campaign.id, campaign.name FROM ad_group z4 ORDER BY ad_group.id LIMIT rYr@)rCrMrHtypecpc_bid_microsre campaign_nameu(광고그룹 목록 조회 완료: %d건u%광고그룹 목록 조회 실패: %sN)r=rIrad_groupr`rLrCrMrHtype_rr_r#rNrcrrO) r%rerW where_clauserBrPrQrTrSagrUs r)list_ad_groupszGoogleAdsClient.list_ad_groupss & 1+?L  N'    --/J!((T5F5Fe(THF \\ !"%%j ""$)).. " *,*;*;'*3< >t?P?PR] ^H !\\//??OOHN&-H #'88 --./9H%,,Q/==M'--c226K"!. *") F KKC[RV WM!  LL91 =  sEE E7E22E7rc * |jjd}|jjd}|j}|j |j ||_g}d|vr|d|_|jdd|vr<|jjj|d|_ |jdd|vr|d|_ |jdddl m}|jj!|j#||j%|j |g }|j&dj } || |d } t(j+d ||| S#t,$r} t(j/d || d } ~ wwxYw)uk 기존 광고그룹을 업데이트한다. Args: ad_group_id: 광고그룹 ID **params: 업데이트할 필드 (name, status, cpc_bid_micros 등) Returns: dict: 업데이트된 resource_name 및 수정 필드 포함 dict Raises: GoogleAdsException: API 호출 실패 시 rrrMrHrrrrrmru1광고그룹 업데이트 완료: id=%s fields=%su,광고그룹 업데이트 실패 (id=%s): %sN)r"r<rtr ad_group_pathrrsrMr`rvrrHrrrrrrrr{r#r$rrO) r%rrrrrrrrQrsrTrUs r)update_ad_groupzGoogleAdsClient.update_ad_groups# #||778HI !%!6!67I!J )00H%5%C%CDDUDUWb%cH "!  &v  ''/6!"&,,"4"4"F"FvhGW"X ''16)*01A*B' ''(89 6  * * 3 3N4L4LSc4L4d e'88 --./9H%,,Q/==M!!."2F KKK[Zj kM!  LLGVW X  sE)E,, F5F  Fcr |jjd}|jjd}|j|j|}||_|j |j|gtjd|y#t$r}tjd||d}~wwxYw)u 광고그룹을 삭제한다 (상태를 REMOVED로 변경). Args: ad_group_id: 삭제할 광고그룹 ID Returns: bool: 삭제 성공 여부 Raises: GoogleAdsException: API 호출 실패 시 rrrmu+광고그룹 삭제 완료 (REMOVED): id=%sTu&광고그룹 삭제 실패 (id=%s): %sN) r"r<rtrrrrr#r$rrO)r%rrrrsrUs r)delete_ad_groupzGoogleAdsClient.delete_ad_group5s #||778HI !%!6!67I!J ,::4;L;LkZM(5  %  - - --./ .  KKE{ S!  LLA;PQ R  rc `d|d|d} |j}|j|j|}g}|D]}|j}|j t |j |jj|jjj|jj|jt |jjdtj!dt#|||S#t$$r} tj'd|| d} ~ wwxYw) us 광고그룹의 키워드 목록을 반환한다. Args: ad_group_id: 광고그룹 ID limit: 최대 반환 개수 (기본값 25) Returns: list[dict]: 키워드 정보 목록 (criterion_id, keyword_text, match_type, status 포함) Raises: GoogleAdsException: API 호출 실패 시 a SELECT ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.status, ad_group_criterion.cpc_bid_micros, ad_group.id FROM ad_group_criterion WHERE ad_group_criterion.type = KEYWORD AND ad_group.id = zH ORDER BY ad_group_criterion.criterion_id LIMIT rYr@) criterion_id keyword_text match_typerHrru6키워드 목록 조회 완료: %d건 (ad_group_id=%s)u3키워드 목록 조회 실패 (ad_group_id=%s): %sN)r=rIrad_group_criterionr`rLrkeywordtextrrMrHrrrCr#rNrcrrO) r%rrWrBrPrQrTrS criterionrUs r) list_keywordszGoogleAdsClient.list_keywordsVs" !"- .'    --/J!((T5F5Fe(THF 22  (+I,B,B(C(1(9(9(>(>&/&7&7&B&B&G&G"+"2"2"7"7*3*B*B'*3< >t?P?PR] ^ J - LL112MN %,, %6 "#'<<#5#5#P#P#X#X  )+F !!&!# g!>/3||/A/A/V/VWe/f !!,#r)/12B/CI,!!), -2JJ --%KHCKBRBRSQ8SFS KKI3v;Xc dMT"  LLGVW X  s*EFF1#FF G#F;;Gkeyword_criterion_idc |jjd}|j|j||}|jj d}|j }||_|jjj||_ ddl m }|jj|jdg|j|j|g} | j dj |||d} t"j%d ||| S#t&$r} t"j)d || d } ~ wwxYw) u 키워드 상태를 업데이트한다. Args: keyword_criterion_id: 키워드 criterion ID ad_group_id: 키워드가 속한 광고그룹 ID status: 변경할 상태 (ENABLED | PAUSED | REMOVED) Returns: dict: 업데이트된 resource_name 포함 dict Raises: GoogleAdsException: API 호출 실패 시 rrrrrHrrm)rsrrrHu?키워드 상태 업데이트 완료: criterion_id=%s status=%su:키워드 상태 업데이트 실패 (criterion_id=%s): %sN)r"r<ad_group_criterion_pathrrtrrsrvrrHrrrrrrr{r#r$rrO) r%rrrHrrsrrrrQrTrUs r)update_keyword_statusz%GoogleAdsClient.update_keyword_statuss;(% )-)A)AB[)\ &6NN!!;0DM --.IJI!((I&3I ##||11LLVTI  6  ! ! * *>+C+C8*+C+U V1JJ --%;KH "*!1!1!!4!B!B 4* F KKQ$  M!  LLL$    sDD D= D88D= entity_id entity_type date_rangemetricssinceuntilc j|t}dj|}|j}|dk(rd} d} d} n'|dk(rd} d} d} n|d k(rd } d } d } ntd |d|r |r d|d|d} nd|} d| d|d| d| d|d| d } |j }|j |j | }g}|D]}|||jj|jj|jj|jj|jj|jj|jjd }|j!|t"j%dt'|||||||S#t($r}t"j+d|||d}~wwxYw)u 광고 성과 리포트를 반환한다. Args: entity_id: 조회할 캠페인/광고그룹/키워드 ID entity_type: 'campaign', 'ad_group', 'keyword' 중 하나 (기본값: 'campaign') date_range: GAQL 날짜 범위 프리셋 (기본값: LAST_7_DAYS). LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH 등 지원. metrics: 조회할 metrics 필드 목록. None이면 기본 metrics 사용. Returns: list[dict]: 성과 리포트 레코드 목록 Raises: ValueError: 지원하지 않는 entity_type인 경우 GoogleAdsException: API 호출 실패 시 Nz, r_z campaign.idz)campaign.id, campaign.name, segments.daterz ad_group.idz6ad_group.id, ad_group.name, campaign.id, segments.dater keyword_viewzad_group_criterion.criterion_idziad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group.id, campaign.id, segments.dateu!지원하지 않는 entity_type: u?. 'campaign', 'ad_group', 'keyword' 중 하나여야 합니다.zsegments.date BETWEEN 'z' AND ''zsegments.date DURING z$ SELECT z, z FROM z WHERE z = z AND z1 ORDER BY segments.date DESC r@) rrdate impressionsclicks cost_microsctr average_cpc conversionsu\인사이트 조회 완료: %d건 (entity_type=%s, id=%s, date_range=%s, since=%s, until=%s)u6인사이트 조회 실패 (entity_type=%s, id=%s): %s)_DEFAULT_INSIGHT_METRICSjoinlowerrr=rIrsegmentsrrrrrrrrr`r#rNrcrrO)r%rrrrrrmetrics_clause entity_lowerresource where_field select_fieldsdate_conditionrBrPrQrTrSrecordrUs r) get_insightszGoogleAdsClient.get_insightss4 ?.G7+"((* : %!H'KGM Z '!H'KTM Y &%H;K:  3K=ADD  U6ugWUG1MN4ZLAN  !-s9+.!"#  " --/J!((T5F5Fe(THF &!*#.LL--#&;;#:#:!kk00#&;;#:#:;;??#&;;#:#:#&;;#:#: * f% & LLnF  M!  LLH    sDF F2F--F2 headlines descriptions final_urlcdt|cxkrdksntdt|ddt|cxkrdksntdt|d |jjd}|jjd }|jj d }|j }|jj jj|_ |j|j||_ |j} | jj|| j } |D]?} |jj d } | | _| j$j| A|D]?} |jj d } | | _| j&j| A|j)|j|g } | j*d j,}|||t|t|d}t.j1d|||S#t2$r}t.j5d||d}~wwxYw)uA 반응형 검색 광고(RSA)를 생성한다. Args: ad_group_id: 광고그룹 ID headlines: 헤드라인 목록 (최소 3개, 최대 15개) descriptions: 설명 목록 (최소 2개, 최대 4개) final_url: 광고 클릭 시 연결할 최종 URL Returns: dict: 생성된 광고 resource_name, ad_group_id 포함 dict Raises: ValueError: 헤드라인 또는 설명 개수가 유효 범위를 벗어난 경우 GoogleAdsException: API 호출 실패 시 u2헤드라인은 3~15개여야 합니다. (현재: u개)u+설명은 2~4개여야 합니다. (현재: rAdGroupAdServiceAdGroupAdOperation AdTextAssetrmr)rsrrheadline_countdescription_countuF반응형 검색 광고 생성 완료: ad_group_id=%s resource_name=%su:반응형 검색 광고 생성 실패 (ad_group_id=%s): %sN)rcrr"r<rtrurvAdGroupAdStatusEnumPAUSEDrHrrrad final_urlsr`responsive_search_adrrrmutate_ad_group_adsr{rsr#r$rrO)r%rrrrrad_group_ad_servicer ad_group_adrrsarassetrQrsrTrUs r)create_responsive_search_adz+GoogleAdsClient.create_responsive_search_ades2.S^)r)QRUV_R`Qaaefg gS&+!+J3|K\J]]abc c, #||778HI "&,,":":;M"N  --.BCI#**K!%!3!3!G!G!N!NK #3#A#A$BSBSU`#aK B MM  +))C! , --m<!  $$U+ ,% / --m<!   ''. / +>> --%;?H%,,Q/==M"/*&"%i.%(%6 F KKX  M!  LLUWbde f  sGH00 I9II))r)Nr )r_ LAST_7_DAYSNNN)__name__ __module__ __qualname____doc___ENV_KEYS_PATHrLr* staticmethodrr7r9r=rVintrJrdrgrrboolrrrrrrrrrr r>r)rr#s(,:(\c(\t(\\ c d  <+$+b0C0d0d000l AAA A  AF.3.#.$.`34D#':4Z:: d :B 444 4  4  4l131#1$1f34B00S0$t*0d00t*0 d 0d9!99 9  9D&'$(  fff f cT! f Tz fTzf dfXHH9H3i H  H  Hr>r)rrtypingrgoogle.ads.googleads.clientrr google.ads.googleads.errorsrutils.env_loaderr utils.loggerrrr#rrrr>r)rsA K:*# H 0JJr>