Gemini × Google Workspace Add-ons 開発ガイド — カスタムAIサイドパネルの構築から Marketplace 公開まで

// gemini.gs — Gemini API ユーティリティ
const GEMINI_API_KEY = PropertiesService.getScriptProperties()
  .getProperty('GEMINI_API_KEY');
const GEMINI_ENDPOINT =
  'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent';
 
/**
 * Gemini API にプロンプトを送信し、テキスト応答を返す
 * @param {string} prompt - 入力プロンプト
 * @param {Object} options - オプション設定
 * @returns {string} Gemini の応答テキスト
 */
function callGemini(prompt, options = {}) {
  const payload = {
    contents: [{
      parts: [{ text: prompt }]
    }],
    generationConfig: {
      temperature: options.temperature || 0.7,
      maxOutputTokens: options.maxTokens || 2048,
      topP: options.topP || 0.95
    }
  };
 
  // System Instruction の設定（任意）
  if (options.systemInstruction) {
    payload.systemInstruction = {
      parts: [{ text: options.systemInstruction }]
    };
  }
 
  const response = UrlFetchApp.fetch(
    `${GEMINI_ENDPOINT}?key=${GEMINI_API_KEY}`,
    {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify(payload),
      muteHttpExceptions: true
    }
  );
 
  const json = JSON.parse(response.getContentText());
 
  if (json.error) {
    throw new Error(`Gemini API Error: ${json.error.message}`);
  }
 
  return json.candidates[0].content.parts[0].text;
}
 
/**
 * 構造化出力（JSON）を要求する Gemini 呼び出し
 * @param {string} prompt - 入力プロンプト
 * @param {Object} schema - JSON Schema 定義
 * @returns {Object} パースされた JSON オブジェクト
 */
function callGeminiStructured(prompt, schema) {
  const payload = {
    contents: [{
      parts: [{ text: prompt }]
    }],
    generationConfig: {
      responseMimeType: 'application/json',
      responseSchema: schema,
      temperature: 0.3
    }
  };
 
  const response = UrlFetchApp.fetch(
    `${GEMINI_ENDPOINT}?key=${GEMINI_API_KEY}`,
    {
      method: 'post',
      contentType: 'application/json',
      payload: JSON.stringify(payload),
      muteHttpExceptions: true
    }
  );
 
  const json = JSON.parse(response.getContentText());
  return JSON.parse(json.candidates[0].content.parts[0].text);
}

// gmail-addon.gs — Gmail サイドパネル
function onGmailMessage(e) {
  const messageId = e.gmail.messageId;
  const message = GmailApp.getMessageById(messageId);
  const subject = message.getSubject();
  const body = message.getPlainBody().substring(0, 3000); // トークン節約
  const from = message.getFrom();
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('Gemini AI Assistant')
        .setSubtitle(subject)
        .setImageUrl('https://example.com/gemini-icon.png')
        .setImageStyle(CardService.ImageStyle.CIRCLE)
    );
 
  // 要約セクション
  const summarySection = CardService.newCardSection()
    .setHeader('📋 メール要約')
    .addWidget(
      CardService.newTextParagraph()
        .setText('サイドパネルから AI 分析を実行できます')
    )
    .addWidget(
      CardService.newButtonSet()
        .addButton(
          CardService.newTextButton()
            .setText('要約を生成')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('summarizeEmail')
                .setParameters({
                  messageId: messageId,
                  subject: subject,
                  body: body.substring(0, 1500)
                })
            )
        )
        .addButton(
          CardService.newTextButton()
            .setText('返信ドラフト作成')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('draftReply')
                .setParameters({
                  messageId: messageId,
                  subject: subject,
                  body: body.substring(0, 1500),
                  from: from
                })
            )
        )
    );
 
  // カスタムプロンプトセクション
  const customSection = CardService.newCardSection()
    .setHeader('💬 カスタム質問')
    .addWidget(
      CardService.newTextInput()
        .setFieldName('customPrompt')
        .setTitle('このメールについて質問')
        .setHint('例: このメールの要求事項をリストアップして')
    )
    .addWidget(
      CardService.newTextButton()
        .setText('AI に聞く')
        .setOnClickAction(
          CardService.newAction()
            .setFunctionName('askAboutEmail')
            .setParameters({
              body: body.substring(0, 1500)
            })
        )
    );
 
  card.addSection(summarySection);
  card.addSection(customSection);
 
  return card.build();
}
 
/**
 * メール要約のコールバック
 */
function summarizeEmail(e) {
  const params = e.commonEventObject.parameters;
 
  const summary = callGemini(
    `以下のメールを3行で要約してください。重要なアクションアイテムがあれば箇条書きで追記してください。\n\n件名: ${params.subject}\n\n本文:\n${params.body}`,
    {
      systemInstruction: 'あなたはビジネスメールの分析アシスタントです。簡潔かつ正確に要約してください。',
      temperature: 0.3,
      maxTokens: 512
    }
  );
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('要約結果')
        .setSubtitle(params.subject)
    )
    .addSection(
      CardService.newCardSection()
        .addWidget(
          CardService.newTextParagraph().setText(summary)
        )
        .addWidget(
          CardService.newButtonSet()
            .addButton(
              CardService.newTextButton()
                .setText('← 戻る')
                .setOnClickAction(
                  CardService.newAction()
                    .setFunctionName('onGmailMessage')
                )
            )
        )
    );
 
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(card.build())
    )
    .build();
}
 
/**
 * 返信ドラフト生成のコールバック
 */
function draftReply(e) {
  const params = e.commonEventObject.parameters;
 
  const replyDraft = callGemini(
    `以下のメールへの返信を日本語で作成してください。ビジネスメールとして丁寧かつ簡潔に、具体的な内容を含めてください。\n\n差出人: ${params.from}\n件名: ${params.subject}\n本文:\n${params.body}`,
    {
      systemInstruction: 'あなたはビジネスメール作成のプロフェッショナルです。',
      temperature: 0.5,
      maxTokens: 1024
    }
  );
 
  // Gmail にドラフトを作成
  const message = GmailApp.getMessageById(params.messageId);
  message.getThread().createDraftReply(replyDraft);
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader().setTitle('返信ドラフト作成完了')
    )
    .addSection(
      CardService.newCardSection()
        .addWidget(
          CardService.newTextParagraph()
            .setText('✅ 下書きフォルダにドラフトを保存しました。\n\n' + replyDraft.substring(0, 500) + '...')
        )
    );
 
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(card.build())
    )
    .build();
}

// docs-addon.gs — Google Docs サイドパネル
function onDocsHomepage(e) {
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('Gemini AI Assistant')
        .setSubtitle('ドキュメント分析')
    );
 
  const analysisSection = CardService.newCardSection()
    .setHeader('📝 ドキュメント分析')
    .addWidget(
      CardService.newButtonSet()
        .addButton(
          CardService.newTextButton()
            .setText('文章を校正')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('proofreadDoc')
            )
        )
        .addButton(
          CardService.newTextButton()
            .setText('要約を生成')
            .setOnClickAction(
              CardService.newAction()
                .setFunctionName('summarizeDoc')
            )
        )
    );
 
  const translateSection = CardService.newCardSection()
    .setHeader('🌐 翻訳')
    .addWidget(
      CardService.newSelectionInput()
        .setFieldName('targetLang')
        .setTitle('翻訳先言語')
        .setType(CardService.SelectionInputType.DROPDOWN)
        .addItem('英語', 'en', false)
        .addItem('中国語（簡体字）', 'zh-CN', false)
        .addItem('韓国語', 'ko', false)
        .addItem('フランス語', 'fr', false)
        .addItem('スペイン語', 'es', false)
    )
    .addWidget(
      CardService.newTextButton()
        .setText('選択テキストを翻訳')
        .setOnClickAction(
          CardService.newAction()
            .setFunctionName('translateSelection')
        )
    );
 
  card.addSection(analysisSection);
  card.addSection(translateSection);
 
  return card.build();
}
 
/**
 * ドキュメント校正
 */
function proofreadDoc(e) {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody().getText();
 
  if (!body || body.trim().length === 0) {
    return createErrorCard('ドキュメントが空です。テキストを入力してから再度お試しください。');
  }
 
  // 長いドキュメントは先頭5000文字に制限
  const textToAnalyze = body.substring(0, 5000);
 
  const result = callGeminiStructured(
    `以下の文章を校正してください。誤字脱字、文法ミス、表現の改善点を指摘してください。\n\n${textToAnalyze}`,
    {
      type: 'object',
      properties: {
        corrections: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              original: { type: 'string', description: '元のテキスト' },
              corrected: { type: 'string', description: '修正後のテキスト' },
              reason: { type: 'string', description: '修正理由' }
            },
            required: ['original', 'corrected', 'reason']
          }
        },
        overallScore: { type: 'number', description: '100点満点の文章品質スコア' },
        summary: { type: 'string', description: '全体的な評価コメント' }
      },
      required: ['corrections', 'overallScore', 'summary']
    }
  );
 
  const card = CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle(`校正結果 — ${result.overallScore}点`)
    );
 
  const summarySection = CardService.newCardSection()
    .setHeader('総合評価')
    .addWidget(
      CardService.newTextParagraph().setText(result.summary)
    );
 
  card.addSection(summarySection);
 
  if (result.corrections.length > 0) {
    const correctionsSection = CardService.newCardSection()
      .setHeader(`修正候補（${result.corrections.length}件）`);
 
    result.corrections.slice(0, 10).forEach((c, i) => {
      correctionsSection.addWidget(
        CardService.newDecoratedText()
          .setTopLabel(`#${i + 1} — ${c.reason}`)
          .setText(`❌ ${c.original}\n✅ ${c.corrected}`)
          .setWrapText(true)
      );
    });
 
    card.addSection(correctionsSection);
  }
 
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(card.build())
    )
    .build();
}

# clasp のインストール
npm install -g @google/clasp
 
# Google アカウントでログイン
clasp login
 
# 既存の Apps Script プロジェクトをクローン
clasp clone <SCRIPT_ID>
 
# ローカルで編集後にプッシュ
clasp push
 
# Apps Script エディタをブラウザで開く
clasp open

// error-handler.gs — エラーハンドリングユーティリティ
function createErrorCard(message) {
  return CardService.newActionResponseBuilder()
    .setNavigation(
      CardService.newNavigation().pushCard(
        CardService.newCardBuilder()
          .setHeader(
            CardService.newCardHeader().setTitle('エラーが発生しました')
          )
          .addSection(
            CardService.newCardSection()
              .addWidget(
                CardService.newTextParagraph()
                  .setText(`⚠️ ${message}`)
              )
              .addWidget(
                CardService.newTextButton()
                  .setText('← 戻る')
                  .setOnClickAction(
                    CardService.newAction()
                      .setFunctionName('onHomepage')
                  )
              )
          )
          .build()
      )
    )
    .build();
}
 
/**
 * try-catch ラッパー
 */
function safeExecute(fn) {
  return function(e) {
    try {
      return fn(e);
    } catch (error) {
      console.error(`Add-on error: ${error.message}`, error.stack);
      return createErrorCard(
        `処理中にエラーが発生しました: ${error.message}\n\nしばらく待ってから再度お試しください。`
      );
    }
  };
}

// cache-helper.gs — キャッシュユーティリティ
function cachedGeminiCall(prompt, options, ttlSeconds) {
  const cache = CacheService.getUserCache();
  const cacheKey = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    prompt
  ).map(b => (b < 0 ? b + 256 : b).toString(16).padStart(2, '0')).join('');
 
  const cached = cache.get(cacheKey);
  if (cached) {
    return cached;
  }
 
  const result = callGemini(prompt, options);
  // CacheService の上限は 100KB / 6時間
  cache.put(cacheKey, result, ttlSeconds || 3600);
  return result;
}

// data-sanitizer.gs — データのサニタイズ
function sanitizeForGemini(text) {
  // メールアドレスをマスク
  let sanitized = text.replace(
    /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
    '[EMAIL_MASKED]'
  );
  // 電話番号をマスク（日本の形式）
  sanitized = sanitized.replace(
    /0\d{1,4}-?\d{1,4}-?\d{4}/g,
    '[PHONE_MASKED]'
  );
  // クレジットカード番号パターンをマスク
  sanitized = sanitized.replace(
    /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
    '[CARD_MASKED]'
  );
  return sanitized;
}

// license.gs — ライセンス管理
const LICENSE_API_URL = 'https://your-backend.com/api/license';
 
/**
 * ユーザーのライセンス状態を確認する
 * @returns {Object} ライセンス情報
 */
function checkLicense() {
  const email = Session.getActiveUser().getEmail();
  const cache = CacheService.getUserCache();
  const cacheKey = `license_${email}`;
 
  // キャッシュチェック（5分）
  const cached = cache.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }
 
  try {
    const response = UrlFetchApp.fetch(
      `${LICENSE_API_URL}/check`,
      {
        method: 'post',
        contentType: 'application/json',
        payload: JSON.stringify({ email: email }),
        muteHttpExceptions: true,
        headers: {
          'Authorization': `Bearer ${getServiceToken()}`
        }
      }
    );
 
    const license = JSON.parse(response.getContentText());
    cache.put(cacheKey, JSON.stringify(license), 300);
    return license;
  } catch (error) {
    console.error('License check failed:', error);
    // フォールバック: エラー時は無料プランとして扱う
    return { plan: 'free', features: ['basic'] };
  }
}
 
/**
 * プレミアム機能のゲーティング
 */
function requirePremium(e) {
  const license = checkLicense();
 
  if (license.plan === 'free') {
    return CardService.newActionResponseBuilder()
      .setNavigation(
        CardService.newNavigation().pushCard(
          createUpgradeCard(license)
        )
      )
      .build();
  }
 
  return null; // プレミアムユーザーは通過
}
 
/**
 * アップグレード促進カード
 */
function createUpgradeCard(license) {
  return CardService.newCardBuilder()
    .setHeader(
      CardService.newCardHeader()
        .setTitle('プレミアム機能')
        .setSubtitle('この機能はプレミアムプランで利用できます')
    )
    .addSection(
      CardService.newCardSection()
        .addWidget(
          CardService.newTextParagraph()
            .setText(
              '🔒 この機能にはプレミアムプランが必要です。\n\n' +
              '**プレミアムプランの特典:**\n' +
              '• 無制限のAI分析\n' +
              '• 高度な校正・翻訳機能\n' +
              '• 優先サポート\n\n' +
              '月額 $9.99 / 年額 $99.99'
            )
        )
        .addWidget(
          CardService.newTextButton()
            .setText('プランを確認する')
            .setOpenLink(
              CardService.newOpenLink()
                .setUrl('https://your-site.com/pricing')
                .setOpenAs(CardService.OpenAs.OVERLAY)
            )
        )
    )
    .build();
}

// performance.gs — パフォーマンス最適化
/**
 * 大量テキストを分割して並列風に処理する
 * （Apps Script は真の並列実行不可のため、バッチ化で効率化）
 */
function processLargeDocument(fullText, chunkSize) {
  const chunks = [];
  for (let i = 0; i < fullText.length; i += chunkSize) {
    chunks.push(fullText.substring(i, i + chunkSize));
  }
 
  const results = [];
  const startTime = Date.now();
  const TIME_LIMIT_MS = 300000; // 5分（バッファ1分）
 
  for (const chunk of chunks) {
    if (Date.now() - startTime > TIME_LIMIT_MS) {
      results.push({
        partial: true,
        message: '処理時間制限により、残りの部分は次回に分析します'
      });
      break;
    }
 
    const analysis = callGemini(
      `以下のテキストを分析してください:\n${chunk}`,
      { temperature: 0.3, maxTokens: 1024 }
    );
    results.push({ text: analysis });
  }
 
  return results;
}

// monitoring.gs — 使用量トラッキング
function trackUsage(action, metadata) {
  const email = Session.getActiveUser().getEmail();
  const timestamp = new Date().toISOString();
 
  // Cloud Logging に構造化ログを出力
  console.log(JSON.stringify({
    severity: 'INFO',
    action: action,
    user: Utilities.computeDigest(
      Utilities.DigestAlgorithm.SHA_256,
      email
    ).map(b => (b < 0 ? b + 256 : b).toString(16).padStart(2, '0')).join('').substring(0, 16),
    timestamp: timestamp,
    metadata: metadata
  }));
}