AdWords APIでレポート作成や広告の開始／停止を自動化する

基本的なコードの流れ

　前項まででAPIを利用するための準備が整い、最初のAPIを操作するところまでできました。

　本項では実際にAPIをコールするコードを詳しく見ていきます。例としてキャンペーンの情報を取得するコードをとりあげます。

リスト1　campaign_get.py

from googleads import adwords

def main(client): # （1）
  campaign_service = client.GetService('CampaignService',
   version='v201603') # （2）

  selector = {
      'fields': ['Id', 'Name', 'Status']
  } # （3）
  page = campaign_service.get(selector) #(4)
  print(page)

if __name__ == '__main__':
  adwords_client = adwords.AdWordsClient.LoadFromStorage() # （1'）
  main(adwords_client)

　コードは4つのパートで構成されています。それぞれパート別に確認していきましょう。

（1）オブジェクト（クライアント情報）の生成

　クライアントオブジェクトを生成します。

　実際には（1）クライアントオブジェクトを生成し、メイン関数に引数としてclientを渡しています。（1）ではgoogleads.yamlファイルからIDなど必要情報を読み込んでいます。ファイルパスとして引数無しの場合は（クライアントライブラリの）ホームディレクトリを参照します。

（2）オブジェクト（AdWordsサービス）の生成

　AdWordsサービスのオブジェクトCampaignServiceをインスタンス化しています。

　引数のversionにはAdWords APIのバージョンを定数で指定します。ここでは執筆時点（2016/05/15）での最新のv201603を指定しています。

（3）メソッド実行に必要なデータを作成

　AdWordsサービスオブジェクトに渡すための必要なデータを作成します。今回はgetメソッドに引き渡すセレクタとしてデータを作成しています。

　セレクタでは取得するデータに関する情報を指定します。fieldsではレポートの項目（スプレッドシートでいう列の項目）を指定します。ここでは（Id, Name, Status）を指定しています（それぞれキャンペーンID、キャンペーン名、キャンペーンのステータス）。

（4）メソッド実行

　セレクタをCampaignServiceオブジェクトに渡し、getメソッドで情報取得を実行します。

レポート作成（1）

　前項でAdWords APIのプログラムによる操作手順の大枠がつかめました。

　次は、APIの中でも最も利用機会の多いレポート作成のAPIを見ていきます。

リスト2　criteria_download_report.py

def main(client): # （1）
  report_downloader = client.GetReportDownloader(version='v201603') # （2）

  report = {
      'reportName': 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
      'dateRangeType': 'LAST_7_DAYS',
      'reportType': 'CRITERIA_PERFORMANCE_REPORT',
      'downloadFormat': 'CSV',
      'selector': {
          'fields': ['CampaignId', 'AdGroupId', 'Id', 'CriteriaType',
                     'Criteria', 'FinalUrls', 'Impressions', 'Clicks', 'Cost']
      }
  } # （3）

  report_downloader.DownloadReport(
      report, sys.stdout, skip_report_header=False, skip_column_header=False,
      skip_report_summary=False) #(4)

　コードを実行し、取得したデータをExcelで開くとこのような形になっています。

クライテリアレポート

　レポートデータはCSVとして保存しておくのが便利です。Excelレポートとしてグラフなどで可視化するほか、ストレージにバックアップとして保存し、Amazon Redshiftなどデータウェアハウス経由で他のデータ（アクセス解析やCRM）と統合して高度な分析に用いる、などの方法を活用できます。

　コードは他のAPIと同じく、4つのパートで構成され（1）（2）までは先ほどと同じです。ここではコード後半に注目して解説していきます。

（3）メソッド実行に必要なデータを作成

　レポートダウンロードのメソッドDownloadReportメソッドを利用します。ここではメソッド実行に必要なレポート定義クエリを作成します。

　いくつかの情報を指定しますが、とくに重要なのはReportType、fieldsです。

　ここではReportTypeのどの種類のレポートをよびだすのかを指定します。キャンペーンクライテリアレポートの場合はCRITERIA_PERFORMANCE_REPORTです。

　fieldsは取得したい項目を指定します（先ほどのcampaign_get.pyと同じ）。

　レポート作成のAPIでは、ReportTypeとfieldsを指定することで掲載結果情報をレポートとして取得します。

（4）メソッド実行

　レポート定義クエリreportをダウンローダオブジェクトに渡し、ダウンロード実行します。