Events: list

指定されたカレンダー上の予定を返します。 今すぐ試すまたは例を見る

リクエスト

HTTP リクエスト

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events

パラメータ

パラメータ名 説明
パスパラメータ
calendarId string カレンダー ID。カレンダー ID を取得するには、calendarList.list メソッドを呼び出します。現在ログインしているユーザーのメイン カレンダーにアクセスするには、「primary」キーワードを使用します。
省略可能なクエリ パラメータ
alwaysIncludeEmail boolean 非推奨であり、無視されました。主催者、作成者、参加者の email フィールドには、実際に使用できるメールアドレスがない場合でも(生成された非有効な値が指定されていても)値が返されます。
eventTypes string 返されるイベントタイプ。(省略可)有効な値は次のとおりです。
  • "default"
  • "focusTime"
  • "outOfOffice"
  • "workingLocation"
このパラメータを複数回繰り返すと、さまざまなタイプのイベントが返されます。現在、このフィールドに使用できるのは次の値のみです。
  • ["default", "focusTime", "outOfOffice"]
  • ["default", "focusTime", "outOfOffice", "workingLocation"]
  • ["workingLocation"]
デフォルトは ["default", "focusTime", "outOfOffice"] です。
この 4 種類のイベントの追加の組み合わせは、今後のリリースで提供される予定です。
iCalUID string レスポンスで提供される iCalendar 形式の予定 ID を指定します。(省略可)iCalendar ID を使用して予定を検索する場合に使用します。
maxAttendees integer レスポンスに含める参加者の最大数。指定した人数よりも多い場合は、参加者のみが返されます。省略可能。
maxResults integer 1 つの結果ページで返されるイベントの最大数。クエリと一致するイベントの数が増えても、検索結果のイベント数はこの値より少なくなるか、まったくなくなる可能性があります。レスポンスの不完全なフィールドは、レスポンスの空でない nextPageToken フィールドによって検出できます。デフォルト値は 250 イベントです。ページサイズは 2,500 イベント以下にする必要があります。省略可能。
orderBy string 結果として返されたイベントの順序。(省略可)デフォルトは、不特定の安定した順序です。

有効な値は次のとおりです。
  • startTime: 開始日時(昇順)で並べ替えます。これは、単一のイベントをクエリする場合(パラメータ singleEvents が True の場合)にのみ使用できます。
  • updated: 最終更新日時(昇順)で並べ替えます。
pageToken string 返す結果ページを指定するトークン。省略可能。
privateExtendedProperty string プロパティ名 = propertyName=value として指定された拡張プロパティ制約プライベート プロパティにのみ一致します。このパラメータを複数回繰り返すと、指定されたすべての制約に一致するイベントが返されます。
q string 次のテキスト フィールドでは、これらのテキストに一致するイベントを検索できます。summarydescriptionlocation、参加者の displayName、参加者のemail。省略可能。
sharedExtendedProperty string プロパティ名 = propertyName=value として指定された拡張プロパティ制約共有プロパティにのみ一致します。このパラメータを複数回繰り返すと、指定されたすべての制約に一致するイベントが返されます。
showDeleted boolean 削除されたイベント(status が「cancelled」と等しい)を結果に含めるかどうか。showDeletedsingleEvents がどちらも False の場合は、キャンセルされた定期的な予定のインスタンス(基となる定期的な予定を除く)が引き続き含まれます。showDeletedsingleEvents の両方が True の場合、削除されたイベントの 1 つのインスタンスのみが返されます(基となる定期的な予定は返されません)。(省略可)デフォルトは False です。
showHiddenInvitations boolean 結果に非表示の招待を含めるかどうかを指定します。(省略可)デフォルトは False です。
singleEvents boolean 定期的な予定をインスタンスに展開し、1 回限りの予定と定期的な予定のインスタンスのみを返す(基となる繰り返しイベント自体は返さない)かどうか。(省略可)デフォルトは False です。
syncToken string 前のリスト リクエストの結果の最後のページで返された nextSyncToken フィールドから取得したトークン。このリスト リクエストの結果には、それ以降に変更されたエントリのみが含まれます。前の list リクエスト以降に削除されたイベントはすべて結果セットに常に含まれ、showDeleted を False に設定することはできません。
クライアントの状態に一貫性を持たせるために、nextSyncToken と一緒に指定できないクエリ パラメータがいくつかあります。

次のものがあります。
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
他のクエリ パラメータは、未定義の動作を避けるために、最初の同期と同じにする必要があります。syncToken が期限切れになった場合、サーバーは 410 GONE レスポンス コードを返します。クライアントはストレージを消去し、syncToken を使用せずに完全な同期を実行する必要があります。
増分同期の詳細
省略可。デフォルトでは、すべてのエントリが返されます。
timeMax datetime フィルタの基準となるイベント開始時間の上限。(省略可)デフォルトでは、開始時間でフィルタされません。必須のタイムゾーン オフセットを含む RFC3339 タイムスタンプである必要があります(例: 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z)。ミリ秒単位で指定できますが、無視されます。timeMin が設定されている場合、timeMaxtimeMin より大きい必要があります。
timeMin datetime フィルタの基準となるイベントの終了時間の下限(その値を含まない)。(省略可)デフォルトでは、終了時間でフィルタされません。必須のタイムゾーン オフセットを含む RFC3339 タイムスタンプである必要があります(例: 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z)。ミリ秒単位で指定できますが、無視されます。timeMax が設定されている場合、timeMintimeMax より小さい値にする必要があります。
timeZone string レスポンスで使用されるタイムゾーン。(省略可)デフォルトはカレンダーのタイムゾーンです。
updatedMin datetime フィルタを適用するイベントの最終更新日時(RFC3339 タイムスタンプとして)。指定すると、この時間以降に削除されたエントリは、showDeleted に関係なく常に含まれます。(省略可)デフォルトでは、最終更新日時でフィルタされません。

承認

このリクエストでは、次のスコープのうち少なくとも 1 つを使用した承認が可能です。

スコープ
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.events

詳細については、認証と認可のページをご覧ください。

リクエスト本文

このメソッドをリクエストの本文に含めないでください。

レスポンス

成功すると、このメソッドは次の構造を含むレスポンスの本文を返します。

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}
プロパティ名 説明 メモ
kind string コレクションのタイプ(「calendar#events」)。
etag etag コレクションの ETag。
summary string カレンダーのタイトル。読み取り専用です。
description string カレンダーの説明。読み取り専用です。
updated datetime カレンダーの最終更新日時(RFC3339 タイムスタンプとして)。読み取り専用です。
timeZone string カレンダーのタイムゾーン。読み取り専用です。
accessRole string このカレンダーに対するユーザーのアクセス権限。読み取り専用。有効な値は次のとおりです。
  • none」 - ユーザーはアクセス権がありません。
  • "freeBusyReader" - ユーザーは予定の有無情報の読み取り権限があります。
  • reader」 - ユーザーはカレンダーに対する読み取りアクセス権を持っています。限定公開の予定は読み取りアクセス権を持つユーザーに表示されますが、予定の詳細は非表示になります。
  • writer」 - ユーザーはカレンダーに対する読み取り / 書き込みアクセス権を持っています。限定公開の予定は書き込みアクセス権を持つユーザーに表示され、予定の詳細が表示されます。
  • owner」 - ユーザーはカレンダーの所有権を持っています。このロールには、ライターのロールのすべての権限に加え、ACL を表示して操作する権限が追加されています。
defaultReminders[] list カレンダー上の認証済みユーザーのデフォルトのリマインダー。このリマインダーは、カレンダーで明示的にオーバーライドされていないすべての予定に適用されます(reminders.useDefault を True に設定していない)。
defaultReminders[].method string このリマインダーで使用されるメソッド。有効な値は次のとおりです。
  • email」 - リマインダーがメールで送信されます。
  • popup」 - リマインダーは UI のポップアップを介して送信されます。

リマインダーを追加する際には必須です。

書き込み可能
defaultReminders[].minutes integer 予定が始まる何分前からリマインダーをトリガーするか。有効な値は 0 ~ 40320(4 分)です。

リマインダーを追加する際には必須です。

書き込み可能
nextPageToken string この結果の次のページへのアクセスに使用されるトークン。これ以上の結果がない場合は省略します。その場合は nextSyncToken を指定します。
items[] list カレンダーの予定の一覧。
nextSyncToken string この結果が返された後に変更されたエントリのみを取得するために後で使用されるトークン。これ以上の結果がある場合は省略します。その場合は nextPageToken を指定します。

注: このメソッドで使用可能なコード例では、サポートされているプログラミング言語すべての例を示しているわけではありません(サポートされている言語の一覧については、クライアント ライブラリ ページをご覧ください)。

Java

Java クライアント ライブラリを使用します。

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Iterate over the events in the specified calendar
String pageToken = null;
do {
  Events events = service.events().list('primary').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

Python クライアント ライブラリを使用します。

page_token = None
while True:
  events = service.events().list(calendarId='primary', pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

PHP クライアント ライブラリを使用します。

$events = $service->events->listEvents('primary');

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->listEvents('primary', $optParams);
  } else {
    break;
  }
}

Ruby

Ruby クライアント ライブラリを使用します。

page_token = nil
begin
  result = client.list_events('primary', page_token: page_token)
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

実習

ライブデータでこのメソッドを呼び出してレスポンスを確認するには、以下の API Explorer を使用します。