Googleカレンダー連携 ヘルプ

概要

このページでは Googleカレンダーとの 2 種類の連携を管理します。

機能 方向 用途
書き込み連携 UnlockOS → Googleカレンダー UnlockOS のネイティブ予約を自動でカレンダーに書き込み、空き状況を一元管理する
読み取りカレンダー Googleカレンダー → UnlockOS Spacemarket・インスタベース・Spacee などが書き込んだカレンダーを読み取り、予約を UnlockOS に取り込んでチェックイン・鍵を発行する

どちらの機能も Googleアカウントの接続が前提です。先に「Googleカレンダーを連携」ボタンで OAuth 接続を完了させてから読み取りカレンダーを設定してください。

Google Workspace 検証ステータス: 検証申請中。検証完了までは、Google OAuth 同意画面でテストユーザーとして登録された Google アカウントのみ利用できます（上限 100 アカウント）。利用を希望する場合はサポートまでご連絡ください。

アクセス方法

接続設定 → 外部連携 → Googleカレンダー カードをクリック

旧 URL /google-calendar-connection にアクセスした場合も、新しい URL /integrations/google-calendar に自動でリダイレクトされます。

ステップ 1: Googleアカウントの接続

書き込み先カレンダー ID の設定

連携ボタンを押す前に、UnlockOS の予約イベントをどのカレンダーに書き込むか確認してください。

設定値 説明
primary Googleアカウントのメインカレンダー（デフォルト）
専用カレンダーの ID 特定のカレンダーにのみ書き込みたい場合

専用カレンダーの ID を調べる手順：

  1. パソコンで Google Calendar を開く
  2. 左サイドバーで対象カレンダーの「⋮」（その他のオプション）→「設定と共有」をクリック
  3. 「カレンダーの統合」セクションに表示される「カレンダー ID」をコピーする（例: xxxxxxx@group.calendar.google.com）

OAuth 同意フロー

  1. カレンダー ID を入力（通常は primary のままで OK）
  2. 「Googleカレンダーを連携」 ボタンをクリック
  3. Google の OAuth 同意画面に遷移
  4. 要求されているアクセス権限を確認して「続行」をクリック
  5. UnlockOS の設定画面に自動で戻り、ステータスが「✓ 連携中」に変わる

要求するアクセス権限

スコープ 内容
https://www.googleapis.com/auth/calendar.events Googleカレンダーのイベント作成・更新・削除（UnlockOS 予約の書き込み先）
https://www.googleapis.com/auth/calendar.calendarlist.readonly Googleアカウントのカレンダー一覧の読み取り（読み取りカレンダーセクションのドロップダウン表示に使用）

2 つのスコープは 1 回の OAuth フローでまとめて付与されます。calendarlist.readonly は読み取り専用で、カレンダーの名前と ID 一覧の取得にのみ使用します。イベント内容は読み取りません。

セキュリティ設計（CSRF 保護）

「連携」ボタンをクリックした際、ブラウザの sessionStorage に CSRF 対策用のワンタイムトークンが一時保存されます。Google の同意画面から戻ったとき、このトークンと施設 ID が一致することを検証してから連携を完了します。

プライベートブラウジングモードでは sessionStorage が利用できないため、連携を開始できません。通常のブラウザウィンドウで操作してください。

ステップ 2: 読み取り — 他社プラットフォームの予約を取り込む

Googleアカウント接続後、接続ステータスの下に 「読み取りカレンダー (他社予約の取り込み)」 セクションが表示されます。ここでは、Spacemarket やインスタベースなどが書き込む Googleカレンダーを部屋に紐付けることができます。UnlockOS がそのカレンダーのイベントを読み取り、予約として取り込み、チェックインと鍵発行を自動で行います。

前提条件: Googleアカウントが接続済みの場合のみ表示されます。

新しいバインディングを追加する

  1. 読み取り元カレンダー — ドロップダウンから対象カレンダーを選択します。Googleアカウントの全カレンダーが一覧表示されます。
    • ドロップダウンが空の場合は、後述の「読み取りカレンダーのドロップダウンが空または表示されない」を参照してください。
  2. 紐付ける部屋 — このカレンダーの予約を割り当てる部屋を選択します。
  3. 「追加」 ボタンをクリックします。

追加が完了すると、下の一覧に新しいバインディングが表示されます。

自動同期

バインディングを作成すると、UnlockOS は約 30 分ごとに紐付けたカレンダーを自動で読み取ります。新しいイベントが見つかると予約として取り込まれます。

手動同期

バインディングカードの 「同期」 ボタンをクリックすると、今すぐカレンダーを読み取り、新しいイベントを予約として取り込みます。同期後、最終同期日時と取り込み件数が更新されます。

バインディングを解除する

バインディングカードの 「解除」 ボタンをクリックして確認ダイアログで確定します。

解除すると直ちに：

  • そのカレンダーの自動同期が停止します。
  • このバインディングから取り込んだ まだチェックインされていない 予約がキャンセルされます（チェックイン済みの予約はそのまま残ります）。

バインディング一覧の見方

登録済みのバインディングはカードで表示されます。各カードの内容：

項目 説明
カレンダー ID 読み取り元 Googleカレンダーの ID
紐付ける部屋 予約が割り当てられる部屋名
最終同期 直近の同期が完了した日時
ステータスバッジ 同期済み / エラー / 未同期

ステップ 3: 書き込み — UnlockOS の予約を Googleカレンダーに反映

Googleアカウント接続後、UnlockOS のネイティブ予約は自動的に [UnlockOS] Reserved というタイトルのブロックイベントとして Googleカレンダーに書き込まれます。同じカレンダーを参照する他のチャネルからの二重予約を防ぐ効果があります。

注意: UnlockOS で予約が作成・変更されると、通常は数秒以内に Googleカレンダーへの即時反映が試みられます。即時反映に失敗した場合は、バックストップ同期（pg_cron ジョブ、約 5 分ごと）が自動でリトライします。いずれもベストエフォートであり、リアルタイムの反映は保証されません。

書き込まれるイベント

予約の変化 Googleカレンダーの動作
予約確定・チェックイン イベントを作成（または既存イベントを更新）
予約変更（日時・部屋） 既存イベントを更新
キャンセル・完了・競合による無効化 イベントを削除

イベントタイトルは [UnlockOS] Reserved、説明欄に予約確認番号と管理 URL が入ります。

書き込み対象外の予約

  • iCal / OTA / PMS 経由の予約: 外部システムが書き込んだ予約を再度 Googleカレンダーに送ると循環書き込みが発生するため、除外されています
  • 過去日の予約: 過去の時間帯の予約は同期対象外です
  • 下書き・保留中の予約: confirmed または checked_in 状態のものだけが同期されます

重要な運用ルール: 1部屋 = 1つの取り込みチャネル

同じ部屋のカレンダーを、iCal連携と Googleカレンダー読み取りの両方で同時に接続しないでください。

同じ部屋の予約カレンダーを iCal連携と Googleカレンダー読み取りバインディングの両方で登録すると、UnlockOS は同じ予約を二重に取り込みます。これにより 偽の二重予約の競合 と重複予約が発生します。

各部屋につき、取り込みチャネルを 1 つだけ選んでください:

チャネル 使うべき場合
iCal連携（?tab=ical） OTA が iCal（.ics）エクスポート URL を提供している場合
Googleカレンダー読み取りバインディング（このページ） OTA が Googleカレンダーに直接書き込む場合（例: Spacemarket、インスタベース）

同じ部屋で両方を使っている場合は、どちらか一方を削除してください。iCal フィードを削除するか、Googleカレンダーのバインディングを解除します。

ページの状態

このページは連携状況に応じて 3 種類の表示になります。

1. 未接続

まだ連携していない施設に表示されます。

  • 書き込み先カレンダー ID 入力欄（初期値: primary）
  • 「Googleカレンダーを連携」 ボタン

2. 連携中

OAuth が完了し、正常に連携されている施設に表示されます。緑色のボーダーで囲まれたセクションに以下の情報が表示されます。

項目 説明
Googleアカウント 連携に使用した Google アカウントのメールアドレス
書き込み先カレンダー 予約イベントを書き込んでいるカレンダー ID
連携開始日時 OAuth を完了した日時
未同期 / 失敗 pending（同期待ち）件数 / failed（失敗・リトライ中）件数

このセクションには 「連携を解除」 ボタンも表示されます。

3. 要再認可

Google アカウント側でアクセスが取り消された状態です。ページ上部に赤いバナーが表示され、失敗した同期件数とともに 「再認可する」 ボタンが表示されます。

再認可バナーが出る主な原因：

  • Googleアカウントの設定でアプリのアクセスを手動で取り消した
  • Google Workspace 管理者がサードパーティアプリのアクセスをブロックした
  • Google Workspace 検証がまだ完了しておらず、テストユーザー上限（100 アカウント）に達した

連携の解除

  1. 連携中セクションの 「連携を解除」 ボタンをクリック
  2. 確認ダイアログで「OK」をクリック

解除すると直ちに：

  • 新しい予約の同期が停止する
  • 保留中・失敗中の同期がすべて無効化される

解除後 30 日以内に、保管中のリフレッシュトークン（認可情報）が Vault から完全に削除されます。

既に書き込まれたイベントはGoogleカレンダー側に残ります。 不要な場合は、Googleカレンダー上で手動で削除してください。

トラブルシューティング

「再認可が必要です」バナーが表示される

Google アカウント側でアクセスが取り消されました。

対処方法：

  1. 「再認可する」 ボタンをクリックして OAuth フローを再開する
  2. 解決しない場合は、Google アカウントの設定 → セキュリティ → 「サードパーティ製アプリとサービス」で UnlockOS のアクセスを確認する
  3. Google Workspace をご利用の場合、Workspace 管理者にサードパーティアプリのポリシーを確認する

Googleカレンダーにイベントが出ない（書き込み連携）

以下を順番に確認してください：

  1. ステータスが「✓ 連携中」になっているか — 「要再認可」や「未接続」の場合は先に連携を完了させる
  2. ネイティブ予約か — OTA・iCal・PMS 経由の予約は書き込み連携の対象外
  3. 書き込み先カレンダー ID が正しいか — primary か、設定した専用カレンダー ID を確認
  4. 数十秒〜数分待ったか — 同期は通常数秒以内に反映されますが、ベストエフォートです。失敗した場合は約 5 分のバックストップ同期で補完されます
  5. 「失敗」件数が増えていないか — 連携中セクションの「未同期 / 失敗」カウンターを確認し、失敗が続く場合はサポートに問い合わせる

連携ボタンをクリックしても何も起きない

ブラウザの sessionStorage が無効な場合（プライベートブラウジングなど）、エラーメッセージが表示されます。通常のブラウザウィンドウで再度お試しください。

Google 同意画面でキャンセルした

「接続をキャンセルしました」というメッセージが表示され、連携は完了しません。改めて「Googleカレンダーを連携」ボタンから操作してください。

同じアカウントで再連携したい

いったん「連携を解除」してから、再度「Googleカレンダーを連携」を行ってください。同意画面で同じ Google アカウントを選択できます。

読み取りカレンダーのドロップダウンが空または表示されない

カレンダー一覧の読み取り権限（calendar.calendarlist.readonly スコープ）が付与されていない場合にドロップダウンが空になります。

対処方法：

  1. 既存の連携を 「連携を解除」 して削除する
  2. 改めて 「Googleカレンダーを連携」 で再接続する（再認可で両方のスコープが付与されます）
  3. 再接続後、読み取りカレンダーのドロップダウンにカレンダー一覧が表示されます

再接続までの間は、カレンダー ID を手入力してバインディングを追加できます（入力欄にカレンダー ID を直接入力してください）。

読み取りカレンダーで「同期」を押してもイベントが取り込まれない

以下の順番で確認してください：

  1. カレンダー ID が正しいか — バインディングに表示されているカレンダー ID とスペース予約サービス側の設定を照合する
  2. イベントの開始日が未来か — 過去日のイベントは取り込まれません
  3. Googleアカウントが「連携中」か — 「要再認可」バナーが出ている場合は先に再認可する
  4. バインディングカードにエラーが表示されていないか — エラー文を確認してサポートに問い合わせる

取り込んだ予約をキャンセル・変更したい

Googleカレンダー読み取りバインディングで取り込まれた予約は、**Googleカレンダーが正しい情報の源（source of truth）**です。そのような予約をキャンセルまたは変更する場合は、UnlockOS の管理画面ではなく Googleカレンダー上でイベントを編集・削除してください。次回の自動同期（読み取り方向は約 30 分ごと）または手動同期のタイミングで UnlockOS に反映されます。

同じ予約が二重に登録されている

同じ部屋のカレンダーを iCal連携と Googleカレンダー読み取りバインディングの両方で同時に接続している場合によく起きる症状です。上記の「重要な運用ルール: 1部屋 = 1つの取り込みチャネル」を参照し、どちらか一方の接続を削除してください。

バックエンド動作（技術的リファレンス）

書き込み連携の同期の仕組み

UnlockOS での予約の状態変化は、データベーストリガーが自動的に検知し pending（同期待ち）フラグを立てます。フラグが立った瞬間に別の AFTER トリガーが gcal-event-sync Edge Function に即時リクエスト（pg_net.http_post）を送信します。このリクエストはトランザクションのコミット後に非同期で実行されます。

つまり、予約の作成・変更・キャンセル後、通常は数秒以内に Googleカレンダーに反映されます。即時リクエストが失敗した場合（Vault シークレット未設定・ネットワーク障害など）、5 分ごとのバックグラウンドジョブ（pg_cron）がバックストップとして残っている pending 行をリトライします。いずれもベストエフォートであり、リアルタイムの反映を保証するものではありません。

リトライとエラー処理

同期に失敗した場合、バックグラウンドジョブが最大 5 回まで自動でリトライします。5 回失敗した予約は DLQ（デッドレターキュー）ビュー（gcal_event_sync_dlq）に記録され、運用チームが確認できます。

認可情報の安全な保管

Google のリフレッシュトークン（長期的なアクセス権限を持つ資格情報）は、ブラウザには一切送信されません。Supabase Vault（暗号化ストレージ）に施設ごとに安全に保存されます。

よくある質問

Q: 連携を解除した後、すでに書き込まれたイベントはどうなりますか?

A: Googleカレンダー側に残ります。UnlockOS から削除は行いません。不要な場合は Googleカレンダーで手動削除してください。

Q: Googleカレンダーの予約を UnlockOS に取り込めますか?

A: はい。読み取りカレンダー 機能を使うと取り込めます。Spacemarket・インスタベースなどが書き込む Googleカレンダーをバインディングとして登録すると、そのイベントが予約として UnlockOS に取り込まれます。なお、書き込み連携 自体は引き続き一方向です。UnlockOS のネイティブ予約は Googleカレンダーに書き込まれますが、その逆（Googleカレンダー側の変更を UnlockOS に反映）はしません。

Q: 施設ごとに別々のカレンダーを使い分けられますか?

A: はい。施設ごとに独立した連携を設定できます。施設 A は primary、施設 B は専用カレンダー ID、というように別々に設定可能です。

Q: 複数の Google アカウントを使えますか?

A: 1 施設につき 1 つの Google アカウントのみ連携できます。別アカウントに切り替えたい場合は、いったん解除してから再連携してください。

Q: リフレッシュトークン（認可情報）はどこに保管されていますか?

A: Supabase Vault（暗号化された内部ストレージ）に保管されます。ブラウザには一切送信されません。連携解除後 30 日以内に自動削除されます。

Q: 認可できるのは誰ですか?

A: 施設オーナー・組織オーナー・Platform Admin のみが OAuth 連携を行えます。施設メンバーはこの設定にアクセスできません。

Q: テストユーザー制限とは何ですか?

A: UnlockOS の Google Workspace 検証がまだ完了していない間は、Google アカウントをテストユーザーとして事前登録しなければ連携できません（上限 100 アカウント）。検証完了後はこの制限がなくなります。テストユーザー登録はサポートまでご連絡ください。

Q: 読み取りカレンダーで取り込んだ予約はどこで確認できますか?

A: 通常の予約管理ダッシュボードの予約一覧に表示されます。ソースが adapter:gcal と記録されているので、他チャネルの予約と区別できます。

Q: 読み取りカレンダーの「解除」をすると、取り込んだ予約はどうなりますか?

A: バインディングを解除すると、そのカレンダーから取り込んだ「まだチェックインされていない予約」がキャンセルされます。チェックイン済みの予約は影響を受けません。

Q: ドロップダウンにカレンダーが表示されません

A: Googleアカウント接続時にカレンダー閲覧の権限が付与されていない場合、ピッカーは空になります。一度「連携を解除」して再連携（再認可）してください。再認可後はカレンダー一覧が取得できるようになります。それまでの間はカレンダー ID を手入力してバインディングを追加できます。

Q: 同期エラーが表示されます

A: バインディングカードのエラーテキストを確認してください。解決しない場合は、一度 Googleアカウントを「連携を解除」して再連携（再認可）してください。再認可でトークンが更新され、多くのエラーが解消されます。

Q: 同じカレンダーを複数の部屋に紐付けてもよいですか?

A: 技術的には可能ですが、同じイベントが各部屋に重複して予約として取り込まれます。意図した動作でない場合、1 カレンダーにつき 1 部屋の紐付けを推奨します。重複バインディングがある場合はカードに ⚠ 警告が表示されます。

Q: iCal連携と Googleカレンダー読み取りを同じ部屋で併用してもよいですか?

A: いいえ。同じ部屋で両方を使うと、同じ予約が二重に取り込まれて偽の二重予約の競合が発生します。各部屋につき 1 つのチャネルを選択してください。上記の「重要な運用ルール: 1部屋 = 1つの取り込みチャネル」を参照してください。

連携予約の鍵について

  • 連携で取り込んだ各イベントには、その予約に割り当てられた部屋の鍵（部屋自身のスマートロック）が 発行されます。チェックイン設定で指定したユニットの鍵ではありません。複数部屋の施設でも、各ゲストは 自分の部屋の鍵を受け取ります。
  • 鍵は事前に発行され、KEYVOX がチェックインの約72時間前からロックへ配信します。
  • 連携予約はキオスクで無料です。割り当てたチェックイン設定に料金プランを選んでも課金されません。
  • カレンダーがスマートロック未割り当ての部屋に紐づいている場合、チェックインは拒否されます （フォールバックの鍵は発行されません）。設定不備が見えるようにするためです。

関連ページ