Google Calendar API ページネーションと同期

本ガイドで使用するコマンドリファレンス：ページネーション付きの予定取得には nylas calendar events list、カレンダーの列挙には nylas calendar list、ヘッドレス環境のセットアップには nylas auth config、イベント通知には nylas webhook create、スケジューリングワークフローには nylas calendar find-time を使用します。

Google Calendar API の nextPageToken と maxResults はどう動作する？

Google Calendar API の events.list では、maxResults がページサイズを設定し、nextPageToken が次のイベントページを指します。レスポンスは、特に繰り返しイベント、削除済みイベント、時間範囲フィルタが関係する場合、リクエストした件数より少ないイベントしか含まないのに次のトークンを返すことがあります。

よく検索される google calendar api nextPageToken maxResults について重要なのは、ページネーションが一度に1つのカレンダーにスコープされる点です。ユーザーが8つのカレンダーを持っている場合、同期コードにはグローバルなカーソル1つではなく、独立した8つのページネーションループと8つの保存済み同期状態が必要です。

Google Calendar API のページネーションはどう動作する？

Google Calendar API のページネーションは、イベントリストを複数の HTTP レスポンスに分割し、各レスポンスには次のページを取得するために呼び出し側が渡す nextPageToken 文字列が含まれます。events.list エンドポイントは /calendars/{calendarId}/events 配下にあるため、ページネーション状態はカレンダーごとにスコープされます。5つのカレンダーを持つユーザーには、独立した5つのページネーションカーソルが存在します。

Google Calendar API events.list ドキュメントによると、デフォルトのページサイズは250で、リクエストあたりの最大は2,500件です（Gmail の messages.list の上限500の5倍）。したがって10,000件のイベントを持つカレンダーには、最大ページサイズで最低4回、デフォルトでは40回の連続した API 呼び出しが必要です。以下のループは単一のカレンダーをページネーションします：

from googleapiclient.discovery import build

service = build("calendar", "v3", credentials=creds)

all_events = []
page_token = None

while True:
    response = service.events().list(
        calendarId="primary",
        maxResults=2500,
        pageToken=page_token,
        singleEvents=True,
        orderBy="startTime",
    ).execute()

    all_events.extend(response.get("items", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

print(f"Fetched {len(all_events)} events")

このコードがページネーションするのは1つのカレンダーです。ユーザーは通常、プライマリカレンダーに加えて共有、セカンダリ、購読カレンダーを持っているため、本番の同期クライアントはこのループを calendarList.list の結果に対する外側のループで包みます。

Google Calendar API の ETag・If-Match・412 エラーはどこで扱うべき？

Google Calendar API の ETag、If-Match、412 Precondition Failed エラーは、ページネーショントークンの問題ではなく同時実行制御の問題です。ページネーションと同期トークンの扱いは本ページで解説し、古くなったイベントの更新、events.patch、楽観的同時実行制御に関する疑問は Google API 412 エラーの修正（ETag、If-Match）を参照してください。

Google Calendar の増分同期はどう動作する？

Google Calendar の増分同期は、ページネーションの最後のレスポンス、つまり nextPageToken が存在しないページでのみ返される syncToken を使用します。このトークンをカレンダーごとに保存します。次回の同期時に events.list に syncToken として渡すと、前回の同期以降に作成、更新、削除されたイベントだけがレスポンスに含まれます。Calendar API 同期ガイドによると、これがローカルコピーを最新に保つための推奨パターンです。

syncToken が無効になると（通常は数週間の非アクティブ後、または Google がトークンをローテーションしたとき）、events.list は 410 Gone を返します。Gmail の同種の失敗は代わりに 404 を返します。コードは 410 をキャッチし、保存済みトークンを破棄して、新しい syncToken を取得するために最初から完全なページネーションを再実行する必要があります。コードパスは次のようになります：

def incremental_sync(service, calendar_id, stored_token):
    """Sync changes since stored_token, or full-sync on 410."""
    try:
        response = service.events().list(
            calendarId=calendar_id,
            syncToken=stored_token,
        ).execute()
        return response.get("items", []), response.get("nextSyncToken")
    except HttpError as e:
        if e.resp.status == 410:
            # Token invalidated — full re-paginate
            return full_paginate(service, calendar_id)
        raise

もう1つの注意点として、syncToken リクエストでは、初回ページネーションで使えるフィルタパラメータのほとんど（q（テキスト検索）、timeMin、timeMax、singleEvents など）が使用できません。singleEvents=True で同期を初期化した場合、その後のすべての増分呼び出しでも同様に省略しなければ、API は 400 Bad Request を返します。

なぜ繰り返しイベントがページネーションの問題になる？

Google Calendar は毎週のスタンドアップや毎月の全社会議を、各オカレンスごとの個別イベントではなく、繰り返しルール（RFC 5545 の RRULE）を持つ1つのイベントとして表現します。events.list エンドポイントは singleEvents パラメータによって挙動が変わります。singleEvents=False（デフォルト）では、レスポンスには繰り返しイベントがマスターレコードとしてのみ含まれます。スタンドアップは1エントリとして返され、クライアント側で展開する必要があります。singleEvents=True では、API がすべての繰り返しを個別のインスタンスに展開し、レスポンスは10〜100倍大きくなる可能性があります。

日次繰り返しの500件のマスターイベントを90日間のウィンドウで展開すると、45,000件のインスタンスになります。singleEvents なしの同じクエリは500行を返します。どちらにも正当なユースケースがあります（分析にはマスターイベント、ダッシュボードにはインスタンスが必要）が、この仕様の違いはページネーションコストのスケールの仕方を変えます。timeMin と timeMax を設定すると展開ウィンドウが制限され、終了日のない繰り返しを持つカレンダーで singleEvents=True を使う場合には必須です。

自前でページネーションを構築すると何が問題になる？

本番品質の Google Calendar 同期クライアントの構築は、カレンダーごとのページネーションモデルと繰り返しイベントの展開のために、Gmail の同等の実装よりも複雑です。最初は25行のループだったものが、必要なすべてのケースを処理すると150〜200行に膨らみます：

• カレンダーごとに1つの同期カーソル — 8つのカレンダーを接続したユーザーには、8つの保存済み syncToken 値、8つの完全同期フォールバックパス、8セットの状態管理メタデータが必要です。
• 410 Gone のフォールバック — すべての増分呼び出しには 410 を囲む try/except と、他のカレンダーに触れずに1つのカレンダーだけをリセットする再ページネーションのコードパスが必要です。2つのコードパスがあり、両方が正しく動作しなければなりません。
• OAuth2 トークンのライフサイクル — Google Calendar のアクセストークンは3,600秒ごとに失効します。同期ループにはリフレッシュトークンのコールバック、失効トークンのリトライロジック、リフレッシュトークン自体の永続ストレージが必要です。
• 繰り返しイベントのセマンティクス — 分析パイプラインにはマスターイベント、ダッシュボード UI には展開済みインスタンスが必要で、初回同期と増分同期の singleEvents が一度でも不一致になると 400 Bad Request が返ります。
• レート制限 — Google Calendar API はユーザーあたり毎分600クエリ、プロジェクトあたり1日1,000,000クエリを強制します。素朴なカレンダーごとの同期ループは、特に繰り返しイベントを展開する場合、グローバル上限よりも先にユーザーごとの上限に達します。
• OAuth 同意画面 — コードを実行する前に、Google Cloud プロジェクト、console.cloud.google.com で設定した OAuth 同意画面、クライアント ID とシークレット、calendar または calendar.readonly スコープ、リダイレクト URI が必要です。Web フォームのクリック作業に15〜20分かかります。

コマンド1つで Google Calendar の予定を一覧表示するには？

Nylas CLI は、ページネーション、同期、OAuth のスタック全体をターミナルコマンド1つに置き換えます。Calendar API のアプローチでは150〜200行の Python と Google Cloud プロジェクトが必要なところを、CLI は1行と2分のインストールに短縮します。

以下の3つのコマンドが最も一般的なパターンをカバーします：今後の予定の一覧表示、日付範囲での絞り込み、単一の予定の取得です。それぞれ内部では API 呼び出しを1回実行し、プロバイダのレスポンスをまたぐページネーションは CLI が処理します：

# List the next 50 upcoming events on the primary calendar
nylas calendar events list --limit 50 --json

# Events in the next 7 days
nylas calendar events list --days 7 --json

# Read one event by ID
nylas calendar events show <event-id> --json

すべてのフラグは nylas calendar events list、nylas calendar events show、および完全なコマンドリファレンスを参照してください。このツールが初めての方ははじめにガイドから始めてください。

予定のページネーションの前にすべてのカレンダーを一覧表示するには？

典型的な Google Workspace ユーザーは4〜8個のカレンダーを持っています：プライマリカレンダー、1〜3個の共有チームカレンダー、任意のセカンダリ個人カレンダー、1〜2個の購読カレンダー（米国の祝日、スポーツの日程、連絡先の誕生日）です。それぞれが個別のページネーションスコープです。Calendar API では、まず calendarList.list を呼び出してアクセス可能なカレンダーを列挙し、次に各 calendarId に対して events.list をループする必要があり、リクエスト数と保存する同期状態が N 倍になります。

CLI はこの列挙に nylas calendar list を使います。nylas calendar events list --calendar-id と組み合わせれば、1つのシェルスクリプトですべてのカレンダーをページネーションできます：

# List every calendar the user has access to
nylas calendar list --json

# Loop pagination across all calendars
for cal in $(nylas calendar list --json | jq -r '.[].id'); do
  nylas calendar events list \
    --calendar-id "$cal" \
    --days 30 \
    --json
done

複数アカウントをまたいでページネーションするには？

本番のカレンダーワークフローは、複数の接続済み Google アカウントにまたがることがよくあります。仕事用と個人用のカレンダーを集約する経営者、5つのクライアントアカウントにまたがってスケジューリングするアシスタント、ワークスペース内の全営業担当者のカレンダーを読み取るセールスオペレーションツールなどです。Google Calendar は OAuth グラントごとにクォータを適用するため、10アカウントの並列同期はアカウント間のスロットリングなしに動作しますが、アプリケーションコードは10セットのリフレッシュトークン、10個のカレンダーごとの syncToken バンドル、10個のアクティブなグラント状態を追跡しなければなりません。

CLI ではグラントが第一級の概念です。nylas auth list は接続済みのすべてのアカウントを表示します。nylas auth whoami は次のコマンドが使用するグラントを出力します。nylas auth switch はアクティブなグラントを切り替えます。すべてのカレンダーコマンドはグラント ID を位置引数として受け付けるため、1つのシェルスクリプトでアクティブな状態を変更せずにグラントを反復処理できます。

# Show every connected Google grant
nylas auth list --provider google --json

# Pull today's events from every connected calendar account
for grant in $(nylas auth list --provider google --json | jq -r '.[].id'); do
  nylas calendar events list "$grant" \
    --days 1 \
    --json
done

CI、cron ジョブ、ヘッドレス環境で同期するには？

Google Calendar の OAuth2 アクセストークンは3,600秒ごとに失効し、ブラウザベースのリフレッシュフローは CI、Docker、AI エージェントサンドボックスなどの無人環境では動作しません。Google のオフラインアクセスフローでは、リフレッシュトークンを取得するための一度きりの対話的セットアップが必要で、アプリケーションはそのトークンをシークレットマネージャーに保存し、再同意までの6か月間再利用します。サービスアカウントという代替手段には Google Workspace のドメイン全体の委任が必要で、これは管理者専用の機能であり、個人の Google アカウントでは利用できません。

Nylas CLI は API キー認証でブラウザを回避します。nylas auth config --api-key はブラウザに触れずにキーを保存します。nylas auth token は下流の API 呼び出し用にスコープ付きベアラートークンを生成します。nylas auth status は現在の認証状態を報告し、コンテナ化されたデプロイのヘルスチェックに便利です。

# Generate a daily schedule digest in a cron job — no browser
export NYLAS_API_KEY="nyk_..."
nylas auth config --api-key "$NYLAS_API_KEY"
nylas calendar events list --days 1 --json > /var/log/agenda.json

ポーリングの代わりに Webhook を使うべきなのはいつ？

Google Calendar を5分ごとにポーリングすると、アカウントあたり1日288回の API 呼び出しが発生します。接続ユーザーが1,000人なら毎日288,000回の呼び出しになり、そのほとんどは変更ゼロを返します。Google Calendar は Cloud Pub/Sub または Webhook コールバック URL によるプッシュ通知の代替手段を提供していますが、セットアップには Pub/Sub トピック、calendar-api-push@system.gserviceaccount.com への IAM バインディング、各カレンダーの watch チャネル、そして Google が watch を7日ごとに失効させるための更新ジョブが必要です。

CLI の Webhook は Pub/Sub トピックなしで登録できます。nylas webhook create は HTTPS エンドポイントとトリガーのリストを登録します。nylas webhook list は登録済みの内容を表示します。nylas webhook triggers は event.created、event.updated、event.deleted、calendar.created を含むサポート対象のすべてのイベントを一覧表示します。nylas webhook test send はエンドポイントにサンプルペイロードを送信し、レシーバーを検証できます。nylas webhook verify は受信ペイロードの HMAC 署名を検証します。

# Register a webhook for calendar event changes
nylas webhook create \
  --url https://example.com/hooks/calendar \
  --triggers event.created,event.updated,event.deleted \
  --json

# Verify an inbound payload signature
nylas webhook verify \
  --payload-file ./incoming.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$WEBHOOK_SECRET"

典型的なカレンダー利用では、Webhook のイベント量はユーザーあたり1日平均5〜20件で、ポーリングの288回の呼び出しと対照的です。イベント変更からアプリケーションがそれを検知するまでのレイテンシは、最大5分から約1秒に短縮されます。

他のカレンダープロバイダはページネーションをどう扱う？

ページネーションの仕様を持つプロバイダは Google Calendar だけではありません。Microsoft Graph（Outlook と Exchange Online のカレンダー）は、クライアントがそのまま辿る完全な URL である @odata.nextLink と、増分同期用のデルタリンク機構を使用します。CalDAV（iCloud、Yahoo、ホスト型 Apple）は REST 的な意味でのページネーションを行いません：calendar-query フィルタ付きの REPORT クエリが一致するイベントを単一のレスポンスで返し、同期は sync-collection と ETag で処理されます。Exchange Web Services（EWS、古い Exchange Server 環境で使用）は IndexedPageItemView 付きの FindItem を使用します。

プロバイダごとのガイドでは、それぞれの仕様で同じ問題を解説しています：ターミナルから Google Calendar を管理、Outlook カレンダーを管理、Exchange カレンダーを管理、iCloud カレンダーを管理、Yahoo カレンダーを管理。同じ nylas calendar events list コマンドが、同一のフラグですべてのプロバイダに対して動作するとドキュメントに記載されています。

上記の Outlook、Exchange、iCloud、Yahoo のプロバイダ側の挙動は、各プロバイダの公開ドキュメントに基づくものであり、すべてのバックエンドでエンドツーエンドの実行を検証したものではありません。プロバイダ固有のワークフローをデプロイする前にローカルでテストしてください。

Google Calendar の同期にはどれくらい時間がかかる？

500件のイベントを持つ単一の Google Calendar の同期は、CLI コマンド1つで約2秒、50,000件の展開済みイベントを持つマルチカレンダーアカウントは約1分で完了します。同じワークロードを、バックオフ付きの逐次的な Python ページネーションループで実行すると、それぞれ約4秒と約6分かかります。ループは明示的なスレッドプールなしには、ユーザーあたり毎分600クエリの上限に向けてファンアウトできないためです。以下のベンチマークは、Google サーバーへの中央値レイテンシ約150ミリ秒の家庭用ブロードバンド接続で測定しました。

実時間の差はほとんどが並行性によるものです。Python の素朴な逐次ループはカレンダーを1つずつ反復しますが、CLI はユーザーあたり毎分600クエリの上限までカレンダーごとのページネーションを並列にファンアウトします。上記の API 呼び出し数は変わりません。CLI が Google の基盤となる呼び出しを安くすることはできず、ディスパッチを速くするだけです。

Google Calendar 同期のよくあるレシピは？

カレンダーのページネーションと標準的な UNIX ツールを組み合わせた4つのシェルパターンです。いずれも JSON 出力のパースに jq、機械可読フォーマットに --json を使用します。

今日のアジェンダ

日次アジェンダスクリプトは、nylas calendar events list --days 1 を、今後24時間のすべての予定の開始時刻とタイトルを出力する jq フィルタで包みます。シェルの起動メッセージ、ターミナルダッシュボード、朝のサマリー用に LLM へパイプする用途に便利です。平均的なアカウントに対して約2秒で実行されます。

nylas calendar events list --days 1 --json \
  | jq -r '.[] | "\(.when.start_time) - \(.title)"'

複数カレンダーをまたいで空き時間を検索

nylas calendar find-time は全参加者の空き/ビジーデータをクエリし、リクエストした時間の長さ分、全員が空いているスロットを返します。CLI が参加者間のタイムゾーン正規化を処理するため、太平洋時間午前9時に提案された30分のスロットは、レスポンス内では東部時間午後12時としても読み取れます。素の空き/ビジー枠には nylas calendar availability check を併用してください。

nylas calendar find-time \
  --participants you@example.com,colleague@example.com \
  --duration 30 \
  --days 7 \
  --json

今週のカレンダーの競合を検出

nylas calendar ai conflicts は今後 N 日間をスキャンし、3段階の深刻度をフラグ表示します：ハードな競合（同時刻のイベント）、ソフトな競合（会議間が15分未満）、移動時間リスクです。デフォルトの先読みは7日間です。各競合の解決案を提案するには nylas calendar ai reschedule を併用してください。

nylas calendar ai conflicts --days 7 --json

特定の主催者からの予定を一括辞退

nylas calendar events list と nylas calendar events rsvp を組み合わせれば、1つのパイプラインで特定の送信者からのすべての招待を辞退できます。RSVP コマンドは --status yes、--status no、--status maybe を受け付けます。自分が所有するイベントの場合は nylas calendar events delete に置き換えてください。受信箱スタイルの分析には nylas calendar analyze を参照してください。

nylas calendar events list --json \
  | jq -r '.[] | select(.organizer.email == "noisy@example.com") | .id' \
  | xargs -I{} nylas calendar events rsvp --id {} --status no

CLI の同期は素の API ページネーションとどう違う？

以下の表は、Google Calendar API の Python アプローチと Nylas CLI を9つの観点で比較します。最大の違いはカレンダーごとの同期状態です。カレンダー同期クライアントは、ユーザーが所有するすべてのカレンダーに対して1つのカーソルと1つのフォールバックパスを管理しなければなりませんが、CLI はそのファンアウトを内部で処理します。

リリース前に開発者が知っておくべきことは？

Google Calendar API の nextPageToken とは？

カレンダーに対して events.list を呼び出すと、API は1ページあたり最大2,500件（デフォルト250件）のイベントを返します。さらにイベントが存在する場合、レスポンスには nextPageToken 文字列が含まれます。そのトークンを次のリクエストの pageToken パラメータとして渡し、次のページを取得します。レスポンスに nextPageToken が含まれなくなるまでループを続けます。これは末尾に到達したことを意味し、レスポンスには増分同期用の nextSyncToken が含まれます。

Google Calendar の増分同期は syncToken でどう動作する？

カレンダーを完全にページネーションすると、最後のレスポンスに nextSyncToken が含まれます。これをカレンダーごとに保存します。次回の同期時に events.list に syncToken として渡すと、前回の同期以降に作成、更新、削除されたイベントだけがレスポンスに含まれます。トークンが無効化されている場合、API は 410 Gone を返すため、新しいトークンを取得するには最初から完全なページネーションを再実行する必要があります。

なぜ Calendar API は 404 ではなく 410 を返す？

410 Gone は、リソース（この場合はトークンをキーとする同期セッション）が存在していたが意図的に無効化されたことをクライアントに伝えます。Gmail の古くなった historyId に対する同種の失敗が 404 を返すのは、Gmail の履歴レコードがローリングウィンドウで失効するためです。Calendar が 410 を使うのは、トークン自体が取り消されたためです。機能的にはどちらも同じ意味です：保存済みトークンを破棄し、完全に再ページネーションしてください。

Google Cloud のセットアップなしで Calendar の予定を一覧表示できる？

はい。Nylas CLI は OAuth2 とプロバイダ認証を内部で処理します。nylas calendar events list --limit 50 --json を実行すれば、Google Cloud プロジェクトの作成、OAuth 同意画面の設定、アクセストークンの管理なしに予定を一覧表示できます。同じフローが Google、Outlook、Exchange、iCloud、Yahoo で動作します。

特定の1つのカレンダーだけを同期するには？

nylas calendar events list に --calendar-id を渡します。接続済みアカウントのすべてのカレンダー ID は nylas calendar list で確認できます。カレンダー ID は primary や en.usa#holiday@group.v.calendar.google.com のような形式、共有カレンダーの場合は UUID です。

繰り返しイベントはどう扱う？

CLI はデフォルトで繰り返しイベントを展開します。12か月にわたる毎週のスタンドアップは、それぞれ固有の発生時刻を持つ52の個別の行として表示されます。基盤となる Google Calendar の events.list 呼び出しは singleEvents=true を使用するため、利用側は RRULE 構文を解釈することなく展開済みインスタンスを取得できます。繰り返しルールを保持したマスターイベントは、現時点では CLI のインターフェースからは公開されていません。

OAuth のポップアップなしで cron ジョブからカレンダーを同期できる？

はい。nylas auth login の代わりに nylas auth config --api-key を使用します。API キーフローはブラウザを開かないため、ヘッドレスマシン、Docker コンテナ、CI パイプラインで動作します。cron を実行する環境でキーをシークレットとして保存してください。

CLI は Outlook や iCloud のカレンダーでも同じように動作する？

はい。nylas calendar events list、nylas calendar events show、nylas calendar events create は、Google Calendar、Microsoft Graph（Outlook と Exchange Online）、CalDAV（iCloud、Yahoo）、EWS（レガシー Exchange）で動作します。プロバイダごとの手順はOutlook カレンダーを管理、iCloud カレンダーを管理、Exchange カレンダーを管理を参照してください。

カレンダー変更のプッシュ通知を受け取れる？

はい。nylas webhook create は、Cloud Pub/Sub トピックを必要とせずに event.created、event.updated、event.deleted などのイベント用 HTTPS エンドポイントを登録します。サポート対象のすべてのイベントタイプは nylas webhook triggers で確認できます。

次のステップ

カレンダーのページネーションは、繰り返し発生する API 統合の課題の1つです。以下の関連ガイドでは、Gmail の同期、ETag ベースの同時実行制御、プロバイダごとのカレンダー管理、コマンドの全体像など、隣接するワークフローを扱います。

• Gmail API ページネーションと同期 — 同じパターンを messages.list と historyId に適用
• ターミナルから Google Calendar を管理 — 作成、更新、RSVP、空き/ビジーのワークフロー
• ターミナルから Outlook カレンダーを管理 — Microsoft Graph の @odata.nextLink に相当
• ターミナルから iCloud カレンダーを管理 — 同じコマンドによる CalDAV のページネーション
• Gmail API の If-Match と ETag の扱い — 412 Precondition Failed と同時実行制御
• Google Calendar 所有権の変更 — カレンダーがアカウント間で移行されるとき
• ターミナルからカレンダーを管理 — マルチプロバイダのハブガイド
• はじめに — インストール方法と初回認証
• calendar events list コマンド — --limit、--days、カレンダー選択、JSON 出力の正確なフラグ
• calendar list コマンド — イベントページをループする前にカレンダーを列挙
• コマンドリファレンス — すべてのフラグとサブコマンドを網羅