設計書

概要

背景・目的

背景：スプレッドシートのタスクを手作業でMicrosoft To Doへ転記するのは手間であった。

目的：スプレッドシートのタスクを自動でMicrosoft To Doに連携し、転記作業を省力化・効率化する。

機能一覧

• Googleスプレッドシートの「Tasks」シートに記載されたタスクをMicrosoft To Doへ自動で登録します。
• MicrosoftアカウントのOAuth2認証フロー（認証URL生成・トークン自動取得）を実行できます。
• OAuth認証後は自動的にリダイレクトされ、トークンが自動取得されます（認可コードの手動入力が不要）。
• アクセストークンの有効期限を管理し、期限切れ時はエラーを表示します。
• タスクごとに登録結果（成功またはエラー内容）を「result」列に出力します。
• タイトルやリスト名などの必須項目をバリデーションします。
• 期限日、本文、繰り返し設定など、指定された各種タスク属性を反映して登録します。
• 期限日はスプレッドシートのタイムゾーンでMicrosoft To Doに登録されます。
• Googleスプレッドシートのカスタムメニューから認証やタスク登録などの操作を実行できます。

入力

本スクリプトは、以下2つのシート構成を前提としています。

「Auth」シート

セル	内容
A1	MicrosoftアプリのClient ID
A2	MicrosoftアプリのClient Secret
A3	アクセストークン（自動取得）
A4	リフレッシュトークン（自動取得）
A5	認証URL（自動生成）
A6	トークン有効期限（自動生成、UNIXミリ秒、内部管理用）
A7	code_verifier（PKCE用、自動生成）
A8	Redirect URI（GAS WebアプリのURL）

「Tasks」シート

列名	内容
title	タスクのタイトル（必須）
list_name	登録先リスト名（必須）
body	タスクの本文（任意）
due	期限日
status	タスクの状態（任意、未指定時はnotStarted）
recurrence_type	繰り返し種別（任意、未指定時は繰り返しなし）
recurrence_start	繰り返し開始日（任意）
recurrence_end	繰り返し終了日（任意）
recurrence_interval	繰り返し間隔（任意、数値）
result	登録結果（自動出力）

status列に指定可能な値

値	意味
notStarted	未開始
inProgress	進行中
completed	完了
waitingOnOthers	他者待ち
deferred	延期

recurrence_type列に指定可能な値

値	意味
daily	毎日
weekly	毎週
absoluteMonthly	毎月（特定日）
absoluteYearly	毎年（特定日）
relativeMonthly	毎月（第n曜日など）
relativeYearly	毎年（第n曜日など）

出力

• Googleスプレッドシート「Tasks」シートの「result」列に、各タスクの登録結果（Successまたはエラー内容）を自動で出力します。
• Microsoft To Doに、Tasksシートで指定した内容のタスクが登録されます。
• Googleスプレッドシート上で、処理完了やエラー発生時にダイアログメッセージが表示されます。

※ ファイルとしての出力（CSVやPDFなど）はありません。

実行方法

1. Googleスプレッドシートを開き、「拡張機能」→「Apps Script」から本スクリプト（MicrosoftToDoImporter.gs）を貼り付けて保存します。
2. スプレッドシートに「Auth」シートと「Tasks」シートを作成し、必要なセル・列を準備します（AuthシートのA1〜A8、Tasksシートの列は本READMEの「入力」を参照）。
3. GAS を Web アプリとして公開し、デプロイされたURLを取得してAzure側のRedirect URIに登録します。
   1. Apps Scriptエディタで右上の「デプロイ」→「新しいデプロイ」を選択します。
   2. デプロイの種類で「Webアプリ」を選択します。
   3. 「実行するユーザー」は 自分 を選択します。
   4. 「アプリにアクセスできるユーザー」は必要最小限の範囲を選択します（個人利用は 自分のみ）。
   5. デプロイして表示されるWebアプリのURLをコピーし、AuthシートのA8セルに貼り付けます。
   6. Azureポータルで該当アプリの「認証（Authentication）」設定を開き、プラットフォームに「Web」を追加して、コピーしたWebアプリのURLをRedirect URI（タイプ：Web）として登録します。
4. AuthシートのA1・A2セルにMicrosoftアプリのClient ID・Client Secretを入力します。
5. スプレッドシートを再読み込みし、メニューに「Microsoft To Do」が追加されていることを確認します。
6. メニューから「認証URL生成」を選択し、A5セルのURLをブラウザで開いて認可します。
7. Microsoftの認可画面で許可すると、自動的にリダイレクトされ、トークンが自動取得されます（A3/A4/A6セルに保存されます）。
8. Tasksシートにタスク情報を記入し、「TasksシートからTo Doに登録」を実行します。
9. 各タスクの登録結果がresult列に出力されます。

想定実行環境

本ツールはGoogle Apps Script（GAS）として動作します。利用にあたり、以下の環境を想定しています。

項目	内容
動作環境	Googleスプレッドシート（Webブラウザー版）
ブラウザ	Google Chrome最新版
Microsoftアカウント	Microsoft To Doが利用可能なアカウント（組織/個人どちらも可）

処理詳細

本ツールの主な処理フローは以下の通りです。

認証URL生成処理

Googleスプレッドシートのカスタムメニューから「認証URL生成」を選択すると、次の処理を行います。

1. AuthシートA1セルからMicrosoftアプリのClient ID、A8セルからRedirect URI（GAS WebアプリのURL）を取得します。
2. PKCE用のcode_verifierとcode_challengeを生成し、code_verifierをAuthシートA7セルに保存します。
3. Microsoft認証エンドポイント、リダイレクトURI、スコープ、code_challenge、code_challenge_method=S256などのパラメータを組み合わせて認証用URLを生成します。
4. 生成した認証URLをAuthシートA5セルに出力します。

トークン自動取得処理（自動）

認証URL（A5セル）をブラウザで開いてMicrosoftアカウントで認可すると、以下の処理が自動的に実行されます。

1. OAuth認可後、ブラウザはGAS WebアプリのURLへ認可コード（code）付きでリダイレクトされます。
2. doGet関数が認可コードを受け取り、AuthシートA7セルからcode_verifier、A8セルからRedirect URIを取得します。
3. Microsoftのトークンエンドポイント（/token）へアクセストークン・リフレッシュトークン取得リクエストを送信します（PKCE対応）。
4. レスポンスからアクセストークン・リフレッシュトークン・有効期限を取得します。
5. 取得したアクセストークンをAuthシートA3セル、リフレッシュトークンをA4セル、有効期限（UNIXミリ秒換算）をA6セルに保存します。
6. セキュリティ対策として、AuthシートA7セルのcode_verifierをクリアします（空文字を保存）。
7. ブラウザに「認証完了」メッセージを表示します。

タスク登録処理

Googleスプレッドシートのカスタムメニューから「TasksシートからTo Doに登録」を選択すると、次の処理を行います。

1. Tasksシートの全データ行を取得し、1行ずつ順に処理します。
2. 各行について、以下の処理を実施します。
   1. タスクデータをオブジェクト形式に変換します。
   2. 必須項目（タイトル・リスト名）が未入力の場合はバリデーションエラーとしてresult列にエラー内容を出力し、次の行へ進みます。
   3. 期限日や繰り返し設定などの値を整形・検証します（不正な場合はエラーとしてresult列に出力）。
   4. Microsoft To DoリストIDをAPI経由で取得します（リストが存在しない場合はエラーとしてresult列に出力）。
   5. タスク情報をMicrosoft Graph API用のリクエスト形式に変換します。
   6. Microsoft Graph APIを呼び出してタスクを登録します。
   7. 登録に成功した場合はresult列に「Success」、失敗した場合はエラー内容を出力します。

メッセージ一覧

種別	メッセージ内容	用途・タイミング
完了	認証URLを生成しました。\nセルA5をクリックしてブラウザで開いてください。	認証URL生成時（ダイアログ）
完了	認証完了	OAuth認証とトークン取得が正常に完了した場合（WebアプリのHTML出力）
完了	タスク登録処理が完了しました！	全タスク登録完了時（ダイアログ）
エラー	{sheetName}シートが存在しません	Authシート、またはTasksシートが存在しない場合
エラー	{fieldName}が空またはスペースのみです。正しい値を入力してください。	認証URL生成時またはトークン取得時に必須項目が空の場合
エラー	Authシートにトークン情報がありません。初回認証が必要です。	トークン未取得時
エラー	Tasksシートに'result'列がありません。'result'列を追加してください。	result列未作成時
エラー	title/list_name missing	必須項目未入力時
エラー	due日付が不正です	期限日が不正な場合
エラー	Error: {msg}	トークン取得処理中に予期しないエラーが発生した場合（WebアプリのHTML出力）
エラー	Microsoft To Do登録APIエラー: HTTP {code}\n{body}	Microsoft To Do API呼び出し時にHTTPエラーが発生した場合（result列）
エラー	アクセストークンの有効期限が切れています。再度認証を実行してください。	トークン有効期限切れ時
エラー	アクセストークン取得に失敗しました: {msg}	アクセストークン取得失敗時
エラー	トークン取得エラー: HTTP {code}\n{body}	Microsoftのトークンエンドポイントからエラーレスポンスが返された場合（WebアプリのHTML出力）
エラー	認可コードが見つかりません	OAuth認証後のリダイレクト時に認可コードが取得できなかった場合（WebアプリのHTML出力）
エラー	指定リストが見つかりません: {listName}	list_name不正時
結果	Error: {msg}	タスク登録失敗時（result列）
結果	Success	タスク登録成功時（result列）

ライセンス

本プログラムのライセンス

• このプログラムはMITライセンスに基づいて提供されます。

開発詳細

開発環境

• VSCode バージョン 1.103.1

改訂履歴

バージョン	日付	内容
2.0.0	2026-01-05	・PKCE対応のOAuth 2.0フローに移行 ・認可コードの自動取得機能を追加 ・Authシートのバリデーション強化 ・認証URL生成時のメッセージ表示タイミングを改善
1.0.2	2026-01-04	エラーメッセージを改善し、AuthシートまたはTasksシートが存在しない場合の説明を統合
1.0.1	2025-08-17	・リマインダー機能の記述・処理を削除 ・期限日・繰り返し設定のタイムゾーン対応 ・Microsoft Graph APIエラー時の詳細なエラーメッセージ追加 ・APIエラー時のハンドリング強化 ・日付バリデーション処理の追加 ・READMEの説明文を一部修正・追記
1.0.0	2025-08-17	初版リリース