Calendar API の互換性

Calendar API見出しのリンクをコピー

Calendarpit は次のエンドポイントを提供します。アクセスのルールは次のとおりです。

• /calendar/v3 の対応エンドポイントは、どれも Calendarpit のベアラートークンが必要です。スコープはローカル OAuthを参照してください。
• アクセスできるのは、認可したテストユーザーが所有するカレンダーだけです。
• primary は、そのユーザーのプライマリカレンダーを指します。
• 存在しないカレンダー ID や、所有していないカレンダー ID には 404（notFound）を返します。
• 例外として、freebusy.query は 200 を返し、レスポンスの中でカレンダーごとに notFound エラーを示します。

表のパスは、すべて /calendar/v3 からの相対パスです。

calendarList.list のクエリパラメータは、後述の「一覧とページング」に記載しています。

メソッドの対応状況見出しのリンクをコピー

未対応のメソッドには、明示的なエラーを返します。

events.import と events.quickAdd は、パスが /events/{eventId} と重なります。このため上の表のステータスを返します。

イベント見出しのリンクをコピー

対応するフィールド見出しのリンクをコピー

• id: [a-zA-Z0-9@._-]{1,128} に一致する値です。primary は使えません。ID が重複すると 409（duplicate）を返します。
• summary、description、location
• start、end
• transparency: opaque、transparent
• status: confirmed、tentative、cancelled
• visibility: default、public、private、confidential
• colorId: "1"–"11"
• attendees、attendeesOmitted
• guestsCanModify、guestsCanInviteOthers、guestsCanSeeOtherGuests
• reminders、recurrence
• conferenceData: conferenceDataVersion=1 が必要です。
• hangoutLink
• extendedProperties.private、extendedProperties.shared: 文字列マップです。

書き込み系のエンドポイントは、次のものも受け付けます。

• sendUpdates: all、externalOnly、none
• conferenceDataVersion: 0、1

サーバーが管理するフィールド見出しのリンクをコピー

• レスポンスには organizer、creator、iCalUID、sequence、created、updated、引用符付きの etag が含まれます。
• kind、etag、created、updated、calendarId、sequence もリクエストで受け付けます。このため、取得したイベントをそのまま送り返せます。
• リクエストの calendarId は、primary ではなく解決後のカレンダー ID です。
• organizer、creator、iCalUID、recurringEventId、originalStartTime は読み取り専用です。更新時に値が変わっていなければ受け付けます。
• events.insert では、これらの読み取り専用フィールドを省略してください。Calendarpit が値を設定します。
• sequence は更新のたびに増えます。
• 保存済みイベントへの GET、PUT、PATCH、DELETE では If-Match を確認します。一致しない場合は 412（conditionNotMet）を返します。

PUT と PATCH見出しのリンクをコピー

• PUT は書き込み可能フィールドを置き換えます。省略した任意フィールドはデフォルトに戻ります。
• PATCH は省略したフィールドを保持します。
  • start や end のオブジェクトを送ると、保存済みのオブジェクトをまるごと置き換えます。中のフィールドはマージしません。
  • extendedProperties のマップはキー単位でマージします。null でキーまたはマップ全体を削除します。
• 終日イベントの入力では dateTime: null と timeZone: null を受け付けます。

削除と削除済みレコード見出しのリンクをコピー

events.delete は 204 を返し、cancelled の削除済みレコードを残します。すでに cancelled の場合は 410（deleted）を返します。

singleEvents=false の場合、繰り返しの系列で cancelled になった例外は一覧に表示されたままです。

繰り返し、招待、リマインダー、ダミーの Meet リンク、時刻のルールはイベント、繰り返し、時刻の扱いを参照してください。

カレンダーリスト見出しのリンクをコピー

エントリの形式見出しのリンクをコピー

• カレンダーリストのエントリは kind: "calendar#calendarListEntry" です。
• list と get は同じ形式のエントリを返します。

所有するカレンダーは、最初は所有者のリストに次の値で載ります。

• accessRole: "owner"
• selected: true
• colorId: "1"（backgroundColor: "#ac725e"、foregroundColor: "#1d1d1d"）
• defaultReminders: []
• primary
• conferenceProperties.allowedConferenceSolutionTypes: ["hangoutsMeet"]

一部のフィールドは、条件によってだけ含まれます。

• hidden は true のときだけ含まれます。
• summaryOverride と notificationSettings は、空のとき省略されます。
• deleted: true は、リストから外したエントリと削除済みレコードにだけ付きます。
• description と location はレスポンスに含まれません。送ると 400（unsupportedFeature）で拒否されます。

書き込みと同時更新の制御は次のとおりです。

• 読み取り専用フィールドは kind、etag、id、summary、timeZone、accessRole、primary、deleted、conferenceProperties です。
• 書き込み時は、読み取り専用フィールドの値が変わっていない場合だけ受け付けます。一致しない場合は 400（invalidParameter）を返します。
• パスで primary を使う場合、id は primary も受け付けます。
• etag は、エントリの設定が変わると更新されます。カレンダーの summary、timeZone、primary フラグが変わったときも更新されます。
• PATCH、PUT、DELETE では If-Match を確認します。一致しない場合は 412（conditionNotMet）を返します。

設定の書き込み（patch、update、insert）見出しのリンクをコピー

ユーザーごとの書き込み可能な設定は、summaryOverride、colorId、backgroundColor、foregroundColor、hidden、selected、defaultReminders、notificationSettings です。

• SQLite 使用時は、再起動後も残ります。
• リセットや Fixture の読み込みで消えます。
• summaryOverride には、空白だけではない 10,000 文字以内の文字列が必要です。"" は 400 を返します。

省略したフィールドの扱いは、書き込みの種類で異なります。

• PATCH は、省略した書き込み可能フィールドを保持します。null で summaryOverride、defaultReminders、notificationSettings を消去します。
• PUT と insert（200）は、書き込み可能フィールドを置き換えます。
  • 省略した summaryOverride、defaultReminders、notificationSettings は消去されます。
  • hidden と selected は false に戻ります。一度も書き込んでいないエントリは selected: true のままです。
  • 色を指定しない場合、colorId は "1" に戻ります。
• 内容が変わらない書き込みは 200 を返します。etag は変わらず、カレンダーリストのページトークンも無効にならず、watch チャネルにも通知しません。

色見出しのリンクをコピー

• colorId はパレット ID "1"–"24" を受け付けます。前景色は "#1d1d1d" です。
• 未知の ID や、"constructor" のような継承プロパティ名は 400 を返します。

colorRgbFormat=true を指定した場合:

• insert、patch、update のどれでも、backgroundColor と foregroundColor（#rrggbb）の両方が必要です。ない場合は 400 を返します。
• 送った colorId は無視され、最も近いパレット色が設定されます。

colorRgbFormat=true を指定しない場合:

• RGB フィールドには、表示中の色と同じ値しか送れません。
• PATCH で現在の colorId と RGB を同じ値で送ると、カスタムの色を保持します。
• PUT と insert でカスタムの RGB を保持するには、colorRgbFormat=true を送る必要があります。
• 別の colorId を指定すると、カスタムの RGB は消えます。

リマインダーと通知見出しのリンクをコピー

• defaultReminders は {method: "email" | "popup", minutes: 0–40320} の項目を 5 件まで受け付けます。
• notificationSettings.notifications は {method: "email", type} の項目を 5 件まで受け付けます。
  • type は eventCreation、eventChange、eventCancellation、eventResponse、agenda のいずれかです。
  • type は重複できません。重複すると 400 を返します。
• どちらの設定でもメールは送信されません。
• PATCH {"notificationSettings": {}} は既存の通知を保持します。
• []、null、または notifications なしの PUT は通知を消去します。

削除と insert見出しのリンクをコピー

calendarList.delete（204）は、プライマリ以外のカレンダーを呼び出し元のリストから外すだけです。

• プライマリカレンダーには 403（cannotDeletePrimaryCalendar）を返します。
• すでに外している場合は 404 を返します。
• 外したカレンダーとそのイベントには、calendars.get、events.*、freebusy.query、events.watch で引き続きアクセスできます。
• そのカレンダーに対する calendarList.get、patch、update は 404 を返します。

calendarList.insert は、リストから外した所有カレンダーを戻します（200）。

• id が必要です。ない場合は 400 を返します。
• カレンダーを新しく作ることはありません。
• すでにリストにあるカレンダー（非表示のものと primary を含む）は 409（duplicate）を返します。非表示を解除するには patch を使ってください。

管理 API による影響:

• プライマリカレンダーを削除すると、リストに残っている最初のカレンダーがプライマリになります。
• すべてリストから外れている場合は、所有する最初のカレンダーを保存済みの設定のままリストに戻します。
• primary: true を設定した場合も、リストから外したカレンダーはリストに戻ります。

watch見出しのリンクをコピー

calendarList.watch は、ループバックの許可リスト、配信ログ、channels.stop エンドポイントを events.watch と共有します。watch 通知を参照してください。

• 開始時に sync を送ります。
• その後、リストへの書き込みで保存済みの設定が変わったときに exists を送ります。
• 管理 API でユーザーのカレンダーを作成・更新・削除したときも exists を送ります。
• イベントへの書き込みでは送りません。
• その他のクエリパラメータ（syncToken を含む）は 400（unsupportedFeature）を返します。
• params（params.ttl など）も 400（unsupportedFeature）を返します。

一覧とページング見出しのリンクをコピー

calendarList.list見出しのリンクをコピー

calendarList.list は次のパラメータを受け付けます。

• maxResults、pageToken
• minAccessRole: freeBusyReader、reader、writer、owner。所有するカレンダーはすべて owner ロールなので、有効な値であればどれでも一致します。
• showHidden: デフォルトは false です。このとき list は hidden: true のエントリを返しません。get では取得できます。
• showDeleted: 下記を参照してください。

レスポンスにはコレクションの etag が含まれます。nextSyncToken はありません。

showDeleted=true を指定すると、次の deleted: true のエントリも返します。

• calendarList.delete でリストから外したカレンダー: hidden: true でも、保存済みの設定を保持します。
• 管理 API で削除したカレンダーの削除済みレコード: リストのデフォルト設定を使います。削除したカレンダーがプライマリだった場合は primary: true を保持します。

events.list見出しのリンクをコピー

events.list は次のパラメータを受け付けます。

• timeMin、timeMax、updatedMin: オフセット付きの RFC 3339 タイムスタンプが必要です。
• maxResults: 1–2500、デフォルト 250
• orderBy: startTime、updated。orderBy=startTime には singleEvents=true が必要です。
• pageToken、singleEvents、timeZone、showDeleted、syncToken、iCalUID
• privateExtendedProperty=name=value、sharedExtendedProperty=name=value: 繰り返し指定できるフィルタです。すべて一致する必要があります。

範囲の判定と並び順は次のとおりです。

• 範囲の判定には start < timeMax と end > timeMin を使います。
• orderBy を指定しない一覧は、イベント ID 順に並びます。

ページトークン見出しのリンクをコピー

• イベント一覧のページングでは、最初のページの時点でスナップショットを固定します。ページ取得の合間に書き込みがあっても、項目は抜けません。
• イベントのページトークンは、クエリとユーザーに結び付いています。
• イベントのページトークンは 1 時間で期限が切れます。再起動・リセット・Fixture の読み込みでも消えます。
• カレンダーリストのページトークンは、データやカレンダーリストへの書き込みがあると無効になります。保存はされません。
• 期限切れや無効なトークンは 410（invalidPageToken）を返します。

syncToken と nextSyncToken は差分同期を参照してください。

明示的に除外している機能見出しのリンクをコピー

次の機能には対応していません。

• ACL・共有カレンダー・委任
• カレンダーグループ
• カラーパレット（colors.get）
• ユーザー設定
• カレンダーリストの同期トークン
• ACL と設定の watch
• フリーテキスト検索（q）
• eventTypes
• 添付ファイル
• 実際のメール送信
• 実際の Google Meet の作成
• 完全な OIDC

リクエストの検証見出しのリンクをコピー

• 未知のボディフィールドは 400（unsupportedFeature）を返します。
• 未知のクエリパラメータ（fields を含む）は、/calendar/v3 のすべてのエンドポイントで 400（unsupportedFeature）を返します。
• 例外として、channels.stop はクエリ文字列を無視します。
• トランスポート用のパラメータ（alt=json、prettyPrint、quotaUser、key）は受け付けます。
• API キーは、OAuth のベアラートークンの代わりにはなりません。
• Calendarpit が Google にリクエストを中継したり、Google と同期したりすることはありません。

カレンダーの管理とデータのリセットはテスト制御 APIを参照してください。クライアントの接続先を Calendarpit にする方法はアプリを接続するを参照してください。