• API Key 관리 기능:

  • PropertiesService를 사용하여 'Gemini_API_Key'를 안전하게 스크립트 속성에 저장, 읽기, 삭제하는 함수(saveApiKey, deleteApiKey)를 구현합니다.

  • API 키를 입력받고 관리하는 전용 사이드바(showApiKeySidebar)를 HtmlService로 생성합니다.

• 전역 변수 설정:

  • 활성 문서와 본문(doc, body)을 참조하는 전역 변수를 선언합니다.

2. 텍스트 및 표 생성 (Gemini 사이드바)

• 메인 사이드바 (showGeminiSidebar) 구현:

  • 프롬프트 입력 영역, 이미지 파일 업로드(input type="file") 영역, Gemini 모델 선택(gemini-2.0-flash-exp, gemini-1.5-pro-002), 출력 형식 선택(텍스트, 표) 드롭다운을 포함하는 HtmlService 기반의 사이드바를 만듭니다.

  • 이미지 업로드 시 미리보기가 가능해야 합니다.

• Gemini API 호출 함수 (GEMINI, GEMINI_WITH_IMAGE) 구현:

  • 주어진 프롬프트, 모델 이름, API 키를 사용하여 Google의 Generative Language API(URL: https://generativelanguage.googleapis.com/v1beta/models/...:generateContent)를 호출합니다.

  • GEMINI_WITH_IMAGE 함수는 Base64 인코딩된 이미지 데이터를 받아 멀티모달 입력(텍스트 + 이미지)을 처리할 수 있어야 합니다. MIME 타입은 image/jpeg로 설정합니다.

  • 응답은 한국어로 요청하며, 응답 텍스트를 반환합니다.

• 문서 삽입 기능 구현:

  • generateGeminiContent 함수에서 API 결과를 받아 문서에 삽입합니다.

  • 결과가 '텍스트' 형식일 경우, 마크다운(헤더, 볼드, 이탤릭, 목록)을 Google Docs 서식으로 변환하여 커서 위치에 삽입하는 함수(insertMarkdownToDoc 및 관련 유틸리티 함수)를 구현합니다.

  • 결과가 '표' 형식일 경우, 마크다운 테이블 문자열을 파싱하여 Google Docs 표(DocumentApp.Table) 객체로 변환하여 삽입하는 함수(formatMarkdownTable, insertFormattedTable)를 구현합니다.

3. 이미지 생성 기능 (Gemini 이미지 생성 사이드바)

• 이미지 생성 사이드바 (showGeminiImageGenerationSidebar) 구현:

  • 이미지 프롬프트 입력 영역과 종횡비(aspectRatio) 선택 드롭다운(1:1, 3:4, 4:3, 9:16, 16:9)을 포함하는 사이드바를 구현합니다.

  • API 키가 없으면 경고 후 API Key 관리 사이드바를 열도록 합니다.

• 이미지 생성 API 호출 함수 (generateGeminiImage) 구현:

  • 모델 이름은 gemini-2.0-flash-exp-image-generation을 사용합니다.

  • 종횡비 선택에 따라 이미지의 width와 height를 계산하여 프롬프트에 추가합니다.

    • 예: 1:1 → 512x512, 3:4 → 384x512, 4:3 → 512x384, 9:16 → 288x512, 16:9 → 512x288

  • API 응답에서 Base64 인코딩된 이미지 데이터를 추출하여 전역 변수 (generatedImageData)에 저장하고, 미리보기용 데이터 URL 배열을 클라이언트(HTML)로 반환합니다.

• 클립보드 복사 지원 및 문서 삽입:

  • 클라이언트 측(HTML/JavaScript)에서 데이터 URL을 사용하여 이미지를 미리 보여주고, "클립보드에 복사" 버튼을 제공합니다.

  • 클립보드 복사 시도 실패를 대비하여, 대체 복사 방법 (fallbackCopyMethod)으로 Google Apps Script의 saveImageForClipboard 함수를 호출하여 Base64 데이터를 문서에 임시 삽입하고 사용자에게 수동 복사를 안내하는 기능이 필요합니다.

  • (선택적) 생성된 이미지를 문서에 직접 삽입하는 서버 함수 (insertGeneratedImageToDoc)도 구현합니다.

4. 메뉴 구성

• 문서가 열릴 때(onOpen) 'Gemini'라는 이름의 커스텀 메뉴를 생성하고, 다음 항목들을 추가합니다:

  • Gemini 사이드바 열기 (showGeminiSidebar 호출)

  • 이미지 생성 (showGeminiImageGenerationSidebar 호출)

  • API Key 관리 (showApiKeySidebar 호출)

참고: Utilities.newBlob, Utilities.base64Decode, UrlFetchApp.fetch 등 Google Apps Script 내장 서비스를 활용해야 합니다. 클라이언트-서버 통신은 google.script.run을 사용합니다.

• API Key 관리 기능:

  • PropertiesService를 사용하여 'Gemini_API_Key'를 안전하게 스크립트 속성에 저장, 읽기, 삭제하는 함수(saveApiKey, deleteApiKey)를 구현합니다.

  • API 키를 입력받고 관리하는 전용 사이드바(showApiKeySidebar)를 HtmlService로 생성합니다. 사이드바는 API 키가 이미 저장되어 있으면 수정 및 삭제 버튼을, 없으면 저장 버튼을 보여주어야 합니다. refreshSidebar를 통해 사이드바 내용을 갱신하는 기능도 포함합니다.

• 전역 변수 설정:

  • 활성 스프레드시트의 현재 시트를 참조하는 전역 변수 sheet를 선언합니다.

2. 텍스트 및 표 생성 (Gemini 사이드바)

• 메인 사이드바 (showGeminiSidebar) 구현:

  • 프롬프트 입력 영역, 이미지 파일 업로드(input type="file") 영역, Gemini 모델 선택(gemini-2.0-flash, gemini-1.5-pro-002), 출력 형식 선택(텍스트, 표) 드롭다운을 포함하는 HtmlService 기반의 사이드바를 만듭니다.

  • 이미지 업로드 시 미리보기가 가능해야 합니다.

• Gemini API 호출 함수 (GEMINI1, GEMINI_WITH_IMAGE) 구현:

  • 주어진 프롬프트, 모델 이름, API 키를 사용하여 Google의 Generative Language API(URL: https://generativelanguage.googleapis.com/v1beta/models/...:generateContent)를 호출합니다.

  • GEMINI_WITH_IMAGE 함수는 Base64 인코딩된 이미지 데이터를 받아 멀티모달 입력(텍스트 + 이미지)을 처리할 수 있어야 합니다. MIME 타입은 image/jpeg로 설정합니다.

  • 응답은 한국어로 요청하며, 응답 텍스트를 반환합니다.

  • GEMINI1 함수는 Sheets의 사용자 정의 함수 GEMINI와 이름이 겹치지 않도록 GEMINI1으로 명명합니다. (수정 요청: GEMINI1 대신 다른 적절한 이름을 사용해주세요. 예를 들어 generateTextContent).

• 스프레드시트 삽입 기능 구현 (generateGeminiContent):

  • API 결과를 받아 스프레드시트의 활성 셀에 삽입합니다.

  • 결과가 '텍스트' 형식일 경우, 활성 셀에 텍스트를 직접 setValue로 삽입합니다.

  • 결과가 '표' 형식일 경우, 마크다운 테이블 문자열을 파싱하여 2D 배열(formatMarkdownTable)로 변환한 후, insertFormattedTable 함수를 사용하여 활성 셀을 시작점으로 표를 삽입합니다. 이 때, 첫 번째 행은 굵게 표시하는 등 기본적인 서식을 적용합니다.

3. 이미지 생성 기능 (Gemini 이미지 생성 사이드바)

• 이미지 생성 사이드바 (showGeminiImageGenerationSidebar) 구현:

  • 이미지 프롬프트 입력 영역과 종횡비(aspectRatio) 선택 드롭다운(1:1, 3:4, 4:3, 9:16, 16:9)을 포함하는 사이드바를 구현합니다.

  • API 키가 없으면 경고 후 API Key 관리 사이드바를 열도록 합니다.

• 이미지 생성 API 호출 함수 (generateGeminiImage) 구현:

  • 모델 이름은 gemini-2.0-flash-exp-image-generation을 사용합니다.

  • 종횡비 선택에 따라 이미지의 width와 height를 계산하여 프롬프트에 추가합니다.

    • 예: 1:1 → 512x512, 3:4 → 384x512, 4:3 → 512x384, 9:16 → 288x512, 16:9 → 512x288

  • API 응답에서 Base64 인코딩된 이미지 데이터를 추출하여 전역 변수 (generatedImageData)에 저장하고, 미리보기용 데이터 URL 배열을 클라이언트(HTML)로 반환합니다.

• 클립보드 복사 지원:

  • 클라이언트 측(HTML/JavaScript)에서 데이터 URL을 사용하여 이미지를 미리 보여주고, "클립보드에 복사" 버튼을 제공합니다.

  • 클립보드 복사 시도 실패를 대비하여, 대체 복사 방법 (fallbackCopyMethod)으로 이미지 데이터 URL을 클립보드에 복사하도록 안내하는 기능이 필요합니다. (Google Sheets는 Google Docs와 같은 insertImage 기능을 직접 지원하지 않으므로, 이미지 파일 자체를 시트에 삽입하는 기능은 제외합니다.)

• 이미지 데이터 URL 반환 함수 (getImageDataUrl):

  • generatedImageData에 저장된 Base64 데이터를 data:image/png;base64,... 형식의 데이터 URL로 반환하여 클라이언트에서 사용할 수 있도록 합니다.

4. Google Sheets 사용자 정의 함수 (Custom Function)

• GEMINI 사용자 정의 함수 구현:

  • @customfunction JSDoc 주석을 포함하여 Google Sheets에서 =GEMINI("프롬프트", [참조 셀], [온도], [모델]) 형식으로 호출할 수 있도록 합니다.

  • 매개변수: prompt (필수), value (선택, 프롬프트에 추가될 셀 값), temperature (선택, 0~1, 기본값 0.7), model (선택, 기본값 gemini-2.0-flash).

  • API 키가 없거나 temperature 범위가 유효하지 않으면 적절한 오류 메시지를 반환합니다.

  • API 호출 시 응답은 한국어로 요청합니다.

5. 메뉴 구성

• 스프레드시트가 열릴 때(onOpen) 'Gemini'라는 이름의 커스텀 메뉴를 생성하고, 다음 항목들을 추가합니다:

  • Open Gemini Sidebar (showGeminiSidebar 호출)

  • 이미지 생성 (showGeminiImageGenerationSidebar 호출)

  • API Key 관리 (showApiKeySidebar 호출)

참고: Utilities.newBlob, Utilities.base64Decode, UrlFetchApp.fetch 등 Google Apps Script 내장 서비스를 활용해야 합니다. 클라이언트-서버 통신은 google.script.run을 사용합니다.

• 메뉴 구성 (onOpen):

  • 프레젠테이션이 열릴 때 'Gemini'라는 이름의 커스텀 메뉴를 생성하고, 다음 항목들을 추가합니다:

    • Open Gemini Sidebar (showGeminiSidebar 호출)

    • Slide 대량생성 하기 (showMailMergeSidebar 호출)

    • 이미지 생성 (showGeminiImageGenerationSidebar 호출)

    • API Key 관리 (showApiKeySidebar 호출)

• API Key 관리 기능:

  • PropertiesService를 사용하여 'Gemini_API_Key'를 안전하게 스크립트 속성에 저장, 읽기, 삭제하는 함수(saveApiKey, deleteApiKey)를 구현합니다.

  • API 키를 입력받고 관리하는 전용 사이드바(showApiKeySidebar)를 HtmlService로 생성하며, 키 저장/수정/삭제 기능을 지원합니다.

2. 텍스트 생성 기능 (Gemini Sidebar)

• 메인 사이드바 (showGeminiSidebar) 구현:

  • 프롬프트 입력 영역, 이미지 파일 업로드(input type="file") 영역, Gemini 모델 선택(gemini-2.0-flash-exp, gemini-1.5-pro-002), 출력 위치 선택(outputLocation: 현재 슬라이드, 새 슬라이드) 드롭다운을 포함하는 HtmlService 기반의 사이드바를 만듭니다.

• Gemini API 호출 함수 (GEMINI, GEMINI_WITH_IMAGE) 구현:

  • 주어진 프롬프트, 모델 이름, API 키를 사용하여 Generative Language API를 호출합니다.

  • GEMINI_WITH_IMAGE 함수는 Base64 인코딩된 이미지 데이터를 받아 멀티모달 입력을 처리할 수 있어야 합니다. MIME 타입은 image/jpeg로 설정합니다.

  • 응답은 한국어로 요청하며, 응답 텍스트를 반환합니다.

• 슬라이드 삽입 기능 (generateGeminiContent, addTextToSlide) 구현:

  • API 결과를 받아 outputLocation에 따라 현재 슬라이드 또는 새 슬라이드에 삽입합니다.

  • 삽입 시 addTextToSlide 함수를 사용하여 텍스트 상자(SlidesApp.ShapeType.TEXT_BOX)를 생성하고, 텍스트를 넣으며, 기본적인 위치/크기/폰트(14pt)를 설정합니다.

3. 이미지 생성 기능 (이미지 생성 사이드바)

• 이미지 생성 사이드바 (showGeminiImageGenerationSidebar) 구현:

  • 이미지 프롬프트 입력 영역과 종횡비(aspectRatio) 선택 드롭다운(1:1, 3:4, 4:3, 9:16, 16:9)을 포함하는 사이드바를 구현합니다.

  • API 키가 없으면 경고 후 API Key 관리 사이드바를 열도록 합니다.

• 이미지 생성 API 호출 함수 (generateGeminiImage) 구현:

  • 모델 이름은 gemini-2.0-flash-exp-image-generation을 사용합니다.

  • 종횡비에 따라 이미지의 width와 height를 설정하고 프롬프트에 포함합니다.

  • API 응답에서 Base64 인코딩된 이미지 데이터를 추출하여 전역 변수 (generatedImageData)에 저장하고, 미리보기용 데이터 URL 배열을 클라이언트(HTML)로 반환합니다.

• 클립보드 복사 지원 및 데이터 URL 반환:

  • 클라이언트 측(HTML/JavaScript)에서 "클립보드에 복사" 버튼을 제공합니다.

  • 클립보드 복사 시도 실패를 대비하여, 대체 복사 방법 (fallbackCopyMethod)으로 이미지 데이터 URL을 클립보드에 복사하도록 안내하는 기능이 필요합니다.

  • Base64 데이터를 data:image/png;base64,... 형식으로 반환하는 서버 함수 (getImageDataUrl)를 구현합니다.

4. 슬라이드 대량 생성 (Mail Merge 기능)

• 대량 생성 사이드바 (showMailMergeSidebar) 구현:

  • Gemini API를 사용해 데이터 초안을 생성하는 기능과 실제 메일 머지를 실행하는 기능을 통합합니다.

  • [Gemini 초안 만들기]: 주제, 타이틀, 열의 개수를 입력받고, generateGeminiTableCSV 함수를 호출합니다.

  • [메일 머지 실행]: CSV 파일 업로드 또는 Google Sheets URL 입력을 통해 데이터를 받아, performMailMerge 함수를 호출합니다.

• Gemini 마크다운 표 생성 (generateGeminiTableCSV) 구현:

  • gemini-1.5-pro 모델을 사용하여 주어진 주제와 열의 개수에 맞는 마크다운 테이블을 생성하도록 프롬프트를 구성합니다.

  • 생성된 마크다운 테이블이 요청된 열의 숫자와 일치하도록 데이터 행을 확인하고 조정(부족하면 추가, 초과하면 제거)하는 로직을 포함합니다.

• 메일 머지 실행 (performMailMerge) 구현:

  • input 매개변수에 CSV 문자열, Google Sheets URL, 또는 마크다운 테이블 문자열을 받아 데이터를 파싱합니다.

  • isMarkdown 플래그를 사용하여 마크다운 파싱(parseMarkdownTable)을 구분합니다.

  • 현재 선택된 슬라이드를 템플릿으로 사용하고, 데이터 세트 수만큼 슬라이드를 복제(presentation.appendSlide(templateSlide))합니다.

  • 데이터를 슬라이드에 적용 (applyDataToSlide):

    • 슬라이드 내의 텍스트 상자를 찾아 {헤더명} 형태의 플레이스홀더를 해당 데이터 값으로 대체합니다.

    • 슬라이드 내의 이미지를 찾아 대체 텍스트/설명(Description)이 {사진}인 경우, 데이터 세트의 사진 키에 해당하는 URL로 이미지를 교체(image.replace(url))합니다. 이 때 원본 이미지의 크기, 위치, 대체 텍스트를 유지해야 합니다.

    • Google Drive 링크는 직접 다운로드 가능한 URL 형식(processDriveLink)으로 변환하여 사용해야 합니다.

참고: SlidesApp.getUi(), SlidesApp.getActivePresentation(), UrlFetchApp.fetch, PropertiesService, HtmlService를 사용해야 합니다. 텍스트 삽입은 TextRange.replaceAllText를 활용하고, 이미지 교체는 Image.replace()를 활용해야 합니다.

메뉴 구성 (onOpen) 🛠️

Google Forms 파일이 열릴 때마다 Google Apps Script의 onOpen 트리거를 사용하여 자동으로 사용자 인터페이스에 'Gemini'라는 맞춤 메뉴를 생성합니다. 이 메뉴는 사용자가 모든 주요 기능에 쉽게 접근하도록 돕는 핵심 진입점 역할을 합니다.

메뉴 항목기능 설명호출 함수Open Gemini 퀴즈퀴즈 생성 설정을 위한 사이드바를 엽니다.showGeminiSidebarOpen Gemini 설문설문 생성 설정을 위한 사이드바를 엽니다.showGeminiSurveySidebar퀴즈 대량 복사(대량 작업) 퀴즈 양식 복사 기능을 위한 사이드바를 엽니다.showBulkQuizSidebar설문 대량 복사(대량 작업) 설문 양식 복사 기능을 위한 사이드바를 엽니다.showBulkSurveySidebar이미지 생성(AI 이미지 생성) 이미지 생성 기능을 위한 사이드바를 엽니다.showGeminiImageGenerationSidebarAPI Key 관리API 키를 안전하게 설정/수정/삭제하는 전용 사이드바를 엽니다.showApiKeySidebar

Sheets로 내보내기

API Key 관리 기능 (보안 및 연동) 🔑

Gemini API를 사용하기 위해 가장 중요한 단계로, PropertiesService를 활용하여 API 키를 안전하게 관리합니다.

1. 키 저장/읽기/삭제 함수:

   • PropertiesService는 Google Apps Script 환경 내에서 데이터를 안전하게 저장할 수 있는 서비스입니다.

   • saveApiKey, getApiKey, deleteApiKey 함수는 'Gemini_API_Key'라는 이름으로 이 스크립트 속성 공간에 API 키를 저장, 읽기, 삭제하는 역할을 전담합니다. 이 방법은 코드를 외부에 노출하지 않고 키를 관리하게 해줍니다.

2. API Key 관리 전용 사이드바 (showApiKeySidebar):

   • HtmlService를 사용하여 키 입력, 저장, 삭제를 위한 사용자 인터페이스를 만듭니다.

   • 사이드바가 열리면 google.script.run을 통해 저장된 키의 존재 여부를 확인하고, 키가 있다면 보안을 위해 마지막 몇 자리만 마스킹 처리하여 표시합니다.

   • 사용자가 새 키를 입력하고 '저장' 버튼을 누르면, 클라이언트(HTML)에서 서버 측 함수(saveApiKey)를 직접 호출하여 키를 안전하게 스크립트 속성에 저장합니다.

   • '삭제' 버튼은 서버 측 deleteApiKey 함수를 호출하여 저장된 키를 즉시 제거합니다.

2. 텍스트 생성 기능 (퀴즈/설문 생성)

퀴즈 생성 사이드바 (showGeminiSidebar) ✏️

퀴즈 생성에 필요한 모든 옵션을 수집하는 HtmlService 기반의 인터페이스입니다.

• 주요 입력 항목: 퀴즈 주제 (필수), 문항 수, 난이도 (초급/중급/고급), 문제 유형 (객관식/단답형/서술형), 객관식 유형 (OX/4지선다/5지선다), 체크박스형 여부 (복수 정답), 문항당 배점.

• 동작 원리: 사용자가 모든 옵션을 선택하고 '생성' 버튼을 누르면, 이 모든 설정 값이 하나의 JavaScript 객체로 묶여 google.script.run을 통해 서버 측 generateGeminiQuiz 함수로 비동기적으로 전달됩니다.

설문 생성 사이드바 (showGeminiSurveySidebar) 📋

설문 문항 생성에 필요한 옵션을 수집하는 HtmlService 기반의 인터페이스입니다.

• 주요 입력 항목: 설문조사 주제 (필수), 문항 수, 문제 유형 (단답형, 장문형, 객관식, 체크박스 등, 복수 선택 가능), 객관식 문항 수 (선택지 개수).

• 동작 원리: 퀴즈 생성과 동일하게, 설정 값이 객체로 묶여 서버 측 generateGeminiSurvey 함수로 전달됩니다.

Gemini API 호출 함수 (GEMINI) 및 폼 문항 삽입 🔗

이 부분은 스크립트의 핵심 로직으로, AI와의 통신과 폼 문서 조작을 담당합니다.

1. API 호출 함수 (GEMINI) 구현:

   • 이 함수는 서버 측에서 실행되며, 전달받은 프롬프트와 모델 이름(예: gemini-1.5-pro)을 사용합니다.

   • 가장 먼저 getApiKey()를 호출하여 스크립트 속성에 저장된 API 키를 가져옵니다. 키가 없으면 사용자에게 키 설정을 안내하는 오류를 반환합니다.

   • 가져온 키를 사용하여 Generative Language API의 HTTP 요청을 구성하고 UrlFetchApp을 통해 API를 호출합니다.

   • 프롬프트에는 항상 응답을 한국어로 요청하는 지침을 명시적으로 포함합니다.

   • API 응답을 JSON으로 파싱하고, 실제 응답 텍스트만을 추출하여 반환합니다.

2. 폼 문항 삽입 기능 (generateGeminiQuiz, generateGeminiSurvey):

   • 사이드바에서 설정값을 받고, 이를 바탕으로 AI가 이해할 수 있는 상세한 프롬프트를 동적으로 생성합니다. (예: "주제 '대한민국 역사', 중급 난이도의 4지선다 객관식 5문항을 JSON 형식으로 작성하고, 정답과 해설을 포함해줘.")

   • GEMINI 함수를 호출하여 AI 응답을 받습니다.

3. API 결과 파싱 및 삽입:

   • parseQuizContent / parseSurveyContent: GEMINI로부터 받은 응답 텍스트(일반적으로 JSON 또는 특정 마크다운 구조)를 파싱하여 질문, 선택지, 정답, 배점 등을 포함하는 구조화된 배열(JavaScript 객체)로 변환합니다.

   • 폼에 추가: FormApp.getActiveForm()을 통해 현재 폼 객체를 가져와, 파싱된 각 질문 데이터를 기반으로 새로운 섹션(addPageBreakItem)을 추가하고 FormApp 아이템을 생성합니다.

     • 퀴즈: addQuestionToForm 함수에서 setPoints()로 배점 설정, setFeedbackForCorrect() 등으로 정답과 해설을 설정합니다. 특히, 체크박스형 문제의 경우 복수 정답이 모두 올바르게 처리되었는지 확인합니다.

     • 설문: addSurveyQuestionToForm 함수에서 배점 설정 없이 질문 유형(단답형, 장문형, 다중 선택 등)에 맞는 아이템을 생성하여 추가합니다.