Google Calendar・Microsoft Graph｜Drive・OneDrive・SharePoint連携 カレンダーイベント添付ファイル検索

Google Driveへの保存が前提か？

Google Calendar API リファレンスには、「Google Driveに格納していないファイルは添付不可」という明記はありません。

一方、「予定にドライブの添付ファイルを追加する」ガイドは、Google Driveファイルを添付する手順だけを説明されてます。

Google Calendar APIのイベントには、ファイル本体を直接アップロードする機能はありません。attachments[]には添付ファイルへのURLを設定します。

• https://developers.google.com/workspace/calendar/api/guides/create-events?hl=ja

予定にドライブの添付ファイルを追加する

カレンダーの予定に、Google ドキュメントの会議メモ、Google スプレッドシートの予算、Google スライドのプレゼンテーションなど、関連する Google Drive ファイルを添付できます。添付ファイルは、 予定を作成するときに追加することも、 events.insert()などの 更新の一部として後で追加することもできます。events.patch()

Google ドライブのファイルを予定に添付する手順は次のとおりです。

1. 通常は files.get() メソッドを使用して、 Drive API Files リソース からファイルの alternateLink URL、title、mimeType を取得します。
2. リクエスト本文に attachments フィールドを設定し、supportsAttachments パラメータを true に設定して、予定を作成または更新します。

イベントのattachments[]には、Google Driveに保存されたファイルへの参照を設定します。添付を追加または変更するリクエストでは、supportsAttachments=trueの指定が必要です。

1つのイベントに設定できる添付ファイルは最大25件です。

Google Driveへファイルをアップロードする

• Google Drive API：ファイルデータをアップロードする

Driveへの保存後にカレンダーへ設定する

Driveへのアップロードが完了したら、Drive APIから次の情報を取得します。

• ファイルID
• ファイル名
• MIMEタイプ
• 閲覧用URL

取得した情報を、Calendar APIのevents.patchなどを使用してイベントのattachments[]へ設定します。

PATCH https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/{eventId}?supportsAttachments=true
Content-Type: application/json

既存の添付があるイベントへ新しいファイルを追加する場合は、先にイベントを取得し、現在のattachments[]に新しい添付情報を追加してから更新します。

• Google Calendar API：予定にGoogle Driveの添付ファイルを追加する
• Google Calendar API：Events.patch

組織アカウントでは共有ドライブを使用する

Google Workspace環境で共有ドライブを利用できる場合は、チーム用ファイルの保存先として共有ドライブを使用するのが適しています。

マイドライブのファイルは個人ユーザーが所有しますが、共有ドライブ内のファイルは個人ではなく組織が所有します。

そのため、ファイルをアップロードした担当者が組織を離れた場合でも、ファイルを組織の資産として維持しやすくなります。

• Google Drive API：共有ドライブの概要

共有ドライブを利用できない個人アカウントでは、マイドライブ上に共有フォルダを作成し、Drive APIのPermissionsリソースを使用してユーザーやグループへ権限を付与します。

• Google Drive API：ファイル、フォルダ、ドライブを共有する

Microsoft側は直接添付とストレージ保存に分かれる

Microsoft Graphでは、イベントへファイル本体を直接添付する方法と、OneDriveまたはSharePointにファイルを保存する方法があります。

検索機能やGoogle側との実装の共通化を重視する場合は、OneDriveまたはSharePointに保存する構成が適しています。

イベントへファイル本体を直接添付する

3MB未満のファイルは、イベントの添付エンドポイントへPOSTできます。

イベントへ直接添付したファイルは、OneDriveやSharePointのdriveItemとして管理されません。

そのため、OneDriveやSharePoint側のフォルダ管理、共有設定、ファイル検索と同じ仕組みには統合しにくくなります。

OneDriveまたはSharePointへ保存する

検索機能を実装する場合は、ファイル本体をOneDriveまたはSharePointのドキュメントライブラリへアップロードします。

Sites.Read.All : SharePoint ルート サイトのリストを読み取ります ( GET /v1.0/sites/root/lists)
Sites.ReadWrite.All : SharePoint リストに新しいリスト アイテムを作成します ( POST /v1.0/sites/root/lists/123/items)
Sites.Manage.All : SharePoint サイトに新しいリストを追加する ( POST /v1.0/sites/root/lists)
Sites.FullControl.All：SharePointサイトとリストへの完全なアクセス権。
https://learn.microsoft.com/en-us/onedrive/developer/rest-api/concepts/permissions_reference?view=odsp-graph-online

referenceAttachmentを利用する場合は事前検証する

Microsoft Graphには、OneDrive for Businessなどに保存されたファイルへのリンクを表すreferenceAttachmentリソースがあります。

referenceAttachmentは、ファイル本体ではなく、クラウドストレージ上のファイルへの参照を表します。

• Microsoft Graph：referenceAttachmentリソース

ただし、イベントへの登録方法や対応状況は、使用するアカウント、カレンダーの種類、Microsoft Graphのバージョンによって確認が必要です。

そのため、OneDriveまたはSharePointへ保存したファイルをイベントの正式な添付として登録する構成を採用する場合は、対象環境でreferenceAttachmentの登録処理を先に検証します。

安定して利用できない場合は、次の方法でイベントとファイルを関連付けます。

• イベント本文にファイルURLを記載する
• イベントの拡張プロパティにファイルIDを保存する
• 自前DBでファイルとイベントの対応を管理する

Microsoft 365 Groupのドキュメントライブラリを使用する

Microsoft 365 Groupに関連付けられたドキュメントライブラリは、次のエンドポイントから取得できます。

GET /groups/{groupId}/drives

このAPIを使用すると、グループが利用できるSharePointのドキュメントライブラリをdriveリソースとして取得できます。

• ドライブを一覧表示する – Microsoft Graph v1.0 | Microsoft Learn

チームで共有するファイルは、個人のOneDriveよりも、グループまたはSharePointサイトのドキュメントライブラリへ保存した方が、担当者個人への依存を減らせます。

グループカレンダーイベントは添付に対応しない

Microsoft側で特に注意が必要なのが、Microsoft 365 Groupのグループカレンダーです。

Microsoft Graphの公式仕様では、添付ファイルを追加できるのはユーザーの予定表のイベントだけです。グループの予定表のイベントには、添付ファイルオブジェクトを追加できません。

• event リソースの種類 – Microsoft Graph v1.0 | Microsoft Learn

グループカレンダーを使用する場合は、次のいずれかの方法を採用します。

• イベント本文へSharePointファイルのURLを記載する
• イベントの拡張プロパティにファイルIDを保存する
• 自社アプリのDBでイベントとファイルを関連付ける
• 添付が必要な場合はユーザーまたは専用アカウントのカレンダーを使用する

必要な「スコープ（scope）」・「パーミッション（permission）」

OAuthの仕組みで、アプリがユーザーのデータにアクセスするとき「何にアクセスできるか」を制限する仕組みです。

例えばあなたのアプリをユーザーがインストールすると、「このアプリがあなたのカレンダーの読み書きとGoogleドライブのファイル閲覧を求めています。許可しますか？」という同意画面が出ます。

あの画面に表示される項目一つ一つがスコープ/パーミッションです。

GoogleとMicrosoftで呼び方が違うだけで同じ概念です。Googleは「スコープ（scope）」、Microsoftは「パーミッション（permission）」と呼びます。

Google

Google Cloud Console（https://console.cloud.google.com）で設定します。

1. プロジェクトを作成
2. 「APIとサービス」→ 使うAPI（Calendar API, Drive API）を有効化
3. 「OAuth同意画面」でアプリ情報とスコープを登録
4. 「認証情報」でOAuthクライアントID（client_id / client_secret）を発行

実際のスコープ要求はアプリのコード側でもOAuth認証フロー開始時に指定します。Console側の登録とコード側の指定の両方が必要です。

Microsoft

Azure Portal（https://portal.azure.com）の Microsoft Entra ID（旧Azure AD）で設定します。

1. 「アプリの登録」で新規登録
2. 「APIのアクセス許可」でMicrosoft Graphのパーミッション（Calendars.ReadWrite, Files.ReadWrite等）を追加
3. 必要に応じて管理者の同意を付与
4. 「証明書とシークレット」でclient_secretを発行

こちらもコード側のOAuthフローでスコープを指定する必要があります。

どちらもやることの構造は同じで、「管理コンソールでアプリを登録してスコープを宣言 → コードでOAuthフロー時にスコープを要求 → ユーザーが同意 → トークン発行」という流れです。

Google

CalendarとDriveは別サービスなので、添付フィールド方式でDriveのファイルをイベントに紐付ける場合はCalendar + Driveの両方のスコープが必要です。

Microsoft Graph

ドライブからファイル検索

Google Driveの検索

Google Driveでは、files.listのqパラメータで検索条件を指定できます。

fullText contains '議事録'

fullTextを使用すると、ファイル名、説明、インデックス対象となったファイル内容などを検索できます。

• ファイルやフォルダを検索する | Google Drive | Google for Developers

OneDrive・SharePointの検索

Microsoft側では、検索範囲によってAPIを使い分けます。

特定のドライブやフォルダ内を検索する場合は、driveItemのsearch APIを使用できます。

• Microsoft Search API を使用して OneDrive と SharePoint のコンテンツを検索する – Microsoft Graph | Microsoft Learn

OneDriveやSharePointのコンテンツを横断して検索する場合は、Microsoft Search APIのPOST /search/queryを使用します。

検索結果には、ファイル名、更新日時、webUrl、保存先のドライブIDやサイトIDなどが含まれます。

KQLとは

SharePointやOneDrive上のファイル・リストアイテムを検索するための構文です。検索できる範囲はログインユーザーの権限に依存し、アクセス権のないアイテムは結果に表示されません。

構文を使うことで、ファイル種別や更新日、作成者などの条件を指定して検索結果を絞り込めます。

キーワード照会言語 (KeyQL) 構文リファレンス、KeyQLを使用したフリー テキスト クエリの構築
https://learn.microsoft.com/ja-jp/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference

プロパティ制限でサポートされているプロパティ演算子
https://learn.microsoft.com/ja-jp/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference#property-operators-that-are-supported-in-property-restrictions

複雑なクエリのKeyQL演算子
https://learn.microsoft.com/ja-jp/sharepoint/dev/general-development/keyword-query-language-kql-syntax-reference#keyql-operators-for-complex-queries

Microsoft Graph の Microsoft Search API を使用して、OneDrive または SharePoint に格納されているコンテンツ (ファイル、フォルダー、リスト、リスト アイテム、またはサイト) を検索します。
https://learn.microsoft.com/ja-jp/graph/search-concept-files

検索可能なプロパティ
https://learn.microsoft.com/ja-jp/sharepoint/technical-reference/crawled-and-managed-properties-overview#managed-properties-overview

アップロードしたファイルから、添付されているカレンダーを検索

大まかな流れ

1. 添付ファイルのタイトル、本文内容に対してキーワード検索
2. 検索に当てはまるドライブ内のファイルを取得
3. ファイルを添付しているカレンダーのイベントを取得

Googleは 添付ファイルをアップロード時に拡張プロパティに対応情報を紐付け検索時に files.list → events.list

こちらの方法ではアプリ上ではなく、GoogleカレンダーのWebでファイルを添付した場合は検索できない制限があります

ちなみにGoogleカレンダーウェブUIから編集してファイルを添付する場合、ドライブアイコン  をクリックして可能です、そこでドライブからかアップロードするか選べれますが、アップロードの場合はマイドライブに格納されるようです。

ステップ0 — カレンダーにファイルを添付する際にファイルIDを拡張プロパティに設定する

ステップ1 — ドライブ内のファイルを検索

corporaでドライブの範囲を指定

// allDrives: アクセス可能な全ドライブから検索
drive.files.list({
  corpora: 'allDrives',
...
})

// drive: 特定の共有ドライブのみ検索
drive.files.list({
  corpora: 'drive',
  driveId: '共有ドライブのID',
...
})

共有ドライブをブラウザで開いたときのURLから確認できます

https://drive.google.com/drive/folders/XXXXXXXXXXXXXXXXX

この XXXXXXXXXXXXXXXXX の部分が共有ドライブのIDです。

Corpora

ファイルとフォルダの検索範囲を絞り込むために使用されるファイルのコレクション。ドライブのコーパスは、user、domain、drive、allDrives です。
user: [マイドライブ] でユーザーが作成して開いたすべてのファイルと、[共有アイテム] でユーザーと直接共有されたファイルが含まれます。

drive: driveId で指定された単一の共有ドライブに含まれるすべてのファイルが含まれます。

domain: ユーザーのドメインと共有されている検索可能なすべてのファイルが含まれます。

allDrives: ユーザーがメンバーになっている共有ドライブ内のすべてのファイルと、[マイドライブ] および [共有アイテム] 内のすべてのファイルが含まれます。allDrives コーパスは範囲が広く、パフォーマンスに影響する可能性があるため、慎重に使用してください。効率化のため、可能な限り allDrives ではなく user または drive を使用します。
https://developers.google.com/workspace/drive/api/guides/about-files?hl=ja

Method: files.list
https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list?hl=ja

クエリパラメータ

qのエスケープ

クエリが正しく動作するように、ファイル名内の特殊文字をエスケープする必要があります。たとえば、ファイル名にアポストロフィ（'）とバックスラッシュ（"\"）の両方が含まれている場合は、バックスラッシュを使用してエスケープします（name contains 'quinn\'s paper\\essay'）。

https://developers.google.com/workspace/drive/api/guides/search-files?hl=ja#examples

fullText contains 検索の仕様

• 検索キーワードはGoogle内部のトークン（分割単位）と完全一致する必要がある
• 英語: スペース、_、camelCaseの大文字境界でトークン分割される
• 日本語: 形態素解析で意味のある単語単位に分割される（「面接」「について」等）
• 大文字小文字は区別しない（world で World にヒット）

※トークンとは検索エンジンが文字列を内部的に分割した結果の1単位のこと

全テスト fullText contains のみで実施

“The contains operator only performs matching on entire string tokens for the fullText term.” 検索対象は “name, description, indexableText, or text in the file’s content or metadata”
Search query terms and operators

ステップ2 — ファイルを含むカレンダーイベントを検索

events.list で使えるパラメータは以下の通りです

privateExtendedProperty、sharedExtendedPropertyでGoogle APIリクエスト時にフィルターをして取得します

Google の公式ドキュメント同士で矛盾？

• Extended Properties ガイド「制約は OR で結合されるため、いずれか 1 つに一致するだけで返される」→ OR
• events.list リファレンス「指定されたすべての制約に一致するイベントを返す」→ AND

Events.list リクエストを使用して、拡張プロパティの値に基づいてイベントを検索できます。フィールド privateExtendedProperty または sharedExtendedProperty を propertyName=value 形式の制約に設定します。これにより、それぞれプライベート プロパティと共有プロパティに対して検索が行われます。
これらのフィールドは複数回繰り返すことができ、制約は OR で結合されるため、イベントは制約のいずれか 1 つに一致するだけで返されます。次の例では、非公開プロパティ petsAllowed=yes または isOutside=yes のいずれかを持つイベントを検索します。
https://developers.google.com/workspace/calendar/api/guides/extended-properties?hl=ja#search_properties

Google Calendar API – events.list の privateExtendedProperty パラメータの説明
「match all given constraints」= すべての条件に一致するイベントのみ返す、つまり AND条件 です。

privateExtendedProperty

string

propertyName=value として指定された拡張プロパティの制約。プライベート プロパティのみが一致します。このパラメータは、指定されたすべての制約に一致するイベントを返すために複数回繰り返されることがあります。

ドキュメントだけでは確定できないため、実際のAPIで動作検証を行った。

検証方法

1. 異なる拡張プロパティを持つイベントを2つ用意する
   • イベントA：プロパティ①のみ
   • イベントB：プロパティ②のみ
2. privateExtendedProperty にプロパティ①と②を同時指定して検索

• A・B両方返る → OR
• 0件 → AND（各イベントは片方の条件しか満たさないため）

あわせて、プロパティ①のみを単独指定した検索も実施

動作的にはAND条件と判断できました

• events.list リファレンスの記載（AND）が実挙動と一致。Extended Properties ガイドの「OR」という記載は誤り。
• したがって「複数の候補のうちいずれかに一致するイベント」を取得したい場合は、複数値を一括で渡すのではなく、条件ごとに個別にAPIを呼び出して結果をマージ（イベントIDで重複排除）する必要がある。

検索画面はGoogleとMicrosoftで共通化できる

ストレージAPIのレスポンス形式は異なりますが、画面へ返すデータをアプリ側で共通形式へ変換できます。

type FileSearchResult = {
  provider: "google" | "microsoft";
  fileId: string;
  fileName: string;
  mimeType: string;
  modifiedAt: string;
  fileUrl: string;
  eventId: string | null;
  eventUrl: string | null;
};

検索結果には、次の操作を表示します。

• ファイルを開く
• 関連する予定を開く
• ファイルを要約する

これにより、利用者はGoogle Drive、OneDrive、SharePointの違いを意識せず、同じ検索画面からファイルへアクセスできます。

AI要約もストレージ取得に統一する

AI要約を行う場合も、カレンダーの添付データではなく、ストレージからファイル本体を取得します。

Google Driveでは、通常のファイルをfiles.getとalt=mediaでダウンロードします。

Googleドキュメント、Googleスプレッドシート、Googleスライドなどは、files.exportを使用してPDFなどの別形式へ変換します。

参考：

• Google Drive API：ファイルのダウンロードとエクスポート

Microsoft Graphでは、driveItemのコンテンツ取得APIを使用します。

GET /drives/{driveId}/items/{itemId}/content

参考：

• Microsoft Graph：driveItemのコンテンツをダウンロードする

取得したファイルをClaudeなどのAI APIへ渡し、要約結果を自社DBへ保存します。

同じファイルが更新されていない限り要約を再実行しないように、次の情報を保存しておくとAI APIの利用料を抑えられます。

• ファイルID
• ファイルの更新日時
• ファイルのハッシュ値
• 使用したAIモデル
• 要約を実行した日時

調査段階で先に決めること

最初に確認するべきなのは、使用するアカウントが組織アカウントか個人アカウントかです。

Google Workspaceで共有ドライブを利用できるか、Microsoft 365 GroupやSharePointを利用できるかによって、保存先と権限設計が変わります。

Microsoft側では、ユーザーのカレンダーを使用するのか、Microsoft 365 Groupのグループカレンダーを使用するのかも先に確定させます。

グループカレンダーイベントは添付ファイルに対応していないため、この判断は実装方式へ直接影響します。

また、次の点もプロトタイプ段階で確認します。

• Google Calendarへ添付を登録できるか
• 更新時に既存の添付が維持されるか
• Microsoftのリンク添付が対象環境で利用できるか
• ファイル閲覧権限とカレンダー参加者が一致するか
• 検索結果からイベントへ戻るURLを取得できるか
• ファイル削除時とイベント削除時に関連データをどう処理するか
• AI APIへ送信できるファイル形式と最大サイズ

基本方針は、GoogleとMicrosoftの両方で「ファイル本体はストレージへ保存し、カレンダーには参照を持たせる」です。

ただし、Microsoft 365 Groupのグループカレンダーイベントは添付に対応していないため、イベント本文、拡張プロパティ、自前DBなどを使用した別の関連付け方式が必要です。