Yahoo広告で運用している広告グループ毎の成果をデータポータルに取り込みたい、そんな広告運用サイドからの要望に答えYahoo!広告APIを使ったレポートの取り込みを実装しました。 当初は簡単にできると想定してたものの、リファレンスを中々読み解くことができずQiitaでの記事見てもでも実装まで数日かかってしまった。せっかくなので実装内容を紹介していきたいと思います。

Yahoo!広告 APIとは

Yahoo!広告 APIは、デベロッパーが開発するアプリケーションとYahoo!広告のシステムを接続して、効率的な広告運用を可能にするAPIです。 以前はYahoo!プロモーション広告APIと呼ばれていましたが追加機能のライフサイクルとセキュリティ機能向上のため変更になりました。

利用開始の手続き

お申し込み手順に従い事前にAPIの利用申請を行います。 https://ads-developers.yahoo.co.jp/developercenter/ja/startup-guide/apply-api-use.html 最大で10営業日ほど発行に時間がかかる場合もありますので、早めに行いましょう。

アプリケーションの登録

Yahoo!広告 API管理ツールにアクセスして、広告運用の権限があるアカウントでログインします。

登録アプリケーションの画面で「登録」ボタンを選択します、ここで権限が足りていない場合ボタンが表示されません。

次に入力項目を埋めて「確認」を選択します、リダイレクトURLは「oob」と入力します。

oobはリダイレクトURIが特に存在しない場合に入力

登録が完了したら「クライアントID」「クライアントシークレット」が表示されますのでメモします。 （広告出稿を操作できるキーになるので外部に漏れないよう注意）

アプリケーションの承認からアクセストークンを取得

ここからが割と実装に詰まっていました、
https://ads-developers.yahoo.co.jp/developercenter/ja/startup-guide/app-approve.html

APIを利用するための全体の流れとして「アプリケーションを承認」→「認可コードを取得」→「アクセストークンの取得」と進めていきます。 この最後のアクセストークンを使って各APIにアクセスできるようになります。

アプリケーションの承認

内部でのみ実装を行う場合、次のURLをつかってアプリケーションの承認を行います。
https://biz-oauth.yahoo.co.jp/oauth/v1/authorize?response_type=code&client_id={クライアントID}&redirect_uri=oob&scope=yahooads&state=hogehoge

URLを開くと承認画面が表示されますので、そのまま承認を行います。 承認後に出てきた「認可コード」はアクセストークン取得のために利用します

認可コードは一度使うと有効期限が切れますので、その場合は「アプリケーションの承認」からやり直しになります。

        $clientId = "hogehoge"; // クライアントID
        $clientSecret = "hogehoge"; // クライアントシークレット
        $code = "hogehoge"; // 認可コード


        $url = "https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=authorization_code"
            . "&client_id={$clientId}"
            . "&client_secret={$clientSecret}"
            . "&redirect_uri=oob"
            . "&code={$code}";


        $curl = curl_init();

        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); 
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);  

        $response = curl_exec($curl);
        $result = json_decode($response, true);
       print_r($result);

この結果に出てくるのが「アクセストークン」と「リフレッシュトークン」です。 「アクセストークン」は発行すると有効期限が1時間で切れてしまいます。そのため都度再発行する必要がありますが、再発行に必要なキーが「リフレッシュトークン」になります。

        $clientId = "hogehoge"; // クライアントID
        $clientSecret = "hogehoge"; // クライアントシークレット
        $refreshToken = "hogehoge"; // リフレッシュトークン

        $url = "https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=refresh_token&client_id={$clientId}&client_secret={$clientSecret}&refresh_token={$refreshToken}";
        $response = $this->get($url); // GET/POSTメソッドは後述
        $accessToken = $response['access_token'] ?? '';

これでアクセストークンを取得することもできバッチ処理などで定期的にAPIへアクセスできるようになりました。

広告レポートの作成

広告レポートを取得するためには事前にAPIからレポートの作成を行わなければいけません。 レポート内容は管理画面と同様に設定できますので既に管理画面でレポートを作成していれば設定内容を合わせる程度の作業になります。

次の例では地域レポートを前日分のみで集計しています。
https://ads-developers.yahoo.co.jp/reference/ads-search-api/

レポートの作成

   $accountId = 0; // 広告のアカウントIDを入力
        $fields = [
            "DAY",
            "CAMPAIGN_NAME",
            "ADGROUP_ID",
            "PREFECTURE",
            "COST",
        ];
        $url = "https://ads-search.yahooapis.jp/api/v2/ReportDefinitionService/add";
        $response = $this->post($url, [
            'accountId' => $accountId,
            'operand' => [
                [
                    'accountId' => $accountId,
                    'reportName' => 'YAHOO_BLOG',
                    'reportType' => 'GEO',
                    'reportDateRangeType' => 'YESTERDAY',
                    'fields' => $fields,
                ]
            ],
        ], $this->getTokenHeader());

       $reports = $response['rval']['values'];
        foreach ($reports as $report) {
            $reportJobId = $report['reportDefinition']['reportJobId'] ?? '';
            $reportJobStatus = $report['reportDefinition']['reportJobStatus'] ?? '';

            echo  $reportJobId; // レポートID

        }

実行後にレポートIDが発行されますので、レポート内容を取得する際にはこれを使用します。

レポートの取得

レポートの取得はレポートIDを使用してCSVのダウンロードを行います。 ただしレポートを発行した直後は時間を置いてダウンロードをする必要があります、次のサンプルは少し雑ですが処理中の場合ダウンロードまで待機するよう処理を実装しています。

レポートの取得

        $accountId = 0;
        while (true) {
            $url = "https://ads-search.yahooapis.jp/api/v2/ReportDefinitionService/get";
            $response = $this->post($url, [
                'accountId' => $accountId,
                'reportJobIds' => [$reportJobId]
            ], $header);
            $report = $response['rval']['values'][0]['reportDefinition'] ?? [];
            $reportJobStatus = $report['reportJobStatus'] ?? '';
            if (in_array($reportJobStatus, [
                'IN_PROGRESS',
                'WAIT',
            ])) {
                $this->info("$reportJobId : $reportJobStatus");
                sleep(5);
                continue;
            }
            //
            $url = "https://ads-search.yahooapis.jp/api/v2/ReportDefinitionService/download";
            $response = $this->post($url, [
                'accountId' => $accountId,
                'reportJobId' => $reportJobId
            ], $header, false);
           break;
     }

これで広告レポートがCSV形式で取得することができました。 Yahoo!広告APIはリファレンスも独特で非常に読みにくいですが、最初の導入部分を乗り越えれば難なく利用できるようになりますね。

記事中に使用されてるget/postメソッドの中身

    public function post($url, $data, $headers = [], $jsonParse = true)
    {
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // 証明書の検証を行わない
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);  // curl_execの結果を文字列で返す
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
        $json = curl_exec($curl);

        if ($jsonParse) {
            return json_decode($json, true);
        }
        return $json;
    }


    public function get($url)
    {
        $curl = curl_init();
        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'GET');
        curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false); // 証明書の検証を行わない
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);  // curl_execの結果を文字列で返す
        $response = curl_exec($curl);
        return json_decode($response, true);
    }

    public function getTokenHeader()
    {
         $clientId = "hogehoge"; // クライアントID
        $clientSecret = "hogehoge"; // クライアントシークレット
        $refreshToken = "hogehoge"; // リフレッシュトークン

        $url = "https://biz-oauth.yahoo.co.jp/oauth/v1/token?grant_type=refresh_token&client_id={$clientId}&client_secret={$clientSecret}&refresh_token={$refreshToken}";
        $response = $this->get($url);
        $accessToken = $response['access_token'] ?? '';

        return [
            "Content-Type: application/json",
            "accept: application/json",
            "Authorization: Bearer $accessToken",
        ];

    }

用語について

用語	概要
アカウントID	アカウントIDは5桁～11桁の数字で構成されています
クライアントID	パートナー企業様のWebサイトやアプリケーションを識別するID パートナー企業様が運営するWebサイトやアプリケーション単位で一つのID登録が必要 ※Yahoo! ID連携 v2では「Client ID」、Yahoo! ID連携 v1では「アプリケーションID」と呼びます
クライアントシークレット	サーバーサイド・アプリケーションとして登録した場合に Client ID（アプリケーションID）と対で発行される共有鍵です。 ユーザーのパスワード同様、開発者はシークレット値を外部に漏れないように安全に管理する必要があります。
認可コード	認可コードを認可サーバーへ渡すことでアクセストークンを取得します。
アクセストークン	Yahoo! JAPANの提供する各種WebAPIにアクセスするためのトークン 通常は1時間の有効期限
リフレッシュトークン	アクセストークンを更新するために利用される可変長トークン 通常長い有効期限が設けられており、アクセストークンの有効期限が切れた際に利用します。

この記事を読んでる人にオススメ