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 が返ることが珍しくない。公開リポジトリが対象でも、トークンを設定して使う。
スクリプトを用意する
- Google スプレッドシートで新しいファイルを作る
- メニューの 「拡張機能」→「Apps Script」 をクリックする。スクリプト エディタが別のタブで開く
- 左上のプロジェクト名(「無題のプロジェクト」)をクリックし、
GitHub コミット履歴などの名前を付ける
スプレッドシートから開いたスクリプトは、そのスプレッドシートに結び付いている(コンテナバインド)。SpreadsheetApp.getActiveSpreadsheet() で、元のスプレッドシートを取得できる。
トークンをスクリプト プロパティに保存する
GAS には環境変数がない。代わりに、キーと値の組を保存できる スクリプト プロパティ を使う。
- スクリプト エディタの左のメニューで、歯車のアイコン 「プロジェクトの設定」 をクリックする
- 下の方にある「スクリプト プロパティ」で 「スクリプト プロパティを追加」 をクリックする
- プロパティに
GITHUB_TOKEN、値に PART 02 で発行したトークンを入力する - 「スクリプト プロパティを保存」 をクリックする
公開リポジトリだけを読むなら、Repository access を「Public repositories」にした、権限なしのトークンで足りる。コードからは PropertiesService.getScriptProperties().getProperty('GITHUB_TOKEN') で読み出す。
スクリプト全体
エディタに最初からある function myFunction() {} を消して、次のコードを貼り付ける。
/**
* 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();
}実行して権限を承認する
- エディタ上部の関数の選択欄で
fetchCommitsを選び、「実行」 をクリックする - 初回は「承認が必要です」と表示される。「権限を確認」 をクリックし、自分のアカウントを選ぶ
- 「このアプリは Google で確認されていません」と表示された場合は、「詳細」→「(プロジェクト名)に移動」 をクリックする(自分で作ったスクリプトなので問題ない)
- 要求される権限(スプレッドシートの表示と編集、外部サービスへの接続)を確認して 「許可」 をクリックする
- 実行ログに「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 の基本だ。
トリガーで定期実行する
毎朝自動で更新するには、時間主導型のトリガーを設定する。画面から設定する場合は次のとおりだ。
- スクリプト エディタの左のメニューで、時計のアイコン 「トリガー」 をクリックする
- 右下の 「トリガーを追加」 をクリックする
- 実行する関数に
fetchCommits、イベントのソースに「時間主導型」、タイプに「日付ベースのタイマー」、時刻に「午前7時〜8時」を選ぶ - 「保存」 をクリックする
コードで設定することもできる。次の関数を一度だけ実行すると、同じトリガーが作られる。
/** 毎日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回のリクエストで取得する。次のコードを同じファイルに追加する。
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 では、ここまでの手法を一覧で比較し、取得できる項目と絞り込み条件の対応表、エラーの逆引きをまとめる。