Pinterest APIの使い方と広告実績の取得｜GASで始める日次レポート

/**
 * Pinterest広告の初回取得用サンプル（単発実行）。
 * スプレッドシートに紐づくGASで使用します。
 * スクリプトプロパティ：PINTEREST_ACCESS_TOKEN、PINTEREST_AD_ACCOUNT_ID、
 * PINTEREST_START_DATE、PINTEREST_END_DATE。
 * ads:readを付与したOAuthトークンが必要です。
 * 公式仕様に基づく例。実広告アカウントでの疎通は未実施です。
 */
function importPinterestAdsReport() {
  const properties = PropertiesService.getScriptProperties();
  function requiredProperty(key) {
    const value = (properties.getProperty(key) || '').trim();
    if (!value) throw new Error(key + 'を設定してください。');
    return value;
  }

  const token = requiredProperty('PINTEREST_ACCESS_TOKEN');
  const accountId = requiredProperty('PINTEREST_AD_ACCOUNT_ID');
  const start = requiredProperty('PINTEREST_START_DATE');
  const end = requiredProperty('PINTEREST_END_DATE');
  if (!/^\d+$/.test(accountId)) {
    throw new Error('広告アカウントIDは数字で指定してください。');
  }

  const startMs = pinterestReportDate_(start);
  const endMs = pinterestReportDate_(end);
  const dayMs = 86400000;
  const todayUtc = Math.floor(Date.now() / dayMs) * dayMs;
  if (startMs > endMs || endMs - startMs > 6 * dayMs) {
    throw new Error('この初回取得例では、開始日から終了日までを7日以内にしてください。');
  }
  if (startMs < todayUtc - 89 * dayMs || endMs >= todayUtc) {
    throw new Error('日付はUTCの昨日まで、過去89日以内で指定してください。');
  }

  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  if (!spreadsheet) throw new Error('スプレッドシートからGASを開いてください。');
  const base = 'https://api.pinterest.com/v5/ad_accounts/' + accountId;
  const account = pinterestReportGetJson_(base, token);
  if (!account || typeof account.currency !== 'string' || !/^[A-Z]{3}$/.test(account.currency)) {
    throw new Error('広告アカウントの通貨を確認できませんでした。');
  }

  const parameters = {
    start_date: start,
    end_date: end,
    columns: 'SPEND_IN_MICRO_DOLLAR,PAID_IMPRESSION,OUTBOUND_CLICK_1',
    granularity: 'DAY'
  };
  const query = Object.keys(parameters).map(function (key) {
    return encodeURIComponent(key) + '=' + encodeURIComponent(parameters[key]);
  }).join('&');
  const data = pinterestReportGetJson_(base + '/analytics?' + query, token);
  if (!Array.isArray(data)) throw new Error('広告レポートの応答形式を確認してください。');
  if (data.length === 0) throw new Error('対象期間のデータがありません。期間と配信状況を確認してください。');

  const seenDates = new Set();
  const rows = data.map(function (row) {
    if (!row || String(row.AD_ACCOUNT_ID) !== accountId) {
      throw new Error('応答の広告アカウントIDが一致しません。');
    }
    const dateMs = pinterestReportDate_(row.DATE);
    if (dateMs < startMs || dateMs > endMs || seenDates.has(row.DATE)) {
      throw new Error('応答の日付に範囲外または重複があります。');
    }
    seenDates.add(row.DATE);
    const spend = pinterestReportMetric_(row, 'SPEND_IN_MICRO_DOLLAR');
    return [
      row.DATE, accountId, account.currency,
      spend === '' ? '' : spend / 1000000,
      pinterestReportMetric_(row, 'PAID_IMPRESSION'),
      pinterestReportMetric_(row, 'OUTBOUND_CLICK_1')
    ];
  }).sort(function (a, b) { return a[0].localeCompare(b[0]); });

  // 初回確認用に毎回新しいシートを作ります。既存のシートは変更しません。
  const suffix = Utilities.formatDate(new Date(), 'UTC', 'yyyyMMdd_HHmmss')
    + '_' + Utilities.getUuid().slice(0, 8);
  const sheet = spreadsheet.insertSheet('Pinterest_' + suffix);
  const headers = ['日付（UTC）', '広告アカウントID', '通貨', '広告費', '広告表示回数', '外部クリック（直接）'];
  sheet.getRange(2, 1, rows.length, 3).setNumberFormat('@');
  sheet.getRange(1, 1, rows.length + 1, headers.length).setValues([headers].concat(rows));
  sheet.getRange(2, 4, rows.length, 1).setNumberFormat('#,##0.######');
  sheet.setFrozenRows(1);
  sheet.autoResizeColumns(1, headers.length);
  spreadsheet.toast(rows.length + '日分を新しいシートに出力しました。', 'Pinterest API');
}

function pinterestReportDate_(value) {
  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
    throw new Error('日付はYYYY-MM-DDで指定してください。');
  }
  const milliseconds = Date.parse(value + 'T00:00:00Z');
  if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString().slice(0, 10) !== value) {
    throw new Error('日付が存在しません。');
  }
  return milliseconds;
}

function pinterestReportMetric_(row, key) {
  const value = row[key];
  if (value === undefined || value === null || value === '') return '';
  if ((typeof value !== 'number' && typeof value !== 'string') || String(value).trim() === '') {
    throw new Error('指標の形式を確認してください：' + key);
  }
  const number = Number(value);
  if (!Number.isFinite(number)) throw new Error('数値として読めない指標があります：' + key);
  return number;
}

function pinterestReportGetJson_(url, token) {
  let response;
  try {
    response = UrlFetchApp.fetch(url, {
      method: 'get',
      headers: { Authorization: 'Bearer ' + token },
      muteHttpExceptions: true,
      followRedirects: false
    });
  } catch (error) {
    throw new Error('Pinterest APIに接続できませんでした。接続状況を確認してください。');
  }
  const status = response.getResponseCode();
  if (status < 200 || status >= 300) {
    const explanations = {
      401: 'トークンの有効性を確認してください。',
      403: 'ads:readと広告アカウントへのアクセス権を確認してください。',
      429: '呼び出し上限です。レート制限ヘッダーを確認し、時間をおいて再実行してください。'
    };
    throw new Error('Pinterest API HTTP ' + status + '。'
      + (explanations[status] || '応答状況を確認してから再実行してください。'));
  }
  try {
    return JSON.parse(response.getContentText());
  } catch (error) {
    throw new Error('Pinterest APIの応答をJSONとして読み取れませんでした。');
  }
}