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

レポートのフィルター・並べ替え

更新履歴

2024/07/24　目次を追加

スクリプトの概要
ご利用の流れ
サンプルコード
　1．検索広告：インプレッション数が0以上のキーワードレポート（フィルター指定、並べ替えあり）
　2．ディスプレイ広告：インプレッション数が0以上の広告レポート（フィルター指定、並べ替えあり）
解説
応用編：複数フィルターを設定する場合
応用編：複数の並び順を設定する場合

スクリプトの概要

Yahoo!広告スクリプトでは、Google スプレッドシートに各種レポートを直接出力することが可能です。
本ページでは、レポートでのフィルターの指定方法や、並び替えについて解説します。

ご利用の流れ

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

サンプルコード

1．検索広告：インプレッション数が0以上のキーワードレポート（フィルター指定、並べ替えあり）


function main() {
  const SPREAD_SHEET_ID = 'SPREAD_SHEET_ID'; //書き出すスプレッドシートID...（1）
  const SHEET_NAME = 'シート1';//スプレッドシートのシート名...（2）
  const accountId = AdsUtilities.getCurrentAccountId();
  //スプレッドシート
  const ss = SpreadsheetApp.openById(SPREAD_SHEET_ID);
  let sh = ss.getSheetByName(SHEET_NAME);
  sh.clear();//既存行をクリア
  //レポート取得
  const reportData = AdsUtilities.getSearchReport({
    accountId: accountId,
    fields: [
      'MONTH', 'WEEK', 'DAY', 'KEYWORD_DISTRIBUTION_SETTINGS','KEYWORD', 'KEYWORD_MATCH_TYPE', 'CAMPAIGN_NAME', 'IMPS', 'CLICKS', 'COST', 'CONVERSIONS'
    ], // ...（3）
    filters: [
      {
        field: 'IMPS',
        filterOperator: 'GREATER_THAN',
        values: [0] 
      }
    ], //...（4）
    reportDateRangeType: 'LAST_7_DAYS', //...（5）
    reportType: 'KEYWORDS', //...（6）
    reportSkipColumnHeader: 'FALSE', //...（7）
    sortFields: [
      {
        field: "DAY",
        reportSortType: "ASC"
      }
    ] // ...（8）
  }).reports[0].rows;
  //スプレッドシートに出力
  sh.getRange('A1').setValues(reportData);
}

2．ディスプレイ広告：インプレッション数が0以上の広告レポート（フィルター指定、並べ替えあり）


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', 'ADGROUP_NAME', 'AD_NAME', 'AD_TYPE', 'MAIN_MEDIA_FORMAT', 'IMPS', 'CLICKS', 'COST', 'CONVERSIONS'
    ],//...(3)
    filters: [
      {
        field: 'IMPS',
        filterOperator: 'GREATER_THAN',
        values: [0]
      }
    ], //...（4）
    reportDateRangeType: 'THIS_MONTH',//...（5） 
    //...（6）ディスプレイ広告ではレポートタイプの指定は基本ない　※参考：基本のレポート
    reportSkipColumnHeader: 'FALSE',//...（7）
    sortFields: [
      {
        field: "CAMPAIGN_NAME",
        reportSortType: "ASC"
      },
      {
        field: "ADGROUP_NAME",
        reportSortType: "ASC"
      },
      {
        field: "AD_NAME",
        reportSortType: "ASC"
      },
    ] // ...（8）
  }).reports[0].rows;
  sh.getRange('A1').setValues(reportData);
}

解説

（1）～（3）の解説は基本のレポートをご参照ください。

（4） filtersでフィルター内容を指定します。
Filtersは必ず以下のfield（項目）、filterOperator（フィルター条件）、values（値）のセットで指定してください。
フィルターを複数指定する場合は、「複数フィルターを設定する場合」をご参照ください。

① fieldでフィルター対象項目を指定します。
今回の例は、インプレション数のため「IMPS」を指定します。
指定できる項目は、fieldsで指定した項目のみです。
fieldsで指定した項目であれば、管理画面ではフィルター項目として指定できない項目も指定できます。

以下1点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

②filterOperatorでフィルター条件を指定します。
　今回の例では、「以上」のため「GREATER_THAN」を指定します。
　よく使われるfilterOperatorは以下のとおりです。

filterOperator	説明
EQUALS	「項目＝条件の値」のように、指定の値と一致する場合に指定します。
GREATER_THAN	「項目＞条件の値」のように、指定の値を超える場合に指定します。
GREATER_THAN_EQUALS	「項目≧条件の値」のように、指定の値以上の場合に指定します。
LESS_THAN	「項目＜条件の値」のように、指定の値未満の場合に指定します。
LESS_THAN_EQUALS	「項目≦条件の値」のように、指定の値以下の場合に指定します。
IN	Valuesで指定した複数の値のいずれかに一致する場合に指定します。

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

③valuesで条件の値を指定します。
　今回の例では、「0」を指定します。
以下1点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと

※filterOperatorが「IN」の場合は、valuesに複数の値を指定できます。
　例）「キャンペーン名が「Aキャンペーン」「Bキャンペーン」「Cキャンペーン」」というフィルターを指定する場合


filters: [
      {
        field: 'CAMPAIGN_NAME',
        filterOperator: 'IN', 
        values: [
          'Aキャンペーン', 'Bキャンペーン', 'Cキャンペーン'
        ] 
      }
　]

valuesに複数の値を指定する場合、以下2点ご注意ください。
　・文字列なので、項目を'（シングルクオーテーション）または"（ダブルクオーテーション）で囲むこと
　・配列なので、項目を,（コンマ）で区切ること

（5）～（7）の解説は基本のレポートをご参照ください。

（8） sortFieldsで並び替えを指定します。
sortFieldsは必ず以下のfield（項目）、reportSortType（並び順）のセットで指定してください。
並び順を複数指定する場合は、「複数の並び順を設定する場合」をご参照ください。

①fieldで並び替えの項目を指定します。
今回の例では、日付順なので「DAY」を指定します。
指定できる項目は、fieldsで指定した項目のみです。

②reportSortTypeで並び順を指定します。
今回の例では、昇順なので「ASC」を指定します。
降順の場合は「DESC」を指定してください。

応用編：複数フィルターを設定する場合

「IMPS＞0かつ配信設定＝オン」というように、2つ以上フィルターを設定したい場合は、以下のようにfield（項目）、filterOperator（フィルター条件）、values（値）のセットを増やします。
指定できる項目は、fieldsで指定した項目のみです。fieldsで指定していない項目を指定した場合、エラーとなります。


filters: [
      {
        field: 'IMPS',
        filterOperator: 'GREATER_THAN',
        values: [0]
      },
      {
        field: 'KEYWORD_DISTRIBUTION_SETTINGS',
        filterOperator: 'EQUALS',
        values: ['オン']
      }
    ],

正しい例：fieldsにフィルターのfieldが含まれている


function main() {
  const SPREAD_SHEET_ID = 'SPREAD_SHEET_ID'; //書き出すスプレッドシートID
  const SHEET_NAME = 'シート1';//スプレッドシートのシート名
  const accountId = AdsUtilities.getCurrentAccountId();

  //スプレッドシート
  const ss = SpreadsheetApp.openById(SPREAD_SHEET_ID);
  let sh = ss.getSheetByName(SHEET_NAME);
  sh.clear();//既存行をクリア

  //レポート取得
  const reportData = AdsUtilities.getSearchReport({
    accountId: accountId, 
    fields: [
      'MONTH', 'WEEK', 'DAY', 'KEYWORD_DISTRIBUTION_SETTINGS','KEYWORD', 'KEYWORD_MATCH_TYPE', 'CAMPAIGN_NAME', 'IMPS', 'CLICKS', 'COST', 'CONVERSIONS'
    ],
    filters: [
      {
        field: 'IMPS',
        filterOperator: 'GREATER_THAN',
        values: [0]
      },
      {
        field: 'KEYWORD_DISTRIBUTION_SETTINGS',
        filterOperator: 'EQUALS',
        values: ['オン']
      }
    ],
    reportDateRangeType: ' LAST_7_DAYS ', 
    reportType: 'KEYWORDS',
    reportSkipColumnHeader: 'FALSE',
    sortFields: [
      {
        field: "DAY",
        reportSortType: "ASC"
      }
    ] 
  }).reports[0].rows;

  //スプレッドシートに出力
  sh.getRange('A1').setValues(reportData);
}

応用編：複数の並び順を設定する場合

「日付の昇順かつコストの降順」というように、2つ以上並び順を設定したい場合は、以下のようにfield（項目）、reportSortType（並び順）のセットを増やします。
指定できる項目は、fieldsで指定した項目のみです。fieldsで指定していない項目を指定した場合、エラーとなります。


sortFields: [
      {
        field: "DAY",
        reportSortType: "ASC"
      },
      {
        field: "COST",
        reportSortType: "DESC"
      },
    ]

正しい例：fieldsに並び替え順のfieldが含まれている


function main() {
  const SPREAD_SHEET_ID = 'SPREAD_SHEET_ID'; //書き出すスプレッドシートID
  const SHEET_NAME = 'シート1';//スプレッドシートのシート名
  const accountId = AdsUtilities.getCurrentAccountId();

  //スプレッドシート
  const ss = SpreadsheetApp.openById(SPREAD_SHEET_ID);
  let sh = ss.getSheetByName(SHEET_NAME);
  sh.clear();//既存行をクリア

  //レポート取得
  const reportData = AdsUtilities.getSearchReport({
    accountId: accountId,
    fields: [
      'MONTH', 'WEEK', 'DAY', 'KEYWORD_DISTRIBUTION_SETTINGS', 'KEYWORD', 'KEYWORD_MATCH_TYPE', 'CAMPAIGN_NAME', 'IMPS', 'CLICKS', 'COST', 'CONVERSIONS'
    ],
    filters: [
      {
        field: 'IMPS',
        filterOperator: 'GREATER_THAN',
        values: [0]
      }
    ],
    reportDateRangeType: 'ALL_TIME',
    reportType: 'KEYWORDS',
    reportSkipColumnHeader: 'FALSE',
    sortFields: [
      {
        field: "DAY",
        reportSortType: "ASC"
      },
      {
        field: "COST",
        reportSortType: "DESC"//...降順
      },
    ]
  }).reports[0].rows;

  //スプレッドシートに出力
  sh.getRange('A1').setValues(reportData);
}

Developer Center

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