Google広告の変更履歴をPythonで運用ログ化する実装
広告の数値が急に動いたとき、最初に知りたいのは「誰がいつ何を変えたか」だ。だが管理画面の変更履歴は一覧性が低い。媒体をまたぐと追跡に時間がかかる。実際、tCPAが突然リセットした原因を追うのに半日を溶かした。犯人は深夜に入った入札変更だった。Google広告APIの change_event を使えば、変更履歴を機械的に取り出せる。取り出した履歴は運用ログへそのまま落とせる。この記事のゴールは、最小コードで履歴を取得することだ。あわせて手動変更とツール変更を見分け、台帳やSlackへ残すところまで進める。コピペできる骨格つきで説明する。
なぜ変更履歴を機械でログ化するのか
広告アカウントは複数人・複数ツールが同時に触る。担当者の手動変更、自動化スクリプト、代理店の入稿、AdPilotのような外部ツール。これらが混ざると、数値変動の原因が管理画面からは追いにくい。とくにtCPAやCV最大化の入札は、変更が学習リセットの引き金になる。学習リセットは配信量とCPAを数日ぶらす。だから「いつ・誰が・どのフィールドを・何から何へ」の記録が要る。tCPA学習リセットの条件と防ぐ運用ルールと組み合わせると、リセットの予兆を変更ログ側から検知できる。管理画面の履歴は目視前提で、集計も差分抽出もできない。ここをAPIで機械化する意味は大きい。
change_eventを叩く最小実装
使うのは change_event リソースだ。Google広告のGAQL（クエリ言語）でフィールドを指定して取得する。骨格はこの1行に集約できる。ブックマークして、自分のアカウントIDと期間に書き換えて使ってほしい。
クエリ骨格： SELECT change_event.change_date_time, change_event.change_resource_type, change_event.client_type, change_event.user_email, change_event.changed_fields FROM change_event WHERE change_event.change_date_time DURING LAST_30_DAYS LIMIT 1000
実装手順は次の通り。（1）google-ads ライブラリで GoogleAdsService の search_stream を呼ぶ。（2）上のGAQLを渡す。（3）返る各行から change_date_time と client_type、changed_fields を読む。（4）old_resource と new_resource を比較して変更前後の値を取り出す。（5）CSVかスプレッドシートへ追記する。changed_fields はFieldMask形式で、変わったフィールド名だけが入る。ここを見れば「入札を触ったのか、予算を触ったのか」が一目で分かる。この手順の完全版（認証・ページング・差分整形つき）はnoteの実践ガイドにまとめている。
手動変更とツール変更をclient_typeで見分ける
監査でいちばん効くのが client_type だ。多くの実装で見落とされるが、ここが要になる。値で変更の出所が分かる。GOOGLE_ADS_WEB_CLIENT なら管理画面からの手動操作。GOOGLE_ADS_API_... ならAPI経由。GOOGLE_ADS_SCRIPTS ならスクリプト。GOOGLE_ADS_EDITOR ならエディタからの一括入稿だ。user_email と併せれば「深夜2時に、APIで、入札単価が変わった」まで特定できる。広告の消化異常をSlackに自動通知する実装と同じ要領で、手動変更だけを抽出してSlackへPOSTすれば、想定外の人手介入をその場で拾える。自動化が増えるほど、この出所の切り分けが事故対応の速さを決める。
実装でつまずいた3つの制約
公式ドキュメントを検証しながら実装して、詰まった点が3つある。ここを先に知っておくとエラーで止まらない。
- 期間は直近30日まで： change_date_time のWHERE句は必須で、範囲は過去30日以内に限られる。それより古い履歴はAPIでは取れない。監査ログを残すなら定期取得して自前で蓄積するしかない。
- LIMITは必須で上限1万行： LIMIT句を省くとエラーになる。上限は10000行。超える場合は最後の行のタイムスタンプを控え、その直後から次のクエリを回してページングする。
- 反映に最大3分： 変更が change_event に載るまで最大3分かかる。変更直後に叩くと取りこぼす。取得ジョブは数分の余裕を持たせる。
取得した履歴を運用フローに載せる
取り出して終わりにしない。運用に効かせる形にする。おすすめは日次バッチだ。毎朝 change_event を取得し、前日ぶんの差分をログ台帳へ追記する。そのうえで手動変更・入札変更・予算変更にタグを付ける。数値が動いた日は、この台帳を時系列でCPA・消化と重ねる。すると「何時の変更が効いたか」が数分で見える。原因究明が半日から数分になった、というのが実装後の一番の変化だ。取得ぶんはBigQueryや広告レポート統合基盤へ流し込めば、媒体横断の変更監査にも広がる。共有用の運用ドキュメントやレビュー資料に落とすなら、AIスライド作成ツールで図解化すると早い。
［PR］ 変更ログを報告資料として整えるなら、以下のツールが使える。AIスライド作成ツール「イルシル」を試してみる
まとめ
Google広告の change_event は、変更履歴を機械的に運用ログへ変える一次データ源だ。client_type で出所を切り分け、30日制約とLIMIT必須と3分遅延の3点を押さえれば、原因究明は半日から数分に縮む。まずは上のGAQL骨格を自分のアカウントで1回叩いてみてほしい。そこから日次蓄積へ広げるのが最短だ。
実務でそのまま使いたい人へ
本記事の手法の完全版（実際のコード・テンプレート・つまずき対処つき）は、運営者のnote（note.com/ryo_ai_hack）で公開している。実データに基づく実践ガイドをまとめて読める。
コメント
コメントを投稿