Events: list

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

リクエスト

HTTP リクエスト

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

パラメータ

パラメータ名 値 説明
パスパラメータ
calendarId string カレンダー ID。カレンダー ID を取得するには、calendarList.list メソッドを呼び出します。現在ログインしているユーザーのメイン カレンダーにアクセスするには、「primary」キーワードを使用します。
省略可能なクエリ パラメータ
alwaysIncludeEmail boolean 非推奨であり、無視されます。
eventTypes string 返されるイベントタイプ。省略可。このパラメータを複数回繰り返して、さまざまなタイプのイベントを返すことができます。設定しない場合、すべてのイベントタイプを返します。

有効な値は次のとおりです。
  • 「birthday」: 年に 1 回繰り返される特別な終日の予定。
  • "default": 定期的なイベント。
  • 「focusTime」: サイレント モードの予定。
  • 「fromGmail」: Gmail からの予定。
  • 「outOfOffice」: 不在の予定。
  • 「workingLocation」: 勤務場所のイベント。
iCalUID string 応答で受け取る予定 ID を iCalendar 形式で指定します。省略可。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 自由記述形式の検索キーワードを使用すると、次のフィールドでこれらのキーワードに一致するイベントを検索できます:
  • summary
  • description
  • location
  • 参加者の displayName
  • 参加者の email
  • 主催者の displayName
  • 主催者の email
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

また、これらの検索キーワードは、勤務地、不在、集中時間のイベントの表示タイトルの翻訳すべてと事前定義されたキーワードを照合します。たとえば、「Office」または「Bureau」を検索すると、officeLocation タイプの勤務地イベントが返されますが、「Out of office」または「Abwesend」を検索すると、不在イベントが返されます。省略可。
sharedExtendedProperty string propertyName=value として指定された詳細プロパティの制約。共有プロパティのみが一致します。このパラメータは、指定されたすべての制約に一致するイベントを返すために複数回繰り返される場合があります。
showDeleted boolean 削除されたイベント（status が「cancelled」の場合）を結果に含めるかどうか。showDeleted と singleEvents の両方が False の場合、定期的な予定のキャンセルされたインスタンス（ただし、基になる定期的な予定は除く）は引き続き含まれます。showDeleted と singleEvents の両方が True の場合、削除されたイベントの 1 つのインスタンスのみが返されます（ただし、基になる定期的なイベントは返されません）。省略可。デフォルトは False です。
showHiddenInvitations boolean 非表示の招待状を結果に含めるかどうか。省略可。デフォルトは False です。
singleEvents boolean 定期的な予定をインスタンスに展開し、単一の 1 回限りの予定と定期的な予定のインスタンスのみを返すか、基になる定期的な予定自体も返すかを指定します。省略可。デフォルトは False です。
syncToken string 前のリスト リクエストの結果の最後のページで返された nextSyncToken フィールドから取得したトークン。これにより、このリスト リクエストの結果には、それ以降に変更されたエントリのみが含まれます。前回のリスト リクエスト以降に削除されたイベントはすべて、常に結果セットに含まれます。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 が設定されている場合、timeMax は timeMin より大きい値にする必要があります。
timeMin datetime フィルタするイベントの終了時間の下限（指定した時間は含まない）。省略可。デフォルトでは、終了時間でフィルタされません。タイムゾーン オフセットが必須の RFC3339 タイムスタンプである必要があります（例: 2011-06-03T10:00:00-07:00、2011-06-03T10:00:00Z）。ミリ秒を指定することもできますが、無視されます。timeMax を設定する場合、timeMin は timeMax より小さくする必要があります。
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 を使用して、ライブデータに対してこのメソッドを呼び出し、レスポンスを確認します。