1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Google Apps ScriptからGemini APIを呼び出す基本実装とエラーハンドリング手順

1
Posted at

読者が抱える課題

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の「スクリプトプロパティ」を利用します。

  1. GASエディタの左メニュー「プロジェクトの設定(歯車マーク)」を開く。
  2. 「スクリプト プロパティ」の項目で「スクリプト プロパティを追加」をクリック。
  3. プロパティ名に 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 を利用したステータスコード制御、およびリトライ処理の組み込みを行うことで、エラーに強いスクリプトを作成することができます。

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?