広告データの自動連携が黙って止まる原因と防ぎ方｜トークンの期限・権限の外れ・集計の遅れを管理する

広告データの自動連携は、止まっても知らせてくれないことがあります。取り込みが止まったまま、レポートは古い数字や欠けた数字で出続けます。

BigQueryの広告データを監視するでは、値の異常を毎朝点検する仕組みを紹介しました。ただし値の監視が捕まえるのは、止まった後です。この記事では、止まる前に手を打つ側を扱います。トークンの期限と権限の管理が中心です。

エラーで止まるより、黙って止まるほうが怖い

エラーで止まる連携は、まだ扱いやすい部類です。通知が来れば、その日のうちに直せます。

厄介なのは、処理としては「成功」しているのに、データが入っていない状態です。取得した行が0件でも、処理は正常に終わります。0という値は、正常な値としても現れます。実行の条件を満たさずに動かなかった処理は、失敗として記録されないことがあります。

こうした止まり方は、レポートを見ても気づけません。数字が少し小さく見えるか、ある媒体の行が消えるだけだからです。

自動連携が止まる5つの原因

筆者が運用している取り込みで実際に起きた停止を整理すると、原因は次の5つに分かれました。

1. 認証の期限が来る

いちばん多いのが、アクセストークンや更新トークンの期限切れです。期限は媒体や発行の方法によって違います。

Metaの長期ユーザーアクセストークンは、通常は約60日で期限が切れます。Metaは、この期間が変わる可能性があるとも書いています。バッチ処理にはシステムユーザーのトークンを使うのが一般的ですが、こちらにも60日の期限付きのものがあります。Metaの開発者向けドキュメントは期限付きを推奨しており、ビジネスによっては期限付きしか使えません。期限付きのトークンは、60日以内に更新しなければ使えなくなります。

GoogleのOAuthでは、更新トークンが無効になる条件が公式に挙げられています。主なものは次のとおりです。

• ユーザーがアプリのアクセス権を取り消した
• 更新トークンが6か月間使われていない
• 同じGoogleアカウントとクライアントIDの組み合わせで、更新トークンが上限の100個を超えた
• Google CloudのAPIで、管理者が設定したセッションの継続時間を超えた

見落としやすいのが、OAuth同意画面の設定です。外部ユーザー向けで、公開ステータスが「テスト中」のままだと、更新トークンは7日で期限切れになります。Google Ads APIのドキュメントでも、この7日の失効が「よくある間違い」の1つとして挙げられています。開発中の設定のまま本番の連携を動かすと、毎週止まります。

管理画面にブラウザでログインして取得する連携は、さらに短い期間で切れることがあります。筆者の環境では、Googleアカウントでログインする管理画面の連携が、10日ほどで切れていました。自動で再ログインさせる方法も試しましたが、安定しませんでした。いまは期限の数日前に、担当者へログインし直すよう通知しています。

期限には、もう1つ厄介な性質があります。同じ時期に発行したトークンは、同じ時期に切れます。筆者の環境では、2つの案件のトークンが同じ日に、20分ほどの差で切れました。片方は気づいて対応しましたが、管理の一覧に載っていなかったもう片方は、止まったまま数日放置されました。

2. 権限や割り当てが外れる

トークンが期限内でも、権限が外れれば連携は止まります。

筆者の環境で、毎朝届く日次レポートが、ある日からAPIのエラーで止まりました。トークンの期限には余裕がありました。調べると、トークンに付いているはずの権限（スコープ）の一覧が空になっていました。

原因は、Metaのビジネス設定でした。連携に使うアプリの利用者一覧から、システムユーザーが外れていたのです。割り当てを戻すと、トークンを発行し直さずに、同じトークンのまま復旧しました。なぜ外れたのかは、特定できていません。

権限については、次の点も押さえておきます。

• スコープは発行したときに決まります。期限を延長しても、スコープは引き継がれるだけで増えません。権限を広げるには発行し直します。
• トークンのスコープと、アカウントへの割り当ては別物です。書き込みの操作には、両方が必要です。
• 用途ごとにトークンを分けると、管理の手間が増えます。延長の仕組みが1本しか更新していないと、2本目は誰にも延長されずに切れます。

担当者の異動や退職も、権限が外れる原因になります。Google 広告スクリプトの公式ドキュメントには、次のように書かれています。

スクリプトの元の作成者が、スクリプトの作成元である Google 広告アカウントとの関連付けを解除した場合、スクリプトの実行は停止しますが、引き続き利用できます。

出典：承認 - Google Ads Scripts

Google Apps Scriptのインストール可能なトリガーも「常に作成者のアカウントで実行されます」。BigQuery Data Transfer Serviceの転送も、転送を作成したユーザーの認証情報を使います。転送オーナーのユーザーIDが無効になると、転送は認証のエラーで失敗します。公式ドキュメントでは、認証情報を更新して転送のオーナーを替える方法が案内されています。

つまり、自動の処理の多くは、作った人の権限で動いています。作った人がいなくなる前に、引き継ぎ先を決めておく必要があります。

3. 実行する仕組みそのものが止まる

認証にも権限にも問題がないのに、処理そのものが動かないこともあります。筆者の環境では、次のような例がありました。

• 取り込み用のスクリプトが、管理画面から消えていました。5日分のデータが欠けてから気づきました。消えたことが停止の原因だと考えると整合しますが、なぜ消えたのかは特定できていません。
• パソコンのタスクスケジューラで動かしていた点検が、電源の条件でスキップされていました。既定の設定では、バッテリーで動いている間は実行されません。記録は失敗ではなく「条件を満たさず実行しなかった」になるため、ログを開かないと気づけませんでした。
• スクリプトのタイムゾーンが日本時間ではなく、実行時刻がずれていました。時刻を指定したつもりの処理が、日本時間の夜に動いていました。

どれも、エラーの通知は来ませんでした。動かなかった処理は、失敗を報告しないからです。

4. 媒体の集計が遅れて0が返る

媒体側の集計が終わっていない日は、APIが0を返すことがあります。

筆者が使っているPinterestのAPIでは、直近2日ほどの値が0で返り、数日後に確定した値に置き換わります。厄介なのは、値が空ではなく0で返ることです。配信が止まった日の0と、集計がまだ済んでいない日の0は、値だけでは見分けられません。

逆の誤りもあります。「どうせ集計の遅れだろう」と考えて、本当の停止を見逃すことです。媒体ごとに、何日前までの値なら確定しているかを把握しておきます。広告レポートの数字はいつ確定するのかでも、確定までの日数の考え方を扱っています。

5. 下流の集計が欠けを吸収してしまう

最後は、取り込みの後ろで起きる問題です。複数の媒体を1つにまとめる集計は、1つの媒体が欠けても黙って通ります。

筆者の環境では、ある媒体の取り込みが5日間止まりました。その間、週次のレポートは自動で投稿され続けました。広告費の合計は実際の3分の1ほどの値で、前週比も大きな減少と出ていました。数字は「減った」ように見えるだけで、「止まった」とは読めませんでした。

値の異常を検知する仕組みは入れていましたが、その媒体は監視の対象から漏れていました。監視があっても、何を監視しているかの棚卸しが漏れると、気づけません。

レポート側の作りも影響します。媒体ごとに行を処理する集計では、行が無い媒体はそのまま飛ばされることがあります。エラーにはならず、媒体の欄ごと消えます。

止まる前に手を打つ

ここからは、止まる前に打てる手を紹介します。筆者の環境で、上の停止を受けて実際に入れたものです。

認証情報の台帳を作る

まず、連携に使っている認証情報を一覧にします。項目は次のとおりです。秘密の値そのものは書きません。

• 何の連携に使っているか
• どこに保存しているか（スクリプトのプロパティ、シークレットの管理サービスなど）
• 誰の権限で発行したか
• 期限と、延長や再発行の方法
• 状態の確かめ方
• 最後に確かめた日

台帳は、毎朝自動で点検する形にしています。期限が近いもの、しばらく確かめていないものを挙げて知らせます。

点検では、登録されていることではなく、実際に使えることを確かめます。筆者の環境では、ログイン済みの一覧に表示されているのに、実際には期限が切れているアカウントがありました。トークンを実際に取得してみて、生きているかを判定しています。

台帳を作って気づいたのは、検知よりも、読まれることのほうが難しいという点です。台帳の点検は期限切れを正しく挙げていたのに、結果のファイルを誰も開かず、業務が止まった日がありました。点検の結果は、毎日目に入る場所へ届けます。

期限の延長を自動にし、延長の失敗を知らせる

期限付きのトークンは、期限の前に延長する処理を定期的に回します。Metaの場合は、期限付きのトークンを fb_exchange_token で交換すると、60日を取り直せます。期限が切れてからでは交換できないので、必ず期限内に回します。具体的な実装は、Meta広告・Yahoo!広告のデータをBigQueryに取り込むで紹介しています。

延長の処理も止まることがあります。延長した後に、残りの日数を確かめます。Metaのトークンは debug_token で、期限（expires_at）、有効かどうか（is_valid）、スコープ（scopes）を確かめられます。スコープが空になっていれば、2で紹介した割り当ての外れを疑います。

GoogleのOAuthを使う連携は、同意画面の公開ステータスを確認します。「テスト中」のままなら、本番の運用に入る前に変えておきます。

認証を個人に寄せない

作った人の権限で動く処理は、その人の異動や退職、パスワードの変更で止まります。可能なところは、個人ではない認証に寄せます。Metaならシステムユーザー、Google Cloudならサービスアカウントです。BigQuery Data Transfer Serviceの転送には、サービスアカウントを関連付けることもできます。

個人の権限で動かすしかないものは、台帳に「誰の権限か」を書いておきます。異動の前に、引き継ぎの対象として挙げられるようにするためです。

「動いた」ことを定期的に知らせる

異常があるときだけ通知する仕組みには、弱点があります。「今日は異常がなかった」と「監視そのものが止まっている」が、受け手には区別できません。どちらも、何も届かないからです。

筆者の環境では、監視の処理が動いた記録を残し、週に1回、直近7日の稼働状況を必ず送るようにしました。この報告が届かなければ、監視が止まっています。

稼働の判定は、日付ごとに記録があるかではなく、前回の実行からどれだけ空いたかで行っています。日付で数えると、タイムゾーンや夏時間の切り替えで、毎日動いていても「未実行」と判定されることがあるためです。

媒体ごとに、最後にデータが入った日を見る

合計ではなく、媒体ごとに最後にデータが入った日を出します。1つの媒体が止まっても、その媒体の日付だけが古くなるので、すぐに分かります。

集計の遅れがある媒体は、遅れの日数ぶん、確かめる日をずらします。遅れを吸収せずに毎日確かめると、遅れのたびに通知が鳴り、通知が読まれなくなります。

レポートの側でも、媒体の欄が空のときは、黙って省かずに「データ未着」と表示します。読む人が、減ったのではなく欠けたのだと分かるようにするためです。

止まったときの切り分け

それでも止まったときは、次の順で確かめると早く原因に届きます。

1. 実行の記録を見る：処理が動いたか、動いて失敗したか、そもそも動いていないかを分けます。最後の実行の日時が手がかりになります。
2. 認証の状態を見る：期限、有効かどうか、スコープを確かめます。Metaのエラーコード190は、アクセストークンの期限切れや無効を表します。サブコードで、期限切れ（463）やパスワードの変更（460）などを区別できます。
3. 媒体の管理画面を日別に見る：管理画面に実績があるのに取り込み先が0なら、集計の遅れか取り込みの問題です。管理画面も0なら、配信そのものを確かめます。
4. 下流の集計を見る：取り込み先にデータがあっても、集計のテーブルやレポートが古いことがあります。作り直しの処理が動いたかを確かめます。

復旧では、止まっていた期間を取り直します。多くの取り込みは、直近の数日を毎回取り直す作りになっています。その期間内なら、処理を手で動かすだけで埋まります。それより前は、期間を指定して取り直します。

取り直しの作りにも注意が要ります。筆者の環境では、取得が0件でも、対象の期間の削除だけが実行される作りが見つかりました。APIの取得に失敗した日に、確定済みのデータを消してしまいます。取り直しは、取得に成功してから消して入れる順にします。

取り直した後は、媒体の管理画面の数字と突き合わせます。突き合わせ方は、レポートの数字を検算する手順で紹介しています。

点検のチェックリスト

連携を作ったとき、または見直すときに確かめる項目です。

1. 連携に使う認証情報が、すべて台帳に載っているか
2. 各認証情報の期限と、延長の方法が分かっているか
3. 延長の処理が動いたことを、残りの日数で確かめているか
4. GoogleのOAuth同意画面が「テスト中」のままになっていないか
5. 個人の権限で動いている処理と、その人が分かっているか
6. 監視の対象に、すべての媒体が入っているか
7. 監視が動いたことを、定期的に報告させているか
8. 媒体ごとに、最後にデータが入った日を見ているか
9. 集計の遅れがある媒体の、確定までの日数が分かっているか
10. 取り直しの処理が、取得に失敗した日にデータを消さない作りになっているか

まとめ

広告データの自動連携は、エラーを出さずに止まることがあります。原因は、認証の期限、権限や割り当ての外れ、実行の停止、媒体の集計の遅れ、下流の集計の5つに分けられます。

値の監視は止まった後に捕まえる仕組みです。止まる前に手を打つには、認証情報の台帳を作り、期限の延長を自動にして、その結果を確かめます。あわせて、監視そのものが動いていることを定期的に知らせる仕組みを置きます。媒体ごとに最後にデータが入った日を見れば、1つの媒体の停止も合計に埋もれません。

関連記事

• BigQueryの広告データを監視する｜欠測・ゼロ・急変をGASで毎朝検知する
• Meta広告・Yahoo!広告のデータをBigQueryに取り込む｜API×GASで自動連携を実装する
• Google広告のデータをBigQueryに自動転送する｜Data Transfer Serviceの設定ガイド
• Google Apps Scriptで広告運用を自動化する｜GASの基本からレポート・アラートの実装まで
• 広告レポートの数字はいつ確定するのか｜仮値と確定値を分けて読む
• レポートの数字を検算する手順｜提出前に確かめる4つの基本と、合わなくても正しいケース