الإشعارات الفورية

يصف هذا المستند كيفية استخدام الإشعارات الفورية التي تُعلِم تطبيقك عند تغيير أحد الموارد.

نظرة عامة

توفر واجهة برمجة التطبيقات Google Calendar API إشعارات فورية تتيح لك مراقبة التغييرات في الموارد. ويمكنك استخدام هذه الميزة لتحسين أداء تطبيقك. وهو يتيح لك التخلص من الشبكة الإضافية واحتساب التكاليف المرتبطة باستطلاع رأي الموارد لتحديد ما إذا كانت قد تغيّرت. كلما تغير مورد تمت مشاهدته، ترسل واجهة برمجة التطبيقات Google Calendar API إشعارًا إلى تطبيقك.

لاستخدام الإشعارات الفورية، يجب تنفيذ أمرين:

  • يمكنك إعداد عنوان URL للاستلام أو متلقي معاودة الاتصال "الرد التلقائي على الويب".

    هذا خادم HTTPS يتعامل مع رسائل إشعارات واجهة برمجة التطبيقات التي يتم تشغيلها عند تغيير أحد الموارد.

  • يمكنك إعداد قناة إشعارات لكل نقطة نهاية مورد تريد مشاهدتها.

    تحدد القناة معلومات التوجيه لرسائل الإشعارات. كجزء من عملية إعداد القناة، يجب تحديد عنوان URL المحدّد الذي تريد تلقّي الإشعارات عليه. عندما يتغيّر مورد القناة، ترسل Google Calendar API رسالة إشعار على شكل طلب POST إلى عنوان URL هذا.

في الوقت الحالي، تتيح واجهة برمجة التطبيقات Google Calendar API إرسال الإشعارات بشأن التغييرات في موارد Acl وCalendarList والأحداث والإعدادات.

إنشاء قنوات إشعارات

لطلب الإشعارات الفورية، عليك إعداد قناة إشعارات لكل مورد تريد مراقبته. بعد إعداد قنوات الإشعارات، سترسل Google Calendar API إشعارًا إلى تطبيقك عند إجراء أي تغييرات على أي من موارد الموارد التي تتم مشاهدتها.

تقديم طلبات المشاهدة

يحتوي كل مورد Google Calendar API قابل للمشاهدة على طريقة watch مرتبطة بعنوان URL على النحو التالي:

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 التي تم ضبطها على الطابع الزمني لـ Unix (بالمللي ثانية) للتاريخ والوقت اللذين تريد فيهما إيقاف Google Calendar API عن إرسال الرسائل إلى قناة الإشعارات هذه.

    إذا انتهت صلاحية القناة، يتم تضمينها كقيمة عنوان HTTP الذي يتضمّن العنصر X-Goog-Channel-Expiration (بتنسيق يمكن للمستخدمين قراءته) في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة.

لمزيد من التفاصيل حول الطلب، يُرجى الرجوع إلى طريقة watch لموارد Acl وCalendarList والأحداث والإعدادات في مرجع واجهة برمجة التطبيقات.

مشاهدة الردّ

إذا أنشأ طلب 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 والأحداث والإعدادات في مرجع واجهة برمجة التطبيقات.

مزامنة الرسالة

بعد إنشاء قناة إشعارات لمشاهدة مورد، ترسل Google Calendar API رسالة sync للإشارة إلى بدء إرسال الإشعارات. وتكون قيمة عنوان HTTP X-Goog-Resource-State لهذه الرسائل هي sync. بسبب مشاكل في توقيت الشبكة، من الممكن تلقّي رسالة sync حتى قبل تلقّي الردّ بطريقة watch.

يمكنك تجاهل إشعار 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

تحتوي رسائل المزامنة دائمًا على قيمة عنوان HTTP X-Goog-Message-Number وهي 1. يتضمّن كل إشعار لاحق لهذه القناة رقم رسالة أكبر من الرقم السابق، إلا أنّ أرقام الرسائل لن تكون تسلسلية.

تجديد قنوات الإشعارات

يمكن أن يكون لقناة الإشعارات وقت انتهاء صلاحية، مع قيمة يتم تحديدها إما من خلال طلبك أو بواسطة أي حدود داخلية لواجهة برمجة تطبيقات Google Calendar API أو إعدادات تلقائية (يتم استخدام القيمة الأكثر تقييدًا). ويتم تضمين وقت انتهاء صلاحية القناة، في حال توفّره، كطابع زمني Unix (بالمللي ثانية) في المعلومات التي تعرضها الطريقة watch. بالإضافة إلى ذلك، يتم تضمين تاريخ انتهاء الصلاحية والوقت (بتنسيق يمكن للمستخدمين قراءته) في كل رسالة إشعار يتلقّاها تطبيقك بخصوص هذه القناة في عنوان HTTP الذي يتضمّن العنصر X-Goog-Channel-Expiration.

لا تتوفّر حاليًا طريقة تلقائية لتجديد قناة الإشعارات. وعند الاقتراب من انتهاء صلاحية القناة، يجب استبدالها بقناة جديدة من خلال استخدام طريقة watch. وكالعادة، يجب استخدام قيمة فريدة للسمة id للقناة الجديدة. تجدر الإشارة إلى أنّه من المحتمل أن تكون هناك فترة "تداخل" تكون فيها قناتا الإشعارات التابعتان للمورد نفسه نشطتين.

استلام الإشعارات

وكلما تغيّر مورد مُراقب، يتلقّى تطبيقك رسالة إشعار تصف التغيير. ترسل Google Calendar API هذه الرسائل كطلبات HTTPS POST إلى عنوان URL الذي حدّدته كسمة address لقناة الإشعارات هذه.

تفسير تنسيق رسالة الإشعار

تشمل جميع رسائل الإشعارات مجموعة من عناوين HTTP التي تتضمّن بادئات X-Goog-. وقد تتضمن بعض أنواع الإشعارات أيضًا نص الرسالة.

العناوين

تتضمّن رسائل الإشعارات التي تم نشرها من خلال Google Calendar API إلى عنوان URL المستلِم عناوين HTTP التالية:

العنوان الوصف
مشاركة العرض دائمًا
X-Goog-Channel-ID المعرّف الفريد العالمي (UUID) أو سلسلة فريدة أخرى قدّمتها لتحديد قناة الإشعارات هذه
X-Goog-Message-Number عدد صحيح يحدِّد هذه الرسالة لقناة الإشعارات هذه. تكون القيمة دائمًا 1 لـ sync رسالة. ترتفع أرقام الرسائل لكل رسالة لاحقة على القناة، إلا أنّها لا تكون تسلسلية.
X-Goog-Resource-ID قيمة مبهمة تحدد المورد الذي تتم مشاهدته. هذا المعرّف ثابت في جميع إصدارات واجهة برمجة التطبيقات.
X-Goog-Resource-State حالة المورد الجديدة التي أدّت إلى ظهور الإشعار. القيم المتاحة: sync أو exists أو not_exists.
X-Goog-Resource-URI معرّف إصدار واجهة برمجة التطبيقات للمصدر الذي تتم مشاهدته.
يقيم أحيانًا
X-Goog-Channel-Expiration تاريخ ووقت انتهاء صلاحية قناة الإشعار، معبرَين عنهما بتنسيق يمكن للمستخدمين قراءته لا يوجد إلا إذا تم تحديده.
X-Goog-Channel-Token الرمز المميز لقناة الإشعار الذي حدّده تطبيقك، والذي يمكنك استخدامه للتحقق من مصدر الإشعارات. ولا تتوفر إلا إذا تم تحديدها.

لا تشتمل رسائل الإشعارات التي تنشرها واجهة برمجة تطبيقات "تقويم Google" إلى عنوان URL المُستلِم على نصّ الرسالة. لا تحتوي هذه الرسائل على معلومات محدَّدة حول الموارد المعدَّلة، وسيلزمك إجراء طلب بيانات آخر من واجهة برمجة التطبيقات للاطّلاع على التفاصيل الكاملة للتغيير.

أمثلة

تغيير رسالة الإشعار لمجموعة الأحداث المعدَّلة:

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.

إذا كانت خدمتك تستخدم مكتبة برامج واجهة برمجة التطبيقات من Google وتعرض 500 أو 502 أو 503 أو 504، تعيد واجهة برمجة تطبيقات تقويم Google إعادة محاولة الوصول باستخدام التراجع الأسي. يتم اعتبار كل رمز آخر لحالة الإرجاع على أنه خطأ في الرسالة.

فهم أحداث إشعارات Google Calendar API

يقدّم هذا القسم تفاصيل حول رسائل الإشعارات التي يمكنك تلقّيها عند استخدام الإشعارات الفورية من خلال Google Calendar API.

X-Goog-Resource-State ينطبق على وقت التسليم
sync قوائم التحكم بالوصول، وقوائم التقويم، والأحداث، والإعدادات. تم إنشاء قناة جديدة بنجاح. يُفترض أن تبدأ بتلقّي إشعارات بشأنه.
exists قوائم التحكم بالوصول، وقوائم التقويم، والأحداث، والإعدادات. حدث تغيير في أحد الموارد. وتشمل التغييرات المحتملة إنشاء مورد جديد، أو تعديل مورد حالي أو حذفه.

إيقاف الإشعارات

تتحكّم السمة expiration في وقت توقّف الإشعارات تلقائيًا. يمكنك اختيار إيقاف تلقّي الإشعارات من قناة معيّنة قبل انتهاء صلاحيتها، وذلك من خلال استدعاء طريقة stop على معرّف الموارد المنتظم التالي:

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

تتطلّب هذه الطريقة تقديم السمتَين id وresourceId للقناة على الأقل، كما هو موضّح في المثال أدناه. يُرجى العلم أنّه إذا كانت واجهة برمجة التطبيقات Google Calendar 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"
}