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

مجوز

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

محدوده
`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`
`https://www.googleapis.com/auth/calendar.app.created`
`https://www.googleapis.com/auth/calendar.events.freebusy`
`https://www.googleapis.com/auth/calendar.events.owned`
`https://www.googleapis.com/auth/calendar.events.owned.readonly`
`https://www.googleapis.com/auth/calendar.events.public.readonly`

برای اطلاعات بیشتر، به صفحه احراز هویت و مجوز مراجعه کنید.

درخواست بدنه

با این روش، بدنه درخواست را ارائه ندهید.

پاسخ

در صورت موفقیت، این متد یک بدنه پاسخ با ساختار زیر برمی‌گرداند:

{
  "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`	برچسب الکترونیکی مجموعه.
`summary`	`string`	عنوان تقویم. فقط خواندنی.
`description`	`string`	شرح تقویم. فقط خواندنی.
`updated`	`datetime`	زمان آخرین تغییر تقویم (به عنوان مهر زمانی RFC3339 ). فقط خواندنی.
`timeZone`	`string`	منطقه زمانی تقویم. فقط خواندنی.
`accessRole`	`string`	نقش دسترسی کاربر برای این تقویم. فقط خواندنی. مقادیر ممکن عبارتند از: « `none` » - کاربر هیچ دسترسی ندارد. « `freeBusyReader` » - کاربر به اطلاعات آزاد/مشغول دسترسی خواندن دارد. « `reader` » - کاربر دسترسی خواندن تقویم را دارد. رویدادهای خصوصی برای کاربرانی که دسترسی خواندن دارند نمایش داده می‌شوند، اما جزئیات رویداد پنهان خواهد بود. « `writer` » - کاربر دسترسی خواندن و نوشتن به تقویم را دارد. رویدادهای خصوصی برای کاربرانی که دسترسی نویسنده دارند نمایش داده می‌شوند و جزئیات رویداد قابل مشاهده خواهد بود. « `owner` » - کاربر دسترسی مدیریتی به تقویم دارد. این نقش تمام مجوزهای نقش نویسنده را به همراه قابلیت اضافی مشاهده و تغییر سطوح دسترسی سایر کاربران دارد. مهم: نقش `owner` با مالک داده‌های تقویم متفاوت است. یک تقویم یک مالک داده دارد، اما می‌تواند چندین کاربر با نقش `owner` داشته باشد.
`defaultReminders[]`	`list`	یادآوری‌های پیش‌فرض در تقویم برای کاربر احراز هویت‌شده. این یادآوری‌ها برای تمام رویدادهای این تقویم که صریحاً آنها را لغو نمی‌کنند (یعنی `reminders.useDefault` روی True تنظیم نشده باشد) اعمال می‌شوند.
`defaultReminders[]. method`	`string`	روشی که این یادآوری استفاده می‌کند. مقادیر ممکن عبارتند از: « `email` » - یادآوری‌ها از طریق ایمیل ارسال می‌شوند. « `popup` » - یادآوری‌ها از طریق یک پنجره بازشو در رابط کاربری ارسال می‌شوند. هنگام اضافه کردن یادآوری الزامی است.	قابل نوشتن
`defaultReminders[]. minutes`	`integer`	تعداد دقایق قبل از شروع رویداد که یادآوری باید فعال شود. مقادیر معتبر بین ۰ تا ۴۰۳۲۰ (۴ هفته به دقیقه) هستند. هنگام اضافه کردن یادآوری الزامی است.	قابل نوشتن
`nextPageToken`	`string`	توکنی که برای دسترسی به صفحه بعدی این نتیجه استفاده می‌شود. در صورت عدم وجود نتایج بیشتر، حذف می‌شود، در این صورت `nextSyncToken` ارائه می‌شود.
`items[]`	`list`	فهرست مناسبت‌ها در تقویم.
`nextSyncToken`	`string`	توکنی که در برهه‌ای از زمان برای بازیابی فقط ورودی‌هایی که از زمان برگرداندن این نتیجه تغییر کرده‌اند، استفاده شده است. در صورت موجود بودن نتایج بیشتر، حذف می‌شود که در این صورت `nextPageToken` ارائه می‌شود.

امتحانش کن!

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