業務システム

Google Calendar APIの使い方|OAuth・サービスアカウント認証と予定作成・空き時間取得・プッシュ通知の実装例

予約管理システム開発の重要性

Google Calendar APIは、Googleカレンダーの予定やカレンダーをHTTPのREST呼び出しで読み書きするためのAPIです。予約システムや社内ツールから予定を作る、担当者の空き時間を調べる、カレンダー側の変更を受け取って自社のデータへ反映する、といった連携に使います。この記事では、認証方式の選び方から、Pythonで予定を取得・作成するコード、freeBusyによる空き時間の取得、watchとsyncTokenによる変更通知の受け取り方、403・429・410エラーへの対処までを、Googleの公式ドキュメント(2026年11月時点)に沿って説明します。

まとめ:Google Calendar APIで予定の取得・作成・空き確認・変更通知を組む手順

  • 認証:利用者本人のカレンダーを触るならOAuth 2.0のユーザー認可、社内のWorkspaceの全員分を裏で処理するならサービスアカウントとドメイン全体の委任。参加者を招待するにはサービスアカウント単体では足りず、委任が要る。
  • 最初の1本:Cloudコンソールで API を有効化し、OAuthクライアントを作り、google-api-python-clientでevents().list()を呼ぶ。
  • 予定の作成:events.insertにstartとendを渡す。時刻はオフセット付きRFC3339かtimeZoneの指定が必須。
  • 空き時間:freeBusy.queryは予定の中身を返さず、埋まっている時間帯だけを返す。予約枠の計算に向く。
  • 変更通知:watchの通知には本文が無い。通知を合図にsyncToken付きで差分を取り直し、410が返ったら全件同期をやり直す。
  • 上限:2026年5月1日以降に作ったプロジェクトは毎分10,000リクエスト・ユーザーごと毎分600リクエスト。1日100万リクエストを超える分は課金対象になる予定。

Google Calendar APIでできることと5つのリソース・クォータ・料金の前提

Google Calendar APIの概要によると、このAPIはGoogleカレンダーのWeb画面でできる操作のほとんどをRESTで公開しています。ベースURLはhttps://www.googleapis.com/calendar/v3で、HTTPを直接呼ぶ方法とGoogleのクライアントライブラリを使う方法があります。

予約連携のevents・calendars・calendarListと設定・権限

APIが扱うリソースは5種類です。予約システムとの連携で実際に呼ぶのは、ほぼeventsとfreeBusyだけになります。

リソース 中身 予約連携での用途
events 個々の予定 予約の書き込み・変更・取得
calendars カレンダー自体の情報 予約専用カレンダーの作成
calendarList 利用者の一覧に載るカレンダー 担当者のカレンダーID取得
settings 利用者の設定 既定のタイムゾーン確認
acl 共有の権限 サービスアカウントへの共有

空き時間の問い合わせ(freeBusy)はリソースとは別に、独立したエンドポイントとして個別に提供されています。カレンダーの表示部品が欲しいだけならAPIを直接組むより、FullCalendarの導入・使い方と日本語化のような表示ライブラリと組み合わせるほうが工数を抑えられます。

2026年5月以降の新規プロジェクトに適用されるクォータと課金のしきい値

クォータのページは、2026年5月1日以降に作成したCloudプロジェクトに次の上限を示しています。それより前から使っているプロジェクトは従来のクォータのままです。

  • プロジェクトあたり毎分10,000リクエスト
  • プロジェクト内のユーザーごとに毎分600リクエスト(1分のスライディングウィンドウで集計)
  • 1日1,000,000リクエストがしきい値で、超えた分は課金される予定。しきい値の引き上げ申請はできない

しきい値の内側なら追加料金はかかりません。課金の詳細は2026年中に公表され、変更の90日以上前に通知するとされています。スタッフ50人のカレンダーを毎分ポーリングしても1日7万2千回なので、通常の予約連携でしきい値に届くことはまずありません。届くとすれば、通知を使わずに全員分を数秒おきに読む設計です。

認証方式の選び方:ユーザーのOAuth認可とサービスアカウント・ドメイン全体の委任

Calendar APIは個人の予定を扱うため、ほぼすべての呼び出しにOAuth 2.0のアクセストークンが要ります。作れる機能は、どの立場でトークンを取得するか次第です。OAuthの認可フローそのものはOAuth 2.0の仕組みと認可フローで説明しています。

利用者ごとのOAuth・サービスアカウント・委任付きサービスアカウントの比較表

方式 向く用途 参加者の招待 導入の手間
ユーザーのOAuth認可 利用者が自分のカレンダーを連携 できる 同意画面と審査
サービスアカウント単体 共有された予約用カレンダーの読み書き できない カレンダーの共有設定
サービスアカウント+委任 Workspace内の全社員分を代理で操作 できる 管理者による委任設定

外部の利用者に自分のGoogleアカウントを連携してもらうなら、ユーザーのOAuth認可しかありません。スコープの一覧にはcalendar(全権限)からcalendar.freebusy(空き時間だけ)まで20種類が並び、公式は「できるだけ狭いスコープを選ぶ」よう求めています。広いスコープを使う公開アプリは審査(verification)の対象になるため、空き時間だけ見たいならcalendar.freebusy、自分で作った予定だけ触るならcalendar.events.ownedに絞ります。

サービスアカウント単体で参加者を招待できない制約と共有設定の手順

社内の予約用カレンダーを1つ用意してシステムから書き込むだけなら、サービスアカウントが手軽です。カレンダーの「特定のユーザーと共有」にサービスアカウントのメールアドレス(xxx@プロジェクトID.iam.gserviceaccount.com)を追加し、「予定の変更」以上の権限を与えれば、そのカレンダーIDを指定して読み書きできます。

ただしevents.insertのリファレンスには、サービスアカウントが参加者リストを設定するにはドメイン全体の委任が必要と書かれています。予約した顧客に招待メールを送りたい要件があるなら、Workspaceの管理者がサービスアカウントのドメイン全体の委任を設定し、コード側で代理するユーザーを指定します。個人のGmailアカウントには委任の仕組みが無いので、この要件は満たせません。その場合は招待を使わず、予約確認のメールを自社システムから送る設計に切り替えます。

検証環境の準備:CloudコンソールでのAPI有効化・同意画面・認証情報の作成

Python クイックスタートの前提は、Python 3.10.7以上、Google Cloudのプロジェクト、Googleカレンダーが使えるアカウントです。手順は次のとおりです。

  1. Google Cloudコンソールでプロジェクトを選び、Google Calendar APIを有効にする。
  2. 「Google Auth platform」の「Branding」でアプリ名とサポートメールを入力し、対象者を選ぶ(社内のWorkspaceだけで試すなら「Internal」)。
  3. 「Clients」で「Create Client」を選び、種類を「Desktop app」にして作成し、JSONをcredentials.jsonとして保存する。
  4. ライブラリをインストールする。
python3 -m pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

サービスアカウントで動かす場合は、手順2・3の代わりに「サービスアカウント」を作成して鍵のJSONを発行します。鍵ファイルはパスワードと同じ扱いで、リポジトリに置かず、本番ではSecret Managerなどから読み込む運用です。認証情報の種類ごとの作り方はGoogle Workspaceの認証情報作成ガイドにまとまっています。

Pythonで予定一覧を取得し、events.insertで予約の予定を作成するコード

クイックスタートのコードを土台に、書き込みもできるスコープへ広げたのが次の例です。初回だけブラウザが開いて同意を求め、以後はtoken.jsonに保存したリフレッシュトークンで動きます。スコープを変えたらtoken.jsonを削除して同意を取り直します。

import datetime
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/calendar.events"]

def get_service():
    creds = None
    try:
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    except FileNotFoundError:
        pass
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
            creds = flow.run_local_server(port=0)
        with open("token.json", "w") as f:
            f.write(creds.to_json())
    return build("calendar", "v3", credentials=creds)

service = get_service()

# 直近10件の予定を開始時刻順に取得する
now = datetime.datetime.now(tz=datetime.timezone.utc).isoformat()
events = service.events().list(
    calendarId="primary", timeMin=now, maxResults=10,
    singleEvents=True, orderBy="startTime",
).execute().get("items", [])
for e in events:
    print(e["start"].get("dateTime", e["start"].get("date")), e.get("summary"))

# 予約の予定を1件作る
body = {
    "summary": "初回相談(オンライン)",
    "start": {"dateTime": "2026-12-03T10:00:00", "timeZone": "Asia/Tokyo"},
    "end":   {"dateTime": "2026-12-03T11:00:00", "timeZone": "Asia/Tokyo"},
    "attendees": [{"email": "[email protected]"}],
}
created = service.events().insert(
    calendarId="primary", body=body, sendUpdates="all"
).execute()
print(created["id"], created["htmlLink"])

singleEvents=Trueは繰り返し予定を1回ずつの予定に展開する指定で、orderBy="startTime"はこれを付けたときだけ使えます。予約システムで「その日に埋まっている予定」を数えるなら、展開しておかないと毎週の定例が1件としか数えられません。

時刻の書き方とsendUpdatesの値で起きやすい2つの不具合

startとendは必須です。dateTimeはRFC3339形式で、timeZoneを書かないならオフセット(+09:00)が必要です。終日の予定はdateにyyyy-mm-ddを入れ、endは最終日の翌日にします(endはその時刻を含まない扱いのため)。繰り返し予定ではtimeZoneの指定が必須とされています。

sendUpdatesはall・externalOnly・noneの3値です。リファレンスには、noneにすると外部のカレンダーとの同期が崩れたり予定が消えたりする可能性があると注記されています。顧客を参加者に入れるならallかexternalOnlyを明示し、既定値に任せないのが安全です。

freeBusy.queryで複数の担当者カレンダーの空き時間を取得して予約枠を計算する

freeBusy.queryのリファレンスによると、このエンドポイントは指定した期間のうち埋まっている時間帯(busy)だけを返し、予定のタイトルや参加者は返しません。担当者の私用の予定を予約システム側へ持ち込まずに済むので、空き枠の計算にはこちらを使います。

body = {
    "timeMin": "2026-12-03T09:00:00+09:00",
    "timeMax": "2026-12-03T18:00:00+09:00",
    "timeZone": "Asia/Tokyo",
    "items": [{"id": "[email protected]"}, {"id": "[email protected]"}],
}
res = service.freebusy().query(body=body).execute()
for cal_id, cal in res["calendars"].items():
    if cal.get("errors"):
        print(cal_id, "取得失敗", cal["errors"])   # 共有されていないカレンダーなど
        continue
    for b in cal["busy"]:
        print(cal_id, b["start"], "-", b["end"])

1回で問い合わせられるカレンダーはcalendarExpansionMaxの上限で50件、グループを展開するときのメンバーはgroupExpansionMaxの上限で100件です。権限の無いカレンダーはエラーにならず、そのカレンダーのerrorsに理由が入るだけなので、busyが空でも「空いている」と判定する前にerrorsを確かめます。ここを見落とすと、共有設定が外れた担当者の枠がすべて空きに見え、二重予約の原因になります。

空き枠は、営業時間からbusyの区間を引き、予約の長さ(30分・60分など)で区切って求めます。返ってくるbusyのendはその時刻を含まないので、10:00終わりの予定の直後の10:00開始の枠は空きとして扱えます。

プッシュ通知(watch)とsyncTokenでカレンダー側の予定変更を受け取る実装

担当者がGoogleカレンダーの画面で予定を動かしたことを予約システムに反映するには、プッシュ通知のガイドにあるwatchで通知チャネルを作ります。受信側のURLはHTTPSで、有効なSSL証明書が必要です。自己署名や期限切れの証明書には送られません。

POST https://www.googleapis.com/calendar/v3/calendars/primary/events/watch
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "id": "resv-sync-sato-20261203",
  "type": "web_hook",
  "address": "https://example.co.jp/hooks/gcal",
  "token": "tenant=42"
}

idはチャネルを識別する64文字以内の文字列、tokenは通知のたびにそのまま返ってくる256文字以内の任意の値で、どのテナントや担当者の通知かを見分けるのに使えます。通知はX-Goog-Channel-ID・X-Goog-Resource-State・X-Goog-Resource-IDなどのヘッダーだけで届き、本文はありません。最初に届くX-Goog-Resource-State: syncはチャネル開設の合図で、以後の変更はexistsで届きます。受信エンドポイントの作り方はWebhookの仕組みとAPIとの違いを参照してください。

通知を合図にsyncTokenで差分を取り直し、410で全件同期に戻る処理

通知に中身が無いので、受け取ったらevents.listを呼んで何が変わったかを確かめます。同期のガイドのとおり、初回の全件取得で最後のページに付くnextSyncTokenを保存しておき、以後はsyncTokenに渡すと前回からの差分(削除された予定を含む)だけが返ります。

from googleapiclient.errors import HttpError

def incremental_sync(service, cal_id, store):
    params = {"calendarId": cal_id, "singleEvents": True}
    token = store.get_sync_token(cal_id)
    if token:
        params["syncToken"] = token
    page = None
    while True:
        try:
            res = service.events().list(pageToken=page, **params).execute()
        except HttpError as e:
            if e.resp.status == 410:          # トークン失効
                store.clear(cal_id)           # 手元のデータを消して
                return incremental_sync(service, cal_id, store)  # 全件同期からやり直す
            raise
        for ev in res.get("items", []):
            if ev.get("status") == "cancelled":
                store.delete(ev["id"])
            else:
                store.upsert(ev)
        page = res.get("nextPageToken")
        if not page:
            store.save_sync_token(cal_id, res["nextSyncToken"])
            return

syncTokenを使うリクエストは、初回と同じクエリパラメータでそろえる必要があり、timeMinなどを足すと400で拒否されます。チャネルには有効期限があり、自動では延長されません。期限の前に新しいidでwatchを呼び直し、不要になったチャネルはchannels/stopにidとresourceIdを渡して止めます。期限切れに気付かず通知が止まる事故を防ぐため、1日1回は通知と無関係に差分同期を走らせる保険を入れておきます。

403・429のusageLimitsと401・410エラーへの対処と指数バックオフの実装

エラーのガイドから、連携で実際に出やすいものを対処の方針ごとに並べます。

コード 主な原因 対処
401 アクセストークンの期限切れ・無効 リフレッシュトークンで再取得、だめなら再認可
403 / 429 usageLimits(レート超過) 指数バックオフで再試行
409 同じIDの予定が既にある 新しいIDにするか更新を使う
410 同期トークンの失効 手元を消して全件同期
412 If-Matchのetagが古い 取り直して変更を当て直す
500 サーバー側の一時的な不具合 指数バックオフで再試行

クォータのページが示す待ち時間の式はmin((2^n + random_number_milliseconds), maximum_backoff)で、nは再試行のたびに1増やし、乱数は1,000ミリ秒以下、上限は32秒か64秒が目安です。

import random, time

def call_with_backoff(request, max_retry=6, max_backoff=32):
    for n in range(max_retry):
        try:
            return request.execute()
        except HttpError as e:
            if e.resp.status not in (403, 429, 500, 503):
                raise
            wait = min(2 ** n + random.random(), max_backoff)
            time.sleep(wait)
    raise RuntimeError("再試行の上限に達しました")

403はレート超過以外にも権限不足で返るので、本番ではエラー本文のreasonがrateLimitExceededやuserRateLimitExceededのときだけ再試行の対象にします。409を避けるには、予約IDから予定IDを決めてevents.insertに渡す方法が有効です(指定できる予定IDは英小文字のa〜vと数字の組み合わせで5〜1024文字)。通信が切れて再送しても同じIDなので、二重に作られず409で止まります。

Calendar API連携を自社で組むか予約管理システムに任せるかの判断基準

ここまでのコードは数十行ですが、本番の連携で手間がかかるのは、チャネルの更新、トークンの保管と失効対応、410からの復旧、担当者の退職や共有解除の検知といった周辺です。

Calendar APIを直接組んでよいのは、次の条件がそろう場合です。カレンダーが社内のWorkspaceにあり管理者が委任を設定できること、連携の方向が「予約システムからカレンダーへ書き出す」片方向で足りること、運用担当が通知の停止に気付ける監視を持てることです。逆に、顧客が自分の個人アカウントを連携する、双方向に同期して画面上の移動をそのまま予約変更として扱う、という要件があるなら、自前で組むのは見送ります。削除・繰り返し予定・タイムゾーンの例外処理がそのまま保守費用として残るからです。

片方向・空き時間参照・双方向の3方式の違いと、カレンダー運用をやめる境界は予約管理システムのカレンダー連携|同期方式3つの選び分けで整理しています。一創では、Googleカレンダーと連携する予約の仕組みを要件に合わせて設計・実装する予約管理システム開発を行っています。

よくある質問

Google Calendar APIを使い始めるときによく出る質問をまとめました。

Google Calendar APIは無料で使えますか?

1日あたりプロジェクトごとに1,000,000リクエストまでは追加料金なしで使えます。このしきい値を超えた分は課金される予定で、詳細は2026年中に公表され、変更の90日以上前に通知されるというのがクォータのページの記載です。毎分のクォータ(プロジェクト10,000・ユーザーごと600)を超えると料金ではなく403か429のエラーになります。

APIキーだけでGoogle Calendar APIを呼べますか?

個人や社内のカレンダーの予定はOAuth 2.0のアクセストークンが必要で、APIキーだけでは読めません。公開設定にしたカレンダーの予定を読むだけなら、スコープ一覧に公開カレンダー用のcalendar.events.public.readonlyが用意されています。書き込みや非公開の予定を扱うなら、ユーザーの認可かサービスアカウントを使います。

Google Apps Script(GAS)のCalendarAppとAPIはどちらを使うべきですか?

自分のカレンダーへの簡単な一括登録や、スプレッドシートと組み合わせた社内の小さな自動化ならGASのほうが早く作れます。外部のWebサービスから呼ぶ、多数の利用者を扱う、変更通知を受けるといった要件ならCalendar APIの出番です。GASを業務で使うときの権限と公開設定の注意はGASのセキュリティ|権限・公開設定・管理者統制で説明しています。

サービスアカウントで作った予定が自分のカレンダーに表示されないのはなぜですか?

calendarId="primary"のままだと、サービスアカウント自身のカレンダーに予定が作られるためです。自分のカレンダーをサービスアカウントのメールアドレスに共有し、そのカレンダーID(多くはメールアドレス)をcalendarIdに指定します。Workspaceでドメイン全体の委任を使う場合は、代理するユーザーを指定すればそのユーザーのprimaryに作られます。

Googleカレンダーの変更を通知ではなく定期的に取得してもよいですか?

担当者が数人で数分の遅れを許容できるなら、syncToken付きのevents.listを数分おきに呼ぶ方式でも動きます。差分だけが返るので負荷は小さく、HTTPSの受信口も要りません。ただし人数が増えるほどユーザーごと・プロジェクトごとのクォータに近づくので、規模が大きくなったらwatchの通知を合図に取りに行く形へ切り替えます。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2025.12.19 コラム アンダーマイニング効果とは?具体例と報酬でやる気が下がる条件、エンハンシング効果との違い
  2. 2026.11.20 テックブログ MAI Code 2とは?Flashとの違い・料金・GitHub Copilotでの使い方【2026年11月】
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.20 テックブログ 六花亭の不正アクセス:決済画面の改ざんでカード情報約8,000件、対象期間と改ざん検知の手順【11月20日時点】
  5. 2026.11.20 テックブログ 福岡銀行の不正アクセス:FFGインダストリーズ1,221先の漏えい可能性と、分析ツールに認証情報を渡さない実装

RELATED POSTS 関連記事

目次