---
title: "Google Calendar APIの使い方｜OAuth・サービスアカウント認証と予定作成・空き時間取得・プッシュ通知の実装例"
url: "https://www.issoh.co.jp/tech/details/20073/"
published: 2026-11-22
updated: 2026-11-22
categories: ["業務システム"]
publisher: "株式会社一創"
---

# 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の概要](https://developers.google.com/workspace/calendar/api/guides/overview)によると、この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の導入・使い方と日本語化](https://www.issoh.co.jp/tech/details/4742/)のような表示ライブラリと組み合わせるほうが工数を抑えられます。

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

[クォータのページ](https://developers.google.com/workspace/calendar/api/guides/quota)は、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の仕組みと認可フロー](https://www.issoh.co.jp/tech/details/8369/)で説明しています。

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

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

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

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

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

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

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

[Python クイックスタート](https://developers.google.com/workspace/calendar/api/quickstart/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の認証情報作成ガイド](https://developers.google.com/workspace/guides/create-credentials)にまとまっています。

## 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": "customer@example.com"}],
}
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のリファレンス](https://developers.google.com/workspace/calendar/api/v3/reference/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": "sato@example.co.jp"}, {"id": "suzuki@example.co.jp"}],
}
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カレンダーの画面で予定を動かしたことを予約システムに反映するには、[プッシュ通知のガイド](https://developers.google.com/workspace/calendar/api/guides/push)にある`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との違い](https://www.issoh.co.jp/tech/details/3289/)を参照してください。

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

通知に中身が無いので、受け取ったら`events.list`を呼んで何が変わったかを確かめます。[同期のガイド](https://developers.google.com/workspace/calendar/api/guides/sync)のとおり、初回の全件取得で最後のページに付く`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エラーへの対処と指数バックオフの実装

[エラーのガイド](https://developers.google.com/workspace/calendar/api/guides/errors)から、連携で実際に出やすいものを対処の方針ごとに並べます。

| コード       | 主な原因               | 対処                     |
| --------- | ------------------ | ---------------------- |
| 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つの選び分け](https://www.issoh.co.jp/column/details/16973/)で整理しています。一創では、Googleカレンダーと連携する予約の仕組みを要件に合わせて設計・実装する[予約管理システム開発](https://www.issoh.co.jp/service/system/reservation/)を行っています。

## よくある質問

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のセキュリティ｜権限・公開設定・管理者統制](https://www.issoh.co.jp/column/details/3258/)で説明しています。

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

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

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

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

## 関連記事

- [予約管理システムのカレンダー連携｜Googleカレンダー運用の限界と同期方式3つの選び分け](https://www.issoh.co.jp/column/details/16973/)：同期方式の選び方とカレンダー運用をやめる判断基準
- [OAuth 2.0とは？仕組み・認可フローと認証との違い](https://www.issoh.co.jp/tech/details/8369/)：Calendar APIの認可で使うフローの基礎
- [Google Drive APIの使い方｜サービスアカウントと共有ドライブ、Pythonでのアップロード・検索・共有の実装例](https://www.issoh.co.jp/tech/details/20075/)：同じサービスアカウント構成でファイルを扱う兄弟記事
- [Webhookとは？読み方・仕組み・APIとの違い](https://www.issoh.co.jp/tech/details/3289/)：watchの通知を受ける受信口の仕組み
- [Webhookの作り方と実装方法｜受信側の署名検証・冪等性](https://www.issoh.co.jp/tech/details/1378/)：通知の重複や再送に耐える受信側の実装
- [FullCalendarとは？導入・使い方と日本語化](https://www.issoh.co.jp/tech/details/4742/)：取得した予定を画面にカレンダー表示する部品

---

出典: [Google Calendar APIの使い方｜OAuth・サービスアカウント認証と予定作成・空き時間取得・プッシュ通知の実装例](<https://www.issoh.co.jp/tech/details/20073/>)（株式会社一創）
