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

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

نظرة عامة

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

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

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

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

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

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

وفي الوقت الحالي، تدعم واجهة برمجة تطبيقات تقويم Google الإشعارات الخاصة بالتغييرات على موارد Acl وCalendarList والأحداث والإعدادات.

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

لطلب الإشعارات الفورية، يجب إعداد قناة للإشعارات. لكل مورد تريد مراقبته. بعد ضبط قنوات الإشعارات ستبلغ واجهة برمجة تطبيقات Google Calendar 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" إرسال الإشعارات إلى عنوان 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 المعرّف الفريد العالمي أو سلسلة فريدة أخرى قدّمتها لتحديد ذلك .
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 Calendar API على عنوان 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 قوائم ACL وقوائم التقويم والأحداث والإعدادات. تم إنشاء قناة جديدة بنجاح. ويمكنك توقّع بدء تلقّي إشعارات بشأنه.
exists قوائم ACL وقوائم التقويم والأحداث والإعدادات. حدث تغيير في مورد. تشمل التغييرات المحتملة إنشاء مورد جديد أو تعديل مورد حالي أو حذفه.

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

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

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

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