はじめに
GoogleAPIで操作履歴を自動取得するロジックを入れたので
YahooAPIでも入れましょうということになりました。
まあGoogleとYahooいつもセットですからね。
片方やればもう片方もやりますよね。うんうん。
6/15にYahoo! JAPAN Ads API Webinarが開催されましたが
資料はこちら
そのときも話が出てましたね。（３４～３７ページ）
履歴機能って結構みんな使ってんだなあ・・・って思いました。
そんなん使ってるのうちくらいなのかと思ってた
YahooAPIの履歴取得には、AuditLogServiceというライブラリを使います。
2020年10月のWebinarで紹介されたそうなので、最近追加された・・・のかな？
リファレンスにどんな情報が来るのか全然記載がないのは何故なんでしょう。。
ほかはすごく親切に教えてくれるのに・・・
[Yahoo検索広告]AuditLogServiceで履歴情報の取得方法
ライブラリを見てみると、３つのメソッドが用意されています。
- get
- downloadの処理状況を取得します。
- addJob
- 操作履歴ファイルをダウンロードするためのジョブを登録します。
- download
- 操作履歴をダウンロードします。
レポート機能を使っている方はピンときますよね！
わざわざgetとdownloadが別々に用意されている。
つまりこのgetでは履歴情報を取れないってことです。
レポート機能と同じ。
ということは、
addJobで取りたい履歴情報の条件を登録
↓
responseとしてjobIDが返される
↓
getでjobIDを参照
↓（ステータスがCOMPLETEDになるまでWAIT）
↓
ダウンロード
でようやくデータ取得できる、アレです。
毎度のことながら時間かかるなあ何とかならんかね。
デバッグで時間かかってストレス。。
ここではポイントだけ上げるので、細かい取り方は割愛します。
細かい取得方法はレポート取得のところを参照してください。
【PHP】Yahoo!広告APIでレポートデータを取得したい！
■2021/6/1-15の履歴情報を取得する場合
１．二段階認証でaccess_tokenを取得してheaderにセット（略）
２．addJobにアクセス
//addJobにアクセス
$addURL = "https://ads-search.yahooapis.jp/api/v5/AuditLogService/addJob";
//API用パラメータ配列
$param_add = [
"accountId" => $accountId,
"operand" => [[
"dateRange" => ["startDate" => $"20210601000000", "endDate" => "20210615235959"], //年月はYYYYMMDDhhmmss
"eventSelector" => [["entityType" => "ALL","eventTypes" => ["ALL"]]], //これ指定しないとCAMPAIGNのADDだけ来る
"encoding" => "UTF8", //これ指定しないとSJISで来る
"sourceType" => "ALL", //これ指定しないとAPIのだけ来る
"lang" => "JA", //これをENにすると英語バージョンで来る
]],
];
でCURL実行。
★レスポンス例：
{
"errors":null,
"rid":"12345123451234512345123451234512",
"rval":{
"values":[
{
"errors":null,
"job":{
"accountId":1234567,
"dateRange":{
"endDate":"20210615235959",
"startDate":"20210601000000"
},
"encoding":"UTF8",
"eventSelector":[],
"jobId":12345678,
"jobName":null,
"jobStatus":"IN_PROGRESS",
"lang":"JA",
"output":"CSV",
"sourceType":"ALL"
},
"operationSucceeded":true
}
]
}
}
３．２で取得したjobIdでgetにアクセス
//getにアクセス
$getURL = "https://ads-search.yahooapis.jp/api/v5/AuditLogService/get";
//API用パラメータ配列
$param_get = [
"accountId" => $accountId,
"jobIds" => [$jobid],
];
でCURL実行。
★レスポンス例：
{
"errors":null,
"rid":"12345123451234512345123451234512",
"rval":{
"totalNumEntries":1,
"values":[
{
"errors":null,
"job":{
"accountId":1234567,
"dateRange":{
"endDate":"20210615235959",
"startDate":"20210601000000"
},
"encoding":"UTF8",
"eventSelector":[],
"jobId":12345678,
"jobName":null,
"jobStatus":"COMPLETED",
"lang":"JA",
"output":"CSV",
"sourceType":"ALL"
},"operationSucceeded":true
}
]
}
}
４．３で取得したjobStatusがCOMPLETEDになったらdownloadにアクセス
//downloadにアクセス
$downloadURL = "https://ads-search.yahooapis.jp/api/v5/AuditLogService/download";
//API用パラメータ配列
$param_dl = [
"accountId" => $accountId,
"jobId" => $jobid,
];
でCURL実行。
レスポンス例：（CSV形式の文字列）
"日時","操作した利用者","ソースタイプ","アカウント名","アカウントID","キャンペーン名","キャンペーンID","広告グループ名","広告グループID","広告名","広告ID","広告タイプ","キーワード","キーワードID","データ自動挿入リストID","ページフィードID","広告表示オプションID","自動入札ID","ターゲットリスト名","ターゲットリストID","ページフィードターゲティングID","コンバージョン設定ID","対象外キーワードリストID","ラベルID","ラベル名","エンティティ","イベントタイプ","項目","更新前","更新後"
"2021/06/03 15:38:53","testuser","広告管理ツール","テストアカウント","1234567","TESTキャンペーン","999999","TEST広告グループ","8888888","","","","追加キーワード","7777777777","","","","","","","","","","","","キーワード","追加","キーワード","","追加キーワード"
上記例だと、
testuserが広告管理ツールを使ってテストアカウントでログインして
TESTキャンペーンのTEST広告グループの
キーワードに「追加キーワード」を追加した
ってことがわかりますね。。
レポート取得の際は最後にjobIDをremoveする処理が入るんだけど、
履歴には必要ないようです。
※英語バージョンの例
"Date","User","Source Type","Account Name","Account ID","Campaign Name","Campaign ID","Ad Group Name","Ad Group ID","Ad Name","Ad ID","Ad Type","Keyword","Keyword ID","Data Assignment List ID","Page Feed ID","Ad Display Option ID","Auto Bidding ID","Target List Name","Target List ID","Page Feed Target ID","Conversion Tracker ID","Negative Keywords List ID","Label ID","Label Name","Entity Type","Event Type","Item","Before","After"
"2021/06/13 10:21:49","dom1482myopic","Yahoo! JAPAN Ads API","テストアカウント","1234567","TESTキャンペーン","999999","TEST広告グループ","8888888","","","","","","","","","","","","","","","","","Ad Groups","Change Ad Group Settings","Target CPA","1000","1800"
GoogleAPIとの違い
先にGoogleAPIでの履歴取得に悪戦苦闘した経験があるので
YahooAPIのほうもすごく警戒して臨んだわけですが、
結論から言うとYahooはGoogleほど複雑じゃないです。
個人的に違うなと感じた部分をリストアップしておきます。
１．履歴情報が日本語で取れる
YahooAPIの大きな特徴は、
これに尽きます。
ヘッダー情報も内容も全部日本語で取れます。
addJobのオプションしていによっては英語バージョンでも取れる。
ただ、GoogleAPIのような生データではなくて、
見せていい情報を選んで並び替えて出してくれてるって感じがしますね。
GoogleAPIが
「渡せるデータは全部そのまま出してやるから、
あとはそっちで勝手にやってちょーだいよ」
って雑な渡し方なのに対して、
YahooAPIは
「データそのままは渡せないけど、見やすく加工してあげたからいいよね！」
って感じ。
まあ差別化って大事だし親切よね。。
ただ、タイプ名とかエンティティとか、データは英語表記で持ってるんだろうし、
わざわざ書き換えてくれなくていいから、英語データだけでいいかなって感じ。
なお、このへんのレポートの出力ロジックは、
次回のAPIアップデート（2021年秋頃予定らしい）で大幅変更らしいので
このステータス変更待つ部分をぜんぶ何とか変えてほしい。
即時取れるようにしてほしい！！！
２．操作履歴は即時反映されるわけではない
GoogleAPIでは操作からAPIデータ取得までに３分程度かかると
リファレンスに記載がありますが、
YahooAPIは１日の中に何回か集計ポイントがあり、集計時点までの操作のみAPIで取得できます。
集計ポイントは非公開なので、いつ反映されるかよくわからない。。
１日に複数回取る場合は傾向を見たほうが良さそうですね。
前日データを取るためには、朝２時までには完了しているとのことで、
２時以降の取得が推奨されています。
３．自動運用ルールはAPIで取得できない（検索広告）
ディスプレイ広告は現状も取得できているようです。
（検索広告の方しか確認していないので詳細は公式ドキュメント参照してください）
今後のリリースで対応予定とのことでした。
４．アカウント以外で履歴情報の絞り込みができない
キャンペーン・広告グループ単位で絞ったデータが欲しかったのですが
現状では絞り込みができないようです。
addJobで条件追加できればいいのになあと動かしながら思いました。
今後のアップデートで対応希望。
不具合かな？と思われる箇所
GoogleAPIでもありましたが、リリースしてそれほど経っていないリソースは
これって仕様？不具合？？と迷う部分がちらほら。
いくつか気になった点を上げておきます。
対応されたり間違いだったりしたら修正します。
１．キャンペーンの設定変更で以下の場合に、["更新後"]が半角スペース(" ")で来る。
・["エンティティ"]=>"キャンペーン" ["イベントタイプ"]=>"キャンペーン設定情報変更"で
["項目"]=> "コンバージョン単価の目標値"
["項目"]=> "入札価格の上限（コンバージョン単価の目標値）"
["項目"]=> "入札価格の下限（コンバージョン単価の目標値）"
["項目"]=> "入札価格の上限（クリック数の最大化）"
["項目"]=> "目標予算（日額）"
["項目"]=> "入札価格の上限（ページ最上部掲載）"
["項目"]=> "目標のインプレッションシェア（ページ最上部掲載）"
["項目"]=> "掲載位置（ページ最上部掲載）"
２．["エンティティ"]=> "キーワード" ["イベントタイプ"]=> "削除"のとき、
・["更新後"]が半角スペース(" ")で来る。
・["項目"]が空("")で来る。
正直いつAPIデータが反映されるかわからないため、操作をして翌日に確認をしたもので
どんな操作をしてこのデータになったのかさっぱり思い出せないわけですが（ダメじゃん）
スペース１文字はないだろうよ！！？と思ったもので備忘録。
今後のアップデートで使い勝手がよくなっていくといいなあと思いました。
気づいたことがあればまた追記します。