Events: list

رویدادها را در تقویم مشخص شده برمی‌گرداند. اکنون آن را امتحان کنید یا نمونه ای را ببینید .

درخواست کنید

درخواست HTTP 

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

پارامترها

نام پارامتر ارزش توضیحات
پارامترهای مسیر
calendarId string شناسه تقویم برای بازیابی شناسه های تقویم با روش calendarList.list تماس بگیرید. اگر می‌خواهید به تقویم اصلی کاربر وارد شده در حال حاضر دسترسی داشته باشید، از کلمه کلیدی " primary " استفاده کنید.
پارامترهای پرس و جو اختیاری
alwaysIncludeEmail boolean منسوخ و نادیده گرفته شده است.
eventTypes string انواع رویداد برای بازگشت اختیاری. این پارامتر را می توان چندین بار تکرار کرد تا رویدادهای انواع مختلف را برگرداند. اگر تنظیم نشود، همه انواع رویداد را برمی‌گرداند.

مقادیر قابل قبول عبارتند از:
  • " birthday ": رویدادهای ویژه تمام روز با تکرار سالانه.
  • " default ": رویدادهای منظم.
  • " focusTime ": روی رویدادهای زمانی تمرکز کنید.
  • " fromGmail ": رویدادهایی از Gmail.
  • " outOfOffice ": رویدادهای خارج از دفتر.
  • " workingLocation ": رویدادهای محل کار.
iCalUID string شناسه رویداد را در قالب iCalendar مشخص می کند تا در پاسخ ارائه شود. اختیاری. اگر می‌خواهید رویدادی را با شناسه iCalendar آن جستجو کنید، از این استفاده کنید.
maxAttendees integer حداکثر تعداد شرکت کنندگانی که باید در پاسخ درج شود. در صورتی که تعداد شرکت کنندگان بیشتر از تعداد مشخص شده باشد، فقط شرکت کننده برگردانده می شود. اختیاری.
maxResults integer حداکثر تعداد رویدادهای بازگشتی در یک صفحه نتیجه. تعداد رویدادها در صفحه حاصل ممکن است کمتر از این مقدار باشد یا اصلاً هیچ کدام نباشد، حتی اگر رویدادهای بیشتری مطابق با پرس و جو وجود داشته باشد. صفحات ناقص را می توان با یک قسمت غیر خالی nextPageToken در پاسخ شناسایی کرد. به طور پیش فرض مقدار 250 رویداد است. اندازه صفحه هرگز نمی تواند بزرگتر از 2500 رویداد باشد. اختیاری.
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 هر دو نادرست باشند، نمونه‌های لغو شده رویدادهای تکرارشونده (اما نه رویداد تکرارشونده زمینه‌ای) همچنان شامل خواهند شد. اگر showDeleted و singleEvents هر دو True باشند، تنها نمونه‌های منفرد از رویدادهای حذف شده (اما نه رویدادهای تکرارشونده اصلی) برگردانده می‌شوند. اختیاری. پیش فرض نادرست است.
showHiddenInvitations boolean اینکه آیا دعوت‌نامه‌های مخفی در نتیجه گنجانده شود. اختیاری. پیش فرض نادرست است.
singleEvents boolean اینکه رویدادهای تکرار شونده را به نمونه‌ها گسترش دهیم و فقط رویدادهای یک‌باره و نمونه‌هایی از رویدادهای تکرار شونده را بازگردانیم، اما نه خود رویدادهای تکرار شونده اساسی. اختیاری. پیش فرض نادرست است.
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 گنجانده می‌شوند. اختیاری. پیش فرض این است که بر اساس آخرین زمان اصلاح فیلتر نشود.

مجوز

این درخواست اجازه مجوز با حداقل یکی از حوزه های زیر را می دهد:

دامنه
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 ارائه می شود.

نمونه ها

توجه: نمونه‌های کد موجود برای این روش همه زبان‌های برنامه‌نویسی پشتیبانی‌شده را نشان نمی‌دهند (برای فهرست زبان‌های پشتیبانی‌شده به صفحه کتابخانه‌های سرویس گیرنده مراجعه کنید).

جاوا

از کتابخانه سرویس گیرنده جاوا استفاده می کند. 

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);

پایتون

از کتابخانه کلاینت پایتون استفاده می کند. 

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 استفاده می کند. 

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?

آن را امتحان کنید!

از APIs Explorer زیر برای فراخوانی این روش در داده‌های زنده و دیدن پاسخ استفاده کنید.