Yahoo!広告 スクリプト | Developer Center

基本のレポート

更新履歴

2024/08/16　以下を追記
　・出力先のセル指定について
　・レポートのフィルター・並べ替えへのリンク
2024/07/24　目次を追加

スクリプトの概要

Yahoo!広告スクリプトでは、Google スプレッドシートに各種レポートを直接出力することが可能です。
本ページでは、基本的なレポートの取得方法と、取得したレポートをスプレッドシートへ出力する方法について解説します。
フィルタの指定方法については、レポートのフィルター・並べ替えをご覧ください。

ご利用の流れ

１．サンプルコードをコピーしてテキストファイルに保存し、解説を見ながらサンプルコード内の(1)～(6)を書き換えます。
２．こちらの手順のとおり、Google アカウントと連携します。
３．こちらの手順のとおり、１で作ったスクリプトを実行します。

１．検索広告のキャンペーンレポート（今月、フィルタ指定なし）

サンプルコード

function main() {
  const spreadsheetId = 'スプレッドシートID';//...(1)
  const sheetName = 'シート1';//...(2)
  const ss = SpreadsheetApp.openById(spreadsheetId);
  let sh = ss.getSheetByName(sheetName);
  sh.clear();
  const reportData = AdsUtilities.getSearchReport({
    accountId: AdsUtilities.getCurrentAccountId(),// 実行中のアカウントを取得します
    reportType: 'CAMPAIGN', //...(3)
    fields: [
      'ACCOUNT_NAME','CAMPAIGN_NAME','IMPS','CLICKS','COST','CONVERSIONS'//...(4)
    ],
    reportDateRangeType: 'THIS_MONTH',//...(5)
    reportSkipColumnHeader : 'FALSE',//...(6)
  }).reports[0].rows; //戻り値の１つ目のレポート行を取得
  sh.getRange('A1').setValues(reportData);//...(7)
}

解説

(1)出力先のスプレッドシート ID を指定します。
　スプレッドシート ID については、こちらの FAQ をご覧ください。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

(2)出力先のスプレッドシートのシート名を指定します。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

(3)reportTypeでレポート種別を指定します。
　今回の例ではキャンペーンレポートを作成するため、reportType は「CAMPAIGN」を指定しています。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

よく使われる reportType は以下のとおりです。

上記以外に指定できる値の詳細はリファレンスをご覧ください。

(4)fieldsで出力項目を指定します。
　以下２点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと
　・配列なので、項目を,（カンマ）で区切ること

よく使われるfieldsは以下のとおりです。

※レポートごとに使える項目が異なります。それぞれのレポートでどの項目が使えるかは各レポート定義をご確認ください。
CSVファイル内の「フィールド名」列の内容をスクリプトに記載いただくことになります。

(5)reportDateRangeTypeでレポートデータの期間を指定します。
　今回の例では今月分のレポートを作成するためreportDateRangeTypeは「THIS_MONTH（本日を含む当月）」を指定しています。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

よく使われるreportDateRangeTypeは以下のとおりです。

上記以外に指定できる値の詳細はリファレンスをご覧ください。
ユーザー側で任意の日付を指定したい場合は、後述の「応用：期間を自由に指定したい場合」をご覧ください。

(6)reportSkipColumnHeaderでヘッダー行を出力するかどうか設定できます。
　今回はヘッダー行を出力するため「FALSE」です。
　ヘッダー行を出力したくない場合は「TRUE」を指定してください。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

(7)sh.getRange('A1').setValues(reportData);でスプレッドシートのA1セル以降に書き込みます。
「A1」の部分に別のセルを指定することで、任意のセル以降に書き込むことも可能です。
この際、両側の'（シングルクオーテーション）を削除しないようご注意ください。
例）B3セル以降に書き込みたい場合
sh.getRange('B3').setValues(reportData);

２．ディスプレイ広告のキャンペーンレポート（今月、フィルタ指定なし）

サンプルコード

function main(){
  const spreadsheetId = 'スプレッドシートID';//...(1)
  const sheetName = 'シート1';//...(2)
  const ss = SpreadsheetApp.openById(spreadsheetId);
  let sh = ss.getSheetByName(sheetName); 
  sh.clear();
  const reportData = AdsUtilities.getDisplayReport({
    accountId: AdsUtilities.getCurrentAccountId(), 
    fields: [
      'ACCOUNT_NAME','CAMPAIGN_NAME','IMPS','CLICKS','COST','CONVERSIONS'
    ],//...(3)
    reportDateRangeType: 'THIS_MONTH',//...(4)
    reportSkipColumnHeader : 'FALSE',//...(5)
  }).reports[0].rows;
  sh.getRange('A1').setValues(reportData);//...(6)
}

解説

(1)出力先のスプレッドシート ID を指定します。
　スプレッドシート ID については、こちらの FAQ をご覧ください。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

(2)出力先のスプレッドシートのシート名を指定します。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

(3)fieldsで出力項目を指定します。
　以下２点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと
　・配列なので、項目を,（カンマ）で区切ること

よく使われるfieldsは以下のとおりです。

※レポートごとに使える項目が異なります。それぞれのレポートでどの項目が使えるかは各レポート定義をご確認ください。
CSVファイル内の「フィールド名」列の内容をスクリプトに記載いただくことになります。

(4)reportDateRangeTypeでレポートデータの期間を指定します。
　今回の例では今月分のレポートを作成するためreportDateRangeTypeは「THIS_MONTH（本日を含む当月）」を指定しています。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

よく使われるreportDateRangeTypeは以下のとおりです。

上記以外に指定できる値の詳細はリファレンスをご覧ください。
ユーザー側で任意の日付を指定したい場合は、後述の「応用：期間を自由に指定したい場合」をご覧ください。

(5)reportSkipColumnHeaderでヘッダー行を出力するかどうか設定できます。
　今回はヘッダー行を出力するため「FALSE」を指定しています。ヘッダー行を出力したくない場合は「TRUE」を指定してください。
　以下１点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

※ディスプレイ広告では、一部のレポートを除いてreportTypeは指定しません。
　reportTypeを指定しない場合、「fields」で指定した出力項目により、以下の単位のレポートとなります。
　・アカウントレポート
　・キャンペーンレポート
　・広告グループレポート
　・広告レポート
　・リンク先URLレポート
　例）「fields」で「AD_ID（広告ID）を指定した場合、広告レポートとなります。

　reportTypeを指定する必要があるレポートについてはリファレンスをご覧ください。
　reportTypeを指定する場合、以下１点ご注意ください。
　・文字列なので、項目'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

(6)sh.getRange('A1').setValues(reportData);でスプレッドシートのA1セル以降に書き込みます。
「A1」の部分に別のセルを指定することで、任意のセル以降に書き込むことも可能です。
この際、両側の'（シングルクオーテーション）を削除しないようご注意ください。
例）B3セル以降に書き込みたい場合
sh.getRange('B3').setValues(reportData);

応用：期間を自由に指定したい場合

検索広告もディスプレイ広告も共通です。
reportDateRangeTypeに「CUSTOM_DATE」を設定し、dateRangeを以下のように指定します。

reportDateRangeType:'CUSTOM_DATE',
dateRange: {
    startDate: '20230101',//開始日をYYYYMMDD形式で指定
    endDate: '20230228' //終了日をYYYYMMDD形式で指定
},

「１．検索広告のキャンペーンレポート（今月、フィルタ指定なし）」のスクリプトに適用すると以下のようになります。

function main() {
　const spreadsheetId = 'スプレッドシートID';
  const sheetName = 'シート1';
  const ss = SpreadsheetApp.openById(spreadsheetId);
  let sh = ss.getSheetByName(sheetName);
  sh.clear();
  const reportData = AdsUtilities.getSearchReport({
    accountId: AdsUtilities.getCurrentAccountId(),// 実行中のアカウントを取得します
    fields: [
      'ACCOUNT_NAME','CAMPAIGN_NAME','IMPS','CLICKS','COST','CONVERSIONS'
    ], 
    //reportDateRangeType: 'THIS_MONTH',//THIS_MONTH指定は削除する
　　//ここに上記reportDateRangeType、dateRangeを貼り付ける
    reportDateRangeType:'CUSTOM_DATE',
    dateRange: {
        startDate: '20230101',//開始日をYYYYMMDD形式で指定
        endDate: '20230228'//終了日をYYYYMMDD形式で指定
    },
    //ここまで
    reportType: 'CAMPAIGN', 
    reportSkipColumnHeader : 'FALSE',
  }).reports[0].rows; //戻り値の１つ目のレポート行を取得
  sh.getRange('A1').setValues(reportData);//スプレッドシートへの書き込み処理
}