読者が抱える課題
Google Apps Script(GAS)からGemini APIを呼び出して自動化処理を構築する際、単にリクエストを送るだけのコードでは実務運用で問題が発生することがあります。APIキーの直書きによるセキュリティリスク、ネットワークエラーやAPIレートリミット(429エラー)発生時の非考慮、レスポンスのパースエラーによるスクリプト停止など、実務運用に耐えうるエラー処理やセキュリティ設定を考慮した実装が必要です。
この記事で分かること
- スクリプトプロパティを使用したAPIキーの安全な管理方法
-
UrlFetchAppを用いたGemini API(gemini-1.5-flash)へのリクエスト作成手順 - エクスポネンシャルバックオフ(指数関数的バックオフ)を取り入れたリトライ処理の実装
- APIエラー時のハンドリングとステータスコードに応じた分岐処理
前提条件
- Google Cloud Console または Google AI Studio でGemini APIキーを発行済みであること
- Google Apps Scriptの基本的な操作(エディタの開き方、スクリプトプロパティの設定)を理解していること
※ 仕様変更の可能性があるため、実際に開発する際はGoogle AI Studio等の最新の公式ドキュメントを必ず確認してください。
実装手順とコード解説
1. APIキーの設定
ソースコード内にAPIキーをハードコーディングすることは避け、GASの「スクリプトプロパティ」を利用します。
- GASエディタの左メニュー「プロジェクトの設定(歯車マーク)」を開く。
- 「スクリプト プロパティ」の項目で「スクリプト プロパティを追加」をクリック。
- プロパティ名に
GEMINI_API_KEY、値に取得したAPIキーを入力して保存。
2. 実務向け実装コード例
以下のコードは、エラーハンドリングと一時的な通信エラーに対する自動リトライを含めた汎用的な関数例です。
/**
* Gemini APIを呼び出しテキストを生成する関数
* @param {string} prompt - 送信するプロンプト
* @return {string} 生成されたテキスト
*/
function generateContentWithGemini(prompt) {
const apiKey = PropertiesService.getScriptProperties().getProperty('GEMINI_API_KEY');
if (!apiKey) {
throw new Error('APIキーがスクリプトプロパティに設定されていません。');
}
// エンドポイントURL(モデルは用途に応じて変更してください)
const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=${apiKey}`;
const payload = {
contents: [
{
parts: [
{ text: prompt }
]
}
],
generationConfig: {
temperature: 0.7,
maxOutputTokens: 1000
}
};
const options = {
method: 'post',
contentType: 'application/json',
payload: JSON.stringify(payload),
muteHttpExceptions: true // ステータスコードが200以外でも例外を発生させず自前で処理する
};
const maxRetries = 3;
let baseDelayMs = 1000;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = UrlFetchApp.fetch(url, options);
const statusCode = response.getResponseCode();
const responseText = response.getContentText();
if (statusCode === 200) {
const json = JSON.parse(responseText);
if (json.candidates && json.candidates.length > 0 && json.candidates[0].content) {
return json.candidates[0].content.parts[0].text;
} else {
throw new Error('レスポンスの構造が想定と異なります: ' + responseText);
}
}
// レートリミット(429)やサーバーエラー(5xx)の場合はリトライ対象とする
if (statusCode === 429 || (statusCode >= 500 && statusCode < 600)) {
console.warn(`Attempt ${attempt} failed with status ${statusCode}. Retrying...`);
if (attempt === maxRetries) {
throw new Error(`APIエラー: HTTP ${statusCode} - ${responseText}`);
}
// エクスポネンシャルバックオフの待機
Utilities.sleep(baseDelayMs);
baseDelayMs *= 2;
continue;
}
// リトライ対象外の4xxエラーなど
throw new Error(`リクエストエラー: HTTP ${statusCode} - ${responseText}`);
} catch (error) {
if (attempt === maxRetries) {
console.error('Gemini API呼び出し中に例外が発生しました: ' + error.message);
throw error;
}
Utilities.sleep(baseDelayMs);
baseDelayMs *= 2;
}
}
}
/**
* 動作確認用テスト関数
*/
function testGeminiApi() {
try {
const prompt = 'Google Apps Scriptの概要を100文字程度で説明してください。';
const result = generateContentWithGemini(prompt);
Logger.log('【生成結果】\n' + result);
} catch (e) {
Logger.log('【エラー発生】 ' + e.message);
}
}
エラーハンドリングのポイントと注意点
1. muteHttpExceptions: true の使用
UrlFetchApp.fetch はデフォルトでHTTPステータスコードが4xxや5xxの場合にスクリプト全体の実行を停止(例外をスロー)します。muteHttpExceptions: true を指定することで、プログラム側でステータスコードを受け取り、レスポンス内容に応じた適切なリカバリ処理を実行できます。
2. リトライ処理(エクスポネンシャルバックオフ)の導入
API呼び出し時のネットワーク瞬断や、短時間のリクエスト集中による 429 Too Many Requests が発生した場合、即座に失敗させるのではなく、指数関数的に待機時間を延ばして再試行(リトライ)する実装が推奨されます。
3. APIレスポンス構造のチェック
安全な運用のために、JSONパース後のオブジェクト階層(candidates や parts)が存在するか確認してからデータを取り出すように実装してください。プロンプトの内容によっては安全フィルター等によってレスポンス構造が変わる場合があります。
導入時チェックリスト
実務環境へ導入する際は、以下の項目を確認してください。
- APIキーがソースコードではなく「スクリプトプロパティ」に格納されているか
- APIキーが漏洩した場合に速やかに再発行・無効化できる体制があるか
- リクエスト制限(Quota)を超過した場合のエラーハンドリングが考慮されているか
- 大量処理を行う場合、GASの実行時間制限(標準アカウントで6分)に達しない設計になっているか
-
使用するモデル名(例:
gemini-1.5-flashやgemini-1.5-pro)が正しいか
まとめ
GASからGemini APIを利用することで、ドキュメント生成やデータ処理の自動化が容易になります。実務での運用時は、APIキーの管理徹底、muteHttpExceptions を利用したステータスコード制御、およびリトライ処理の組み込みを行うことで、エラーに強いスクリプトを作成することができます。