این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Events: list

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

درخواست

درخواست HTTP

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

مولفه های

نام پارامتر	ارزش	شرح
پارامترهای مسیر
`calendarId`	`string`	شناسه تقویم برای بازیابی شناسه های تقویم با روش calendarList.list تماس بگیرید. اگر می‌خواهید به تقویم اصلی کاربر وارد شده در حال حاضر دسترسی داشته باشید، از کلمه کلیدی " `primary` " استفاده کنید.
پارامترهای پرس و جو اختیاری
`alwaysIncludeEmail`	`boolean`	منسوخ و نادیده گرفته شده است.
`eventTypes`	`string`	انواع رویداد برای بازگشت اختیاری. این پارامتر را می توان چندین بار تکرار کرد تا رویدادهای انواع مختلف را برگرداند. اگر تنظیم نشود، همه انواع رویداد را برمی‌گرداند. مقادیر قابل قبول عبارتند از: " `default` ": رویدادهای منظم. " `focusTime` ": روی رویدادهای زمانی تمرکز کنید. " `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 زیر برای فراخوانی این روش در داده‌های زنده و دیدن پاسخ استفاده کنید.