Google Calendar API は RESTful API。HTTP を直接呼ぶか、Google のクライアントライブラリで使う。カレンダーの Web 画面にある機能の大部分を、API から扱える。
| リソース | 内容 |
|---|---|
Events | タイトル・開始と終了・参加者などを持つ予定。単発と繰り返しがある |
Calendars | イベントの集まり。説明文や既定のタイムゾーンなどのメタデータを持つ |
CalendarList | ユーザーのカレンダー一覧に出るカレンダーの集まり。色や新規イベントの通知設定など、ユーザーごとの属性を持つ (CalendarListEntry) |
Settings | タイムゾーンなど、画面上のユーザー設定 |
Acl | ユーザーやグループに、カレンダーへの特定のアクセス権を与えるルール |
出典: Google Calendar API の概要 (Google for Developers)
get だけ (list は無い)。GET https://www.googleapis.com/calendar/v3/colorscalendar と event の 2 つのパレットと、updated。いずれも読み取り専用background (背景色) と foreground (その上に文字を描く色) を持つcalendarListEntry の colorId は calendar パレット、イベントの colorId は event パレットを指すcalendar・calendar.readonly・calendar.app.created・calendar.calendarlist・calendar.calendarlist.readonly・calendar.events.freebusy・calendar.events.owned・calendar.events.owned.readonly・calendar.events.public.readonly のどれか出典: Colors (Google for Developers) ・ colors.get (Google for Developers)
POST https://www.googleapis.com/calendar/v3/freeBusy で、複数のカレンダーやグループの、予定が入っている時間帯 (busy) を返す。
| 項目 | 内容 |
|---|---|
timeMin / timeMax | 検索範囲の開始と終了 (RFC3339) |
timeZone | 応答のタイムゾーン。既定は UTC |
items[].id | 照会するカレンダーまたはグループの ID |
groupExpansionMax | 1 グループに含めるカレンダー ID の最大数。上限 100。超えるとエラー |
calendarExpansionMax | 空き状況を返すカレンダーの最大数。上限 50 |
calendar.readonly・calendar・calendar.events.freebusy・calendar.freebusy のどれかcalendars に、カレンダーごとの busy[] (start は開始を含み、end は終了を含まない) と errors[] が入る。groups にはグループの展開結果が入るreason は groupTooBig・tooManyCalendarsRequested・notFound・internalError。今後増える可能性があるため、未知の値も扱えるようにする公式ページに 20 件が載っている。接頭辞はすべて https://www.googleapis.com/auth/。公式は「できるだけ範囲の狭いスコープを選ぶ」よう求めている。
| 用途 | スコープ (接頭辞を省略) | 概要 |
|---|---|---|
| 全体 | calendar | 閲覧できるすべてのカレンダーの閲覧・編集・共有、完全削除 |
| 全体 | calendar.readonly | 閲覧できるカレンダーの閲覧・ダウンロード |
| イベント | calendar.events | すべてのカレンダーのイベントの閲覧・編集 |
| イベント | calendar.events.readonly | すべてのカレンダーのイベントの閲覧 |
| イベント | calendar.events.owned | 所有カレンダーのイベントの作成・変更・削除 |
| イベント | calendar.events.owned.readonly | 所有カレンダーのイベントの閲覧 |
| イベント | calendar.events.public.readonly | 公開カレンダーのイベントの閲覧 |
| 空き状況 | calendar.freebusy | 予定の空き状況の確認 |
| 空き状況 | calendar.events.freebusy | アクセスできるカレンダーの空き状況の閲覧 |
| カレンダー | calendar.calendars | カレンダーのプロパティの変更、セカンダリカレンダーの作成 |
| カレンダー | calendar.calendars.readonly | カレンダーのタイトル・説明・タイムゾーンなどの閲覧 |
| カレンダー | calendar.app.created | セカンダリカレンダーの作成と、そのイベントの操作 |
| 一覧 | calendar.calendarlist | 購読中のカレンダーの閲覧・追加・削除 |
| 一覧 | calendar.calendarlist.readonly | 購読中のカレンダー一覧の閲覧 |
| 共有 | calendar.acls | 所有カレンダーの共有権限の閲覧・変更 |
| 共有 | calendar.acls.readonly | 所有カレンダーの共有権限の閲覧 |
| 設定 | calendar.settings.readonly | カレンダー設定の閲覧 |
| アドオン | calendar.addons.execute | カレンダーアドオンとしての実行 |
| アドオン | calendar.addons.current.event.read | 画面で開いたイベントの閲覧 |
| アドオン | calendar.addons.current.event.write | 画面で開いたイベントの編集 |
出典 (公式): Sensitive scope verification ・ OAuth 同意画面の設定 ・ OAuth 2.0 Scopes for Google APIs
出典 (非公式): How to use OAuth for Google Calendar (Nylas)
範囲の選び方 (この資料の解釈): 閲覧だけなら .readonly 付きにする。自分の所有カレンダーだけを扱うなら、calendar.events より calendar.events.owned が狭い。空き状況だけなら calendar.freebusy で足りる可能性がある。公式の文面ではなく、スコープ名と概要からの推測。
| 種類 | 上限 |
|---|---|
| 1 分あたり・プロジェクト | 10,000 リクエスト |
| 1 分あたり・プロジェクト × ユーザー | 600 リクエスト |
| 1 日あたり・プロジェクト (課金のしきい値) | 1,000,000 リクエスト |
403 usageLimits または 429 usageLimits が返るmin((2^n) + ランダムミリ秒, maximum_backoff)。ランダムは 1,000 ミリ秒以下で、再試行のたびに計算し直す。maximum_backoff は 32〜64 秒が目安。再試行の回数にも上限を設けるquotaUser パラメータ (または x-goog-quota-user ヘッダー) で実際のユーザーを指定する対象は Acl・CalendarList・Events・Settings の 4 種類。通知を受ける HTTPS のサーバーが要る。
| watch の項目 | 内容 |
|---|---|
id (必須) | プロジェクト内で一意。最大 64 文字。UUID を推奨 |
type (必須) | web_hook |
address (必須) | 通知を受ける HTTPS の URL。有効な SSL 証明書が要る (自己署名・信頼されない発行元・失効・ホスト名の不一致は不可) |
token | 最大 256 文字。通知の検証や振り分けに使う。機密情報は入れない |
expiration | ミリ秒の Unix タイムスタンプ |
X-Goog-Resource-State: sync の通知が届く。メッセージ番号は常に 1。watch の応答より先に届くことがあるX-Goog-Resource-State は sync・exists・not_exists のいずれかhttps://www.googleapis.com/calendar/v3/channels/stop に id と resourceId を POST するEvents と Acl はカレンダーごと、Settings と CalendarList はユーザーごとに 1 回の購読で足りるid で watch をもう一度呼ぶ (新旧が並行して有効な時間帯がある)。通知は一定の割合で欠落することがあり、届かなくても同期が進む作りにする。出典: Calendar API のプッシュ通知 (Google for Developers)
nextSyncToken を保存するsyncToken に入れて list する。結果には削除されたエントリも入る。pageToken が返ったら、最初と同じクエリに pageToken を足して順に取り、最後のページの新しい syncToken を保存する400updated と modifiedSince) は取りこぼしやすく、非推奨recurrence に RRULE を入れる (例: RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z)events.list() の既定: 単発の予定・繰り返しの親・例外だけを返す。例外ではないインスタンスは返さないsingleEvents=true: 各インスタンスが個別に返るが、親は返らない。空き状況だけを見る権限のユーザーも、同じ動きになるevents.instances(): 特定の繰り返し予定のインスタンスを全部取る| フィールド | 内容 |
|---|---|
recurrence | 親だけが持つ。インスタンスは持たない |
recurringEventId | 所属する親予定の ID |
originalStartTime | 親の繰り返しルール上の本来の開始時刻。日時が変えられていても、系列の中の位置を特定できる |
インスタンスの変更・削除は、取得したインスタンスへの PUT で行う。取り消すには status を cancelled にする。この操作で例外ができる。