GAS で取得する場合の特徴

GAS は、これまでの Python や VBA と実行される場所が違う。この違いが、できることと制約を決める。

観点内容
実行場所Google のサーバー。PC の電源が切れていても、トリガーで定期実行できる
使える手法API 方式だけ。手元のフォルダーにも Git コマンドにも手が届かないので、ローカル方式は使えない
HTTP 通信UrlFetchApp。ライブラリの追加は不要
JSON の解析JavaScript なので JSON.parse がそのまま使える
トークン実質的に必須(下の囲みを参照)
実行時間1回の実行は6分まで

⚠️ GAS ではトークンなしの呼び出しが通りにくい

トークンなしのレート制限(1時間60回)は、送信元の IP アドレスごとに数えられる。GAS のリクエストは Google のサーバーから出ていくため、同じ IP アドレスを世界中の GAS 利用者と共有している。自分は1回しか呼んでいなくても、すでに上限に達していて 403 が返ることが珍しくない。公開リポジトリが対象でも、トークンを設定して使う。

スクリプトを用意する

  1. Google スプレッドシートで新しいファイルを作る
  2. メニューの 「拡張機能」→「Apps Script」 をクリックする。スクリプト エディタが別のタブで開く
  3. 左上のプロジェクト名(「無題のプロジェクト」)をクリックし、GitHub コミット履歴 などの名前を付ける

スプレッドシートから開いたスクリプトは、そのスプレッドシートに結び付いている(コンテナバインド)。SpreadsheetApp.getActiveSpreadsheet() で、元のスプレッドシートを取得できる。

トークンをスクリプト プロパティに保存する

GAS には環境変数がない。代わりに、キーと値の組を保存できる スクリプト プロパティ を使う。

  1. スクリプト エディタの左のメニューで、歯車のアイコン 「プロジェクトの設定」 をクリックする
  2. 下の方にある「スクリプト プロパティ」で 「スクリプト プロパティを追加」 をクリックする
  3. プロパティに GITHUB_TOKEN、値に PART 02 で発行したトークンを入力する
  4. 「スクリプト プロパティを保存」 をクリックする

公開リポジトリだけを読むなら、Repository access を「Public repositories」にした、権限なしのトークンで足りる。コードからは PropertiesService.getScriptProperties().getProperty('GITHUB_TOKEN') で読み出す。

スクリプト全体

エディタに最初からある function myFunction() {} を消して、次のコードを貼り付ける。

JavaScript(Google Apps Script:コード.gs)
/**
 * GitHub REST API でコミット履歴を取得し、スプレッドシートに書き出す。
 * スクリプト プロパティ GITHUB_TOKEN にトークンを設定しておく。
 */
const CONFIG = {
  repo: 'VBA-tools/VBA-JSON',   // 所有者名/リポジトリ名
  branch: '',                   // 空ならデフォルトブランチ
  since: '',                    // 例: '2018-01-01T00:00:00+09:00'(空なら最初のコミットから)
  maxCount: 1000,               // 取得する最大件数
  sheetName: 'コミット履歴',
};
const API_BASE = 'https://api.github.com';
const API_VERSION = '2022-11-28';

/** エントリーポイント:コミット履歴を取得してシートを書き換える */
function fetchCommits() {
  const params = ['per_page=100'];
  if (CONFIG.branch) params.push('sha=' + encodeURIComponent(CONFIG.branch));
  if (CONFIG.since) params.push('since=' + encodeURIComponent(CONFIG.since));
  let url = `${API_BASE}/repos/${CONFIG.repo}/commits?${params.join('&')}`;

  const rows = [];
  while (url && rows.length < CONFIG.maxCount) {
    const res = githubGet_(url);
    for (const c of res.data) {
      rows.push([
        new Date(c.commit.author.date),          // UTC の文字列を日時にする
        c.commit.author.name,
        c.sha.slice(0, 7),
        c.commit.message.split('\n')[0],
        c.html_url,
      ]);
      if (rows.length >= CONFIG.maxCount) break;
    }
    url = res.next;                              // Link ヘッダーの rel="next"
  }

  writeSheet_(['日時', '作者', 'SHA', 'メッセージ', 'URL'], rows);
  console.log(`${rows.length} 件を書き込んだ`);
}

/** 1回のリクエスト:JSON と次のページの URL を返す */
function githubGet_(url) {
  const res = UrlFetchApp.fetch(url, {
    method: 'get',
    headers: githubHeaders_(),
    muteHttpExceptions: true,                    // 4xx・5xx でも例外にせず、自分で判定する
  });
  const code = res.getResponseCode();
  const headers = lowerKeys_(res.getHeaders());

  if (code !== 200) {
    throwGitHubError_(code, headers, res.getContentText());
  }
  return { data: JSON.parse(res.getContentText()), next: nextLink_(headers['link']) };
}

function githubHeaders_() {
  const headers = {
    'Accept': 'application/vnd.github+json',
    'X-GitHub-Api-Version': API_VERSION,
  };
  const token = PropertiesService.getScriptProperties().getProperty('GITHUB_TOKEN');
  if (token) headers['Authorization'] = 'Bearer ' + token;
  return headers;
}

function throwGitHubError_(code, headers, body) {
  if ((code === 403 || code === 429) && headers['x-ratelimit-remaining'] === '0') {
    const reset = new Date(Number(headers['x-ratelimit-reset']) * 1000);
    throw new Error('レート制限に達した。再開できる時刻: ' +
      Utilities.formatDate(reset, 'Asia/Tokyo', 'HH:mm'));
  }
  if (code === 404) {
    throw new Error('404: リポジトリ名が違うか、非公開リポジトリを読む権限がない');
  }
  throw new Error(`HTTP ${code}: ${body.slice(0, 200)}`);
}

/** <https://...&page=2>; rel="next", ... から next の URL を取り出す */
function nextLink_(link) {
  if (!link) return '';
  const m = link.match(/<([^>]+)>;\s*rel="next"/);
  return m ? m[1] : '';
}

/** ヘッダー名を小文字にそろえる(大文字・小文字の違いを吸収する) */
function lowerKeys_(obj) {
  const out = {};
  Object.keys(obj).forEach(k => { out[k.toLowerCase()] = obj[k]; });
  return out;
}

/** シートを書き換える。1列目は日時、2列目以降は文字列として書く */
function writeSheet_(header, rows) {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheet = ss.getSheetByName(CONFIG.sheetName) || ss.insertSheet(CONFIG.sheetName);
  const cols = header.length;
  sheet.clearContents();
  sheet.getRange(1, 1, 1, cols).setValues([header]).setFontWeight('bold');
  sheet.setFrozenRows(1);
  if (rows.length === 0) return;
  sheet.getRange(2, 1, rows.length, 1).setNumberFormat('yyyy-mm-dd hh:mm');
  sheet.getRange(2, 2, rows.length, cols - 1).setNumberFormat('@');   // 書式なしテキスト
  sheet.getRange(2, 1, rows.length, cols).setValues(rows);            // 1回でまとめて書き込む
}

/** スプレッドシートを開いたときにメニューを追加する */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('GitHub')
    .addItem('コミット履歴を取得', 'fetchCommits')
    .addToUi();
}

実行して権限を承認する

  1. エディタ上部の関数の選択欄で fetchCommits を選び、「実行」 をクリックする
  2. 初回は「承認が必要です」と表示される。「権限を確認」 をクリックし、自分のアカウントを選ぶ
  3. 「このアプリは Google で確認されていません」と表示された場合は、「詳細」→「(プロジェクト名)に移動」 をクリックする(自分で作ったスクリプトなので問題ない)
  4. 要求される権限(スプレッドシートの表示と編集、外部サービスへの接続)を確認して 「許可」 をクリックする
  5. 実行ログに「89 件を書き込んだ」と表示され、スプレッドシートに「コミット履歴」シートができる

スプレッドシートを開き直すと、メニューに「GitHub」が追加される。以降は、エディタを開かなくても 「GitHub」→「コミット履歴を取得」 で実行できる。

コードのポイント

muteHttpExceptions を付けて自分で判定する

UrlFetchApp.fetch は、ステータスが 400 番台・500 番台のときに既定で例外を投げる。そのままではレスポンスのヘッダーを読めず、レート制限なのか権限不足なのかを区別できない。muteHttpExceptions: true を指定して例外を止め、ステータスとヘッダーを自分で調べている。

ページネーションは Link ヘッダーをたどる

考え方は PART 03 と同じだ。Link ヘッダーから rel="next" の URL を正規表現で取り出し、なくなるまで繰り返す。getHeaders() が返すヘッダー名は大文字・小文字が一定とは限らないので、lowerKeys_ で小文字にそろえてから参照している。

文字列は「書式なしテキスト」で書く

スプレッドシートも Excel と同じで、12345e6 のような SHA を数値に、= で始まるメッセージを数式に変換してしまう。値を書く前に、2列目以降の表示形式を書式なしテキスト(@)にして防いでいる。

日時は Date オブジェクトで書く

new Date('2019-01-28T16:19:54Z') で UTC の文字列を日時にしてからセルに書くと、スプレッドシートのタイムゾーンで表示される。日本時間になっていないときは、スプレッドシートの 「ファイル」→「設定」 でタイムゾーンを確認する。

書き込みは1回にまとめる

セルを1つずつ setValue で書くと、そのたびにサーバーとの通信が発生して非常に遅くなる。2次元配列にまとめて setValues で一度に書くのが、GAS の基本だ。

トリガーで定期実行する

毎朝自動で更新するには、時間主導型のトリガーを設定する。画面から設定する場合は次のとおりだ。

  1. スクリプト エディタの左のメニューで、時計のアイコン 「トリガー」 をクリックする
  2. 右下の 「トリガーを追加」 をクリックする
  3. 実行する関数に fetchCommits、イベントのソースに「時間主導型」、タイプに「日付ベースのタイマー」、時刻に「午前7時〜8時」を選ぶ
  4. 「保存」 をクリックする

コードで設定することもできる。次の関数を一度だけ実行すると、同じトリガーが作られる。

JavaScript(トリガーの作成)
/** 毎日7時台に fetchCommits を実行するトリガーを作る(一度だけ実行する) */
function createDailyTrigger() {
  ScriptApp.getProjectTriggers()
    .filter(t => t.getHandlerFunction() === 'fetchCommits')
    .forEach(t => ScriptApp.deleteTrigger(t));           // 重複を防ぐ
  ScriptApp.newTrigger('fetchCommits').timeBased().everyDays(1).atHour(7).create();
}

実行される時刻は「7時ちょうど」ではなく、7時台のどこかになる。トリガーは作成した人の権限で動き、失敗したときはその人にメールで通知される。実行の履歴は、左のメニューの「実行数」で確認できる。

💡 毎回全件を取り直してよいか

このスクリプトは、実行のたびにシートを消して全件を書き直す。数百〜数千件なら数回〜数十回のリクエストで済むので、1日1回の実行なら問題ない。数万件の履歴があるリポジトリでは、CONFIG.since で直近の期間だけに絞るか、シートの最新の日時を読んで、それ以降の分だけを追記する形に変える。

発展:GraphQL で変更行数を一度に取る

REST API で変更行数を取るには、コミットの数だけリクエストが必要になる(PART 03)。GAS には6分の実行時間の上限があるので、件数が多いと時間切れになる。ここでは、PART 04 で紹介した GraphQL API を使い、100件分の変更行数を1回のリクエストで取得する。次のコードを同じファイルに追加する。

JavaScript(GraphQL 版:同じファイルに追加する)
const COMMITS_QUERY = `
query($owner: String!, $name: String!, $cursor: String) {
  repository(owner: $owner, name: $name) {
    defaultBranchRef {
      target {
        ... on Commit {
          history(first: 100, after: $cursor) {
            pageInfo { hasNextPage endCursor }
            nodes {
              oid authoredDate messageHeadline url
              additions deletions changedFilesIfAvailable
              author { name }
            }
          }
        }
      }
    }
  }
}`;

/** エントリーポイント:変更行数付きでコミット履歴を取得する(トークン必須) */
function fetchCommitsWithStats() {
  const [owner, name] = CONFIG.repo.split('/');
  const rows = [];
  let cursor = null;
  while (rows.length < CONFIG.maxCount) {
    const data = githubGraphql_(COMMITS_QUERY, { owner: owner, name: name, cursor: cursor });
    const branch = data.repository.defaultBranchRef;
    if (!branch) break;                                   // 空のリポジトリ
    const history = branch.target.history;
    for (const c of history.nodes) {
      rows.push([
        new Date(c.authoredDate), c.author.name, c.oid.slice(0, 7), c.messageHeadline,
        c.changedFilesIfAvailable === null ? '' : String(c.changedFilesIfAvailable),
        String(c.additions), String(c.deletions), c.url,
      ]);
    }
    if (!history.pageInfo.hasNextPage) break;
    cursor = history.pageInfo.endCursor;
  }
  writeSheet_(['日時', '作者', 'SHA', 'メッセージ', 'ファイル数', '追加', '削除', 'URL'],
              rows.slice(0, CONFIG.maxCount));
}

function githubGraphql_(query, variables) {
  const token = PropertiesService.getScriptProperties().getProperty('GITHUB_TOKEN');
  if (!token) throw new Error('GraphQL API にはトークンが必要(スクリプト プロパティ GITHUB_TOKEN)');
  const res = UrlFetchApp.fetch(API_BASE + '/graphql', {
    method: 'post',
    contentType: 'application/json',
    headers: { 'Authorization': 'Bearer ' + token },
    payload: JSON.stringify({ query: query, variables: variables }),
    muteHttpExceptions: true,
  });
  const body = JSON.parse(res.getContentText());
  if (res.getResponseCode() !== 200 || body.errors) {     // GraphQL はエラーでも 200 を返す
    throw new Error('GraphQL エラー: ' + JSON.stringify(body.errors || body).slice(0, 300));
  }
  return body.data;
}

writeSheet_ は2列目以降を文字列として書くので、ファイル数や行数も文字列になっている。スプレッドシート側で合計などの計算に使いたい場合は、writeSheet_ の書式設定を、数値の列だけ除くように変える。

GAS の制約を知っておく

制約内容対処
実行時間1回の実行は6分まで取得する範囲を絞る。変更行数は GraphQL で取る
UrlFetchApp の回数1日あたりの上限がある(無料の Google アカウントで 20,000回、Google Workspace で 100,000回。執筆時点)通常の使い方では届かない。トリガーを短い間隔にしすぎない
トリガーの時刻指定した1時間の範囲のどこかで実行される分単位の正確さが必要な用途には使わない
IP アドレスの共有トークンなしでは、他の利用者の分でレート制限に達していることがあるトークンを設定する

プライベートリポジトリの場合

🔒 この回のスクリプトで変わる点

  • コードの変更は不要。スクリプト プロパティ GITHUB_TOKEN に、対象リポジトリの Contents: Read-only を付けたトークン(PART 02)を設定する
  • スクリプト プロパティは、スクリプトを編集できる人なら誰でも見られる。スプレッドシートに結び付いたスクリプトは、スプレッドシートの編集権限を持つ人が開ける。トークンを入れたスプレッドシートの編集権限は、トークンを見せてよい人だけに絞る。閲覧だけの人には「閲覧者」で共有する
  • トークンは対象のリポジトリだけ・読み取りだけに絞り、有効期限を設定する。期限が切れるとトリガーの実行が 401 で失敗し、メールで通知が届くので、そのときに再発行する
  • 取り込んだシートには非公開の情報が入る。スプレッドシートの共有範囲(「リンクを知っている全員」になっていないか)を確認する

つまずきやすい点

症状原因と対処
「レート制限に達した」と表示されるトークンが設定されていない(プロパティ名の打ち間違いを含む)。GITHUB_TOKEN になっているか確認する
HTTP 401トークンの値が違う、または期限切れ。値の前後に空白が入っていないかも確認する
TypeError: Cannot read properties of null (reading 'getSheetByName')スプレッドシートに結び付いていない単独のスクリプトで実行している。スプレッドシートの「拡張機能」から開いたエディタに貼り付ける
メニューに「GitHub」が出ないonOpen はスプレッドシートを開いたときに動く。保存してからスプレッドシートを再読み込みする
日時が9時間ずれているスプレッドシートのタイムゾーンが日本になっていない。「ファイル」→「設定」で変更する
「起動時間の最大値を超えました」6分の上限。CONFIG.since や maxCount で範囲を絞る

✅ 次の記事では…

PART 09 では、ここまでの手法を一覧で比較し、取得できる項目と絞り込み条件の対応表、エラーの逆引きをまとめる。

→ PART 09 — まとめ:手法の比較と取得できる項目一覧 へ