اعلان های فشاری

این سند نحوه استفاده از اعلان‌های فشاری را توضیح می‌دهد که برنامه شما را هنگام تغییر منبع مطلع می‌کند.

نمای کلی

Google Calendar API اعلان‌های فشاری را ارائه می‌کند که به شما امکان می‌دهد تغییرات منابع را نظارت کنید. می توانید از این ویژگی برای بهبود عملکرد برنامه خود استفاده کنید. این به شما امکان می دهد شبکه اضافی را حذف کنید و هزینه های مربوط به منابع نظرسنجی را محاسبه کنید تا مشخص کنید آیا تغییر کرده اند یا خیر. هر زمان که یک منبع مشاهده شده تغییر کند، API تقویم Google به برنامه شما اطلاع می دهد.

برای استفاده از اعلان‌های فشاری، باید دو کار انجام دهید:

  • URL دریافتی خود یا گیرنده پاسخ به تماس "webhook" را تنظیم کنید.

    این یک سرور HTTPS است که پیام‌های اعلان API را که هنگام تغییر یک منبع فعال می‌شوند، مدیریت می‌کند.

  • برای هر نقطه پایانی منبعی که می خواهید تماشا کنید ( کانال اطلاع رسانی ) تنظیم کنید.

    یک کانال اطلاعات مسیریابی پیام های اعلان را مشخص می کند. به عنوان بخشی از راه‌اندازی کانال، باید URL خاصی را که می‌خواهید اعلان‌ها را دریافت کنید، شناسایی کنید. هر زمان که منبع کانال تغییر کند، Google Calendar API یک پیام اعلان به عنوان یک درخواست POST به آن URL ارسال می کند.

در حال حاضر، Google Calendar API از اعلان‌ها برای تغییرات در منابع Acl ، CalendarList ، رویدادها و تنظیمات پشتیبانی می‌کند.

ایجاد کانال های اطلاع رسانی

برای درخواست اعلان‌های فشاری، باید یک کانال اعلان برای هر منبعی که می‌خواهید نظارت کنید راه‌اندازی کنید. پس از راه‌اندازی کانال‌های اعلان، Google Calendar API برنامه شما را در صورت تغییر هر منبع مشاهده شده مطلع می‌کند.

درخواست تماشا کنید

هر منبع API تقویم Google قابل مشاهده دارای یک روش watch مرتبط در یک URI به شکل زیر است:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

برای راه‌اندازی یک کانال اعلان برای پیام‌های مربوط به تغییرات یک منبع خاص، یک درخواست POST به روش watch منبع ارسال کنید.

هر کانال اعلان هم با یک کاربر خاص و هم با یک منبع خاص (یا مجموعه ای از منابع) مرتبط است. درخواست watch موفق نخواهد شد مگر اینکه کاربر فعلی مالک یا اجازه دسترسی به این منبع را داشته باشد.

مثال

شروع به تماشای تغییرات در مجموعه ای از رویدادها در یک تقویم معین کنید: 

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

خواص مورد نیاز

با هر درخواست watch ، باید این فیلدها را ارائه دهید:

  • یک رشته ویژگی id که به طور منحصر به فرد این کانال اعلان جدید را در پروژه شما شناسایی می کند. توصیه می کنیم از یک شناسه منحصر به فرد جهانی ( UUID ) یا هر رشته منحصر به فرد مشابهی استفاده کنید. حداکثر طول: 64 کاراکتر.

    مقدار شناسه ای که تنظیم کرده اید در سرصفحه HTTP X-Goog-Channel-Id هر پیام اعلانی که برای این کانال دریافت می کنید بازتاب می یابد.

  • یک type رشته ویژگی با مقدار web_hook تنظیم شده است.

  • یک رشته ویژگی address روی URL تنظیم شده است که به اعلان‌های این کانال اعلان گوش می‌دهد و به آن پاسخ می‌دهد. این URL پاسخ به تماس وب هوک شما است و باید از HTTPS استفاده کند.

    توجه داشته باشید که Google Calendar API فقط در صورتی می‌تواند اعلان‌ها را به این آدرس HTTPS ارسال کند که یک گواهی SSL معتبر روی سرور وب شما نصب شده باشد. گواهینامه های نامعتبر عبارتند از:

    • گواهی های خود امضا شده
    • گواهی امضا شده توسط یک منبع نامعتبر.
    • گواهی هایی که باطل شده اند.
    • گواهینامه هایی که موضوعی دارند که با نام میزبان هدف مطابقت ندارد.

خواص اختیاری

همچنین می توانید این فیلدهای اختیاری را با درخواست watch خود مشخص کنید:

  • یک ویژگی token که یک مقدار رشته دلخواه را برای استفاده به عنوان نشانه کانال مشخص می کند. می توانید از نشانه های کانال اطلاع رسانی برای اهداف مختلف استفاده کنید. برای مثال، می‌توانید از این رمز برای تأیید اینکه هر پیام دریافتی مربوط به کانالی است که برنامه شما ایجاد کرده است استفاده کنید - برای اطمینان از اینکه اعلان جعلی نیست - یا برای هدایت پیام به مقصد مناسب در برنامه خود بر اساس هدف این کانال حداکثر طول: 256 کاراکتر.

    این توکن در هدر HTTP X-Goog-Channel-Token در هر پیام اعلانی که برنامه شما برای این کانال دریافت می کند گنجانده شده است.

    اگر از نشانه های کانال اطلاع رسانی استفاده می کنید، توصیه می کنیم:

    • از یک قالب رمزگذاری قابل توسعه مانند پارامترهای جستجوی URL استفاده کنید. مثال: forwardTo=hr&createdBy=mobile

    • داده های حساس مانند نشانه های OAuth را درج نکنید.

  • یک رشته ویژگی expiration مهر زمانی یونیکس (بر حسب میلی ثانیه) از تاریخ و زمانی تنظیم شده است که می‌خواهید Google Calendar API ارسال پیام برای این کانال اعلان را متوقف کند.

    اگر یک کانال دارای زمان انقضا باشد، به عنوان مقدار هدر HTTP X-Goog-Channel-Expiration (در قالب قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال دریافت می کند، لحاظ می شود.

برای جزئیات بیشتر در مورد درخواست، به روش watch برای منابع Acl ، CalendarList ، رویدادها و تنظیمات در مرجع API مراجعه کنید.

پاسخ را تماشا کنید

اگر درخواست watch با موفقیت یک کانال اعلان ایجاد کند، یک کد وضعیت HTTP 200 OK برمی‌گرداند.

بدنه پیام پاسخ ساعت، اطلاعاتی را در مورد کانال اعلانی که ایجاد کرده اید، ارائه می دهد، همانطور که در مثال زیر نشان داده شده است.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

علاوه بر ویژگی هایی که به عنوان بخشی از درخواست خود ارسال کرده اید، اطلاعات بازگردانده شده همچنین شامل resourceId و resourceUri برای شناسایی منبعی است که در این کانال اعلان مشاهده می شود.

می‌توانید اطلاعات برگشتی را به سایر عملیات کانال اعلان ارسال کنید، مانند زمانی که می‌خواهید دریافت اعلان‌ها را متوقف کنید .

برای جزئیات بیشتر در مورد پاسخ، به روش watch برای منابع Acl ، CalendarList ، رویدادها و تنظیمات در مرجع API مراجعه کنید.

همگام سازی پیام

پس از ایجاد یک کانال اعلان برای تماشای یک منبع، Google Calendar API یک پیام sync ارسال می‌کند تا نشان دهد اعلان‌ها شروع می‌شوند. مقدار هدر HTTP X-Goog-Resource-State برای این پیام ها sync است. به دلیل مشکلات زمان‌بندی شبکه، ممکن است حتی قبل از دریافت پاسخ روش watch ، پیام sync را دریافت کنید.

نادیده گرفتن اعلان sync بی خطر است، اما می توانید از آن نیز استفاده کنید. برای مثال، اگر تصمیم گرفتید که نمی‌خواهید کانال را حفظ کنید، می‌توانید از مقادیر X-Goog-Channel-ID و X-Goog-Resource-ID در یک تماس برای توقف دریافت اعلان‌ها استفاده کنید. همچنین می توانید از اعلان sync برای انجام مقداری مقداردهی اولیه برای آماده شدن برای رویدادهای بعدی استفاده کنید.

قالب پیام‌های sync که Google Calendar API به URL دریافتی شما ارسال می‌کند در زیر نشان داده شده است.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

پیام‌های همگام‌سازی همیشه دارای مقدار سرصفحه X-Goog-Message-Number HTTP 1 هستند. هر اعلان بعدی برای این کانال دارای یک شماره پیام است که بزرگتر از شماره قبلی است، اگرچه شماره پیام ها متوالی نخواهد بود.

کانال های اطلاع رسانی را تمدید کنید

یک کانال اعلان می‌تواند یک زمان انقضا داشته باشد، با مقداری که با درخواست شما یا هر محدودیت داخلی یا پیش‌فرض Google Calendar API تعیین می‌شود (مقدار محدودتر استفاده می‌شود). زمان انقضای کانال، در صورت وجود، به عنوان مهر زمانی یونیکس (بر حسب میلی ثانیه) در اطلاعاتی که با روش watch بازگردانده می شود، لحاظ می شود. علاوه بر این، تاریخ و زمان انقضا (در قالب قابل خواندن توسط انسان) در هر پیام اعلانی که برنامه شما برای این کانال در هدر X-Goog-Channel-Expiration HTTP دریافت می کند گنجانده شده است.

در حال حاضر، هیچ راه خودکاری برای تمدید کانال اعلان وجود ندارد. زمانی که یک کانال به انقضای خود نزدیک است، باید با فراخوانی روش watch ، آن را با کانال جدید جایگزین کنید. مثل همیشه، باید از یک مقدار منحصر به فرد برای ویژگی id کانال جدید استفاده کنید. توجه داشته باشید که زمانی که دو کانال اعلان برای یک منبع فعال هستند، احتمالاً یک دوره زمانی "همپوشانی" وجود دارد.

اعلان ها را دریافت کنید

هر زمان که یک منبع مشاهده شده تغییر کند، برنامه شما یک پیام اعلان دریافت می کند که تغییرات را توصیف می کند. Google Calendar API این پیام‌ها را به‌عنوان درخواست HTTPS POST به نشانی اینترنتی که به‌عنوان ویژگی address برای این کانال اعلان مشخص کرده‌اید ارسال می‌کند.

قالب پیام اعلان را تفسیر کنید

همه پیام‌های اعلان شامل مجموعه‌ای از هدرهای HTTP هستند که دارای پیشوندهای X-Goog- هستند. برخی از انواع اعلان‌ها می‌توانند شامل متن پیام نیز باشند.

سرصفحه ها

پیام‌های اعلان ارسال شده توسط Google Calendar API به URL دریافتی شما شامل سرصفحه‌های HTTP زیر است:

سربرگ توضیحات
همیشه حاضر
X-Goog-Channel-ID UUID یا رشته منحصر به فردی که برای شناسایی این کانال اعلان ارائه کرده اید.
X-Goog-Message-Number عدد صحیحی که این پیام را برای این کانال اعلان شناسایی می کند. مقدار همیشه برای sync پیام‌ها 1 است. تعداد پیام ها برای هر پیام بعدی در کانال افزایش می یابد، اما ترتیبی نیستند.
X-Goog-Resource-ID یک مقدار غیر شفاف که منبع تماشا شده را شناسایی می کند. این شناسه در نسخه‌های API پایدار است.
X-Goog-Resource-State وضعیت منبع جدیدی که اعلان را راه‌اندازی کرد. مقادیر ممکن: sync , exists , or not_exists .
X-Goog-Resource-URI یک شناسه مخصوص نسخه API برای منبع تماشا شده.
گاهی حضور دارد
X-Goog-Channel-Expiration تاریخ و زمان انقضای کانال اطلاع رسانی، در قالب قابل خواندن توسط انسان بیان شده است. فقط در صورت تعریف وجود دارد.
X-Goog-Channel-Token نشانه کانال اعلان که توسط برنامه شما تنظیم شده است و می توانید از آن برای تأیید منبع اعلان استفاده کنید. فقط در صورت تعریف وجود دارد.

پیام‌های اعلان ارسال شده توسط Google Calendar API به URL دریافتی شما حاوی متن پیام نیستند. این پیام‌ها حاوی اطلاعات خاصی در مورد منابع به‌روزرسانی‌شده نیستند، برای مشاهده جزئیات کامل تغییر، باید یک تماس API دیگر برقرار کنید.

نمونه ها

تغییر پیام اعلان برای مجموعه تغییر یافته از رویدادها: 

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

به اطلاعیه ها پاسخ دهید

برای نشان دادن موفقیت، می توانید یکی از کدهای وضعیت زیر را برگردانید: 200 ، 201 ، 202 ، 204 ، یا 102 .

اگر سرویس شما از کتابخانه سرویس گیرنده API Google استفاده می کند و 500 ، 502 ، 503 یا 504 را برمی گرداند، Google Calendar API دوباره با عقب نشینی نمایی تلاش می کند. هر کد وضعیت بازگشت دیگری به عنوان یک پیام ناموفق در نظر گرفته می شود.

رویدادهای اعلان API تقویم Google را درک کنید

این بخش جزئیات پیام‌های اعلان‌هایی را که می‌توانید هنگام استفاده از اعلان‌های فشار با API Google Calendar دریافت کنید، ارائه می‌کند.

X-Goog-Resource-State اعمال می شود تحویل زمانی
sync ACL ها، لیست های تقویم، رویدادها، تنظیمات. یک کانال جدید با موفقیت ایجاد شد. می توانید انتظار داشته باشید که برای آن اعلان دریافت کنید.
exists ACL ها، لیست های تقویم، رویدادها، تنظیمات. تغییری در یک منبع وجود داشت. تغییرات احتمالی شامل ایجاد یک منبع جدید، یا اصلاح یا حذف یک منبع موجود است.

توقف اعلان ها

ویژگی expiration زمانی را کنترل می کند که اعلان ها به طور خودکار متوقف شوند. می‌توانید با فراخوانی روش stop در URI زیر، دریافت اعلان‌ها را برای یک کانال خاص قبل از منقضی شدن آن متوقف کنید:

https://www.googleapis.com/calendar/v3/channels/stop

این روش مستلزم آن است که حداقل id کانال و ویژگی های resourceId را همانطور که در مثال زیر نشان داده شده است ارائه دهید. توجه داشته باشید که اگر Google Calendar API چندین نوع منبع داشته باشد که دارای روش‌های watch هستند، تنها یک روش stop وجود دارد.

فقط کاربران با مجوز مناسب می توانند کانال را متوقف کنند. به طور خاص:

  • اگر کانال توسط یک حساب کاربری معمولی ایجاد شده باشد، فقط همان کاربر از همان مشتری (همانطور که توسط شناسه های مشتری OAuth 2.0 از نشانه های auth مشخص شده است) که کانال را ایجاد کرده است می تواند کانال را متوقف کند.
  • اگر کانال توسط یک حساب سرویس ایجاد شده باشد، هر کاربر از همان مشتری می تواند کانال را متوقف کند.

نمونه کد زیر نحوه توقف دریافت اعلان ها را نشان می دهد: 

POST https://www.googleapis.com/calendar/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}