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

این سند نحوه استفاده از اعلان‌های فوری (push notifications) را شرح می‌دهد که هنگام تغییر یک منبع، به برنامه شما اطلاع می‌دهند.

نمای کلی

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

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

  • آدرس اینترنتی دریافتی یا گیرنده‌ی فراخوانی «وب‌هوک» خود را تنظیم کنید.

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

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

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

در حال حاضر، API تقویم گوگل از اعلان‌ها برای تغییرات در منابع Acl ، CalendarList ، Events و Settings پشتیبانی می‌کند.

ایجاد کانال‌های اعلان

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

درخواست‌های تماشا را انجام دهید

هر منبع API تقویم گوگل که قابلیت مشاهده دارد، یک متد 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

در بدنه درخواست، id کانال، type web_hook و آدرس اینترنتی دریافتی خود را در address وارد کنید. همچنین می‌توانید به صورت اختیاری موارد زیر را نیز وارد کنید:

  • یک token برای استفاده به عنوان توکن کانال شما.
  • زمان expiration بر حسب میلی‌ثانیه برای زمان انقضای کانال درخواستی شما.

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

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

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

    مقدار شناسه‌ای که تنظیم کرده‌اید، در هدر HTTP مربوط به X-Goog-Channel-Id هر پیام اعلانی که برای این کانال دریافت می‌کنید، منعکس می‌شود.

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

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

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

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

خواص اختیاری

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

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

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

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

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

    • داده‌های حساس مانند توکن‌های OAuth را وارد نکنید.

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

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

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

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

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

بدنه پاسخ جزئیات کانال مانند موارد زیر را ارائه می‌دهد:

  • kind : این را به عنوان یک منبع کانال API شناسایی می‌کند.
  • id : شناسه‌ای که برای این کانال مشخص کرده‌اید.
  • resourceId : شناسه منبع تحت نظر.
  • resourceUri : شناسه‌ی مختص به نسخه از منبعِ تحتِ نظر.
  • token : توکنی که در بدنه درخواست ارائه شده است.
  • expiration : زمان انقضای کانال به صورت یک مهر زمانی یونیکس بر حسب میلی‌ثانیه.

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

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

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

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

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

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

قالب پیام‌های sync که API تقویم گوگل به آدرس اینترنتی دریافتی شما ارسال می‌کند، در زیر نشان داده شده است.

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

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

کانال‌های اعلان را تمدید کنید

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

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

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

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

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

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

سربرگ‌ها

پیام‌های اعلان ارسال شده توسط API تقویم گوگل به آدرس اینترنتی دریافتی شما شامل هدرهای HTTP زیر هستند:

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

پیام‌های اعلان ارسال شده توسط API تقویم گوگل به آدرس اینترنتی دریافتی شما، شامل متن پیام نیستند. این پیام‌ها حاوی اطلاعات خاصی در مورد منابع به‌روزرسانی‌شده نیستند، برای مشاهده جزئیات کامل تغییر، باید یک فراخوانی 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 گوگل استفاده می‌کند و مقادیر 500 ، 502 ، 503 یا 504 را برمی‌گرداند، API تقویم گوگل با یک backoff نمایی دوباره تلاش می‌کند. هر کد وضعیت بازگشتی دیگر، به عنوان یک پیام ناموفق در نظر گرفته می‌شود.

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

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

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

توقف اعلان‌ها

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

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

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

فقط کاربرانی که مجوز لازم را دارند می‌توانند یک کانال را متوقف کنند. به ویژه:

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

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

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"
}