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

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

نظرة عامة

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

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

  • إعداد عنوان URL لتلقّي الردّ أو جهاز استقبال الردّ التلقائي على الويب

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

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

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

تتيح Directory API حاليًا إرسال إشعارات بشأن التغييرات التي تطرأ على موارد Users.

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

لطلب الإشعارات الفورية، يجب إعداد قناة للإشعارات. لكل مورد تريد مراقبته. بعد ضبط قنوات الإشعارات ستبلغ واجهة برمجة التطبيقات للدليل تطبيقك عند رصد أي مورد التغييرات.

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

يرتبط كلّ مورد قابل للمشاهدة في Directory API بطريقة watch على معرّف موارد منتظم (URI) بالشكل التالي:

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

لإعداد قناة إشعارات للرسائل المتعلقة بالتغييرات في مورد معين، يمكنك إرسال طلب POST إلى طريقة watch للمورد.

ترتبط كل قناة من قنوات الإشعارات بمستخدم معين مورد معين (أو مجموعة موارد). لن يتمكّن طلب watch من النجاح ما لم يكن المستخدِم الحالي أو حساب الخدمة يملكان هذا المورد أو يملكان الإذن بالوصول إليه.

أمثلة

تكون جميع طلبات المشاهدة لمورد "User" لنطاق واحد بالشكل العام:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

استخدِم المَعلمتَين domain وevent لتحديد النطاق ونوع الحدث الذي تريد تلقّي إشعارات بشأنه.

تكون جميع طلبات المشاهدة لمورد المستخدم الخاص بالعميل بالتنسيق العام:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

استخدِم المَعلمتَين customer وevent لتحديد المعرّف الفريد لحساب العميل على Google ونوع الحدث الذي تريد تلقّي إشعارات بشأنه.

القيم المحتمَلة لسمة event هي:

  • add: حدث من إنشاء المستخدِم
  • delete: حدث حذفه المستخدم
  • makeAdmin: حدث تغيير حالة مشرف المستخدم
  • undelete: حدث إلغاء حذف المستخدم
  • update: حدث عدّله المستخدم

ملاحظة: تحذف الأمثلة التالية محتوى الطلب من أجل الوضوح.

مراقبة الأحداث التي أنشأها المستخدمون للنطاق mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

مراقبة الأحداث التي أنشأها المستخدم للعميل my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

الخصائص المطلوبة

مع كل طلب watch، يجب تقديم الحقول التالية:

  • سلسلة السمة id التي تعرّف هذا العنصر بشكل فريد قناة إشعارات جديدة ضمن مشروعك. ننصحك باستخدام معرّف فريد على مستوى العالم (UUID) أو أي سلسلة فريدة مشابهة . الحد الأقصى للطول: 64 حرفًا.

    يتم تكرار قيمة المعرّف التي تحدّدها في X-Goog-Channel-Id عنوان HTTP لكل رسالة إشعار تصلك من هذه القناة.

  • سلسلة خاصية type تم ضبطها على القيمة web_hook

  • سلسلة موقع address تم ضبطها على عنوان URL الذي يستمع ويستجيب للإشعارات في قناة الإشعارات هذه. هذا هو عنوان URL لطلب إعادة الاتصال بتطبيقك على الويب، ويجب أن يستخدم بروتوكول HTTPS.

    يُرجى العِلم أنّ واجهة برمجة التطبيقات Directory API لا يمكنها إرسال إشعارات إلى عنوان HTTPS هذا إلا إذا كانت هناك شهادة SSL صالحة مثبّتة على خادم الويب. تشتمل الشهادات غير الصالحة على:

    • الشهادات الموقعة ذاتيًا.
    • الشهادات الموقَّعة من مصدر غير موثوق به.
    • الشهادات التي تم إبطالها.
    • الشهادات التي تحتوي على موضوع لا يتطابق مع الهدف اسم المضيف.

السمات الاختيارية

ويمكنك أيضًا تحديد هذه الحقول الاختيارية طلب "watch":

  • سمة token تحدّد سلسلة عشوائية استخدامه كرمز مميز للقناة. يمكنك استخدام علامات قناة الإشعارات لأغراض مختلفة. على سبيل المثال، يمكنك استخدام دالة الرسم للتأكد من أن كل رسالة واردة هي لقناة إنشاء تطبيق — للتأكد من عدم تشغيل الإشعار أو انتحالها — أو لتوجيه الرسالة إلى الوجهة الصحيحة داخل طلبك استنادًا إلى الغرض من هذه القناة. الحد الأقصى للطول: 256 حرفًا

    يتم تضمين الرمز المميز في عنوان HTTP يتضمّن X-Goog-Channel-Token في كل إشعار التي يتلقاها طلبك المتعلق بهذه القناة.

    في حال استخدام الرموز المميّزة لقناة الإشعارات، ننصحك بما يلي:

    • استخدِم تنسيق ترميز قابلاً للامتداد، مثل طلب بحث عن عنوان URL. المعلَمات. مثلاً: forwardTo=hr&createdBy=mobile

    • لا تُدرِج بيانات حسّاسة، مثل رموز OAuth.

  • تم ضبط سلسلة السمة expiration على سمة الطابع الزمني لـ Unix (بالمللي ثانية) من التاريخ والوقت اللذين تريد من واجهة برمجة التطبيقات للدليل إيقاف إرسال الرسائل لقناة الإشعارات هذه.

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

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

عرض الرد

إذا أنشأ طلب "watch" إشعارًا بنجاح فستعرض رمز حالة HTTP 200 OK.

يقدّم نص رسالة الاستجابة للمشاهدة معلومات عن قناة الإشعارات التي أنشأتها للتو، كما هو موضّح في المثال أدناه.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

بالإضافة إلى المواقع التي أرسلتها كجزء من طلبك، كما تتضمن المعلومات التي تم إرجاعها resourceId resourceUri لتحديد المورد الذي تتم مشاهدته على هذا المحتوى .

يمكنك تمرير المعلومات التي تم إرجاعها إلى قناة إشعارات أخرى. عمليات مثل عندما تريد إيقاف تلقي الإشعارات

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

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

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

يمكنك تجاهل إشعار "sync"، ولكن يمكنك استخدامه أيضًا. على سبيل المثال، إذا قررت عدم الاحتفاظ بالقناة، يمكنك استخدام القيمتَين X-Goog-Channel-ID و X-Goog-Resource-ID في مكالمة لالتوقف عن تلقّي الإشعارات. يمكنك أيضًا استخدام صفحة إشعار sync لإجراء بعض الإعداد من أجل الاستعداد أحداث لاحقة.

تنسيق رسائل sync التي ترسلها واجهة برمجة تطبيقات الدليل إليها يظهر أدناه عنوان 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. يحمل كل إشعار لاحق لهذه القناة رقم رسالة أكبر من الرقم السابق، ولكن لن تكون أرقام الرسائل متسلسلة.

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

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

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

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

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

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

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

العناوين

تتضمّن رسائل الإشعارات التي تنشرها واجهة برمجة التطبيقات Directory API على عنوان URL المخصّص لتلقّيها عناوين HTTP التالية:

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

تحتوي رسائل الإشعارات المرسَلة إلى المستخدمين على المعلومات التالية في نص الطلب:

الموقع الوصف
kind تُحدِّد هذه السمة هذا العنصر على أنّه مورد مستخدم. القيمة: السلسلة الثابتة "admin#directory#user".
id المعرّف الفريد لمورد المستخدم.
etag علامة ETag لرسالة الإشعار. يختلف عن علامة ETag لمورد User.
primaryEmail عنوان البريد الإلكتروني الرئيسي للمستخدم

أمثلة

تتّبع رسائل الإشعارات لأحداث الموارد User الشكل العام التالي:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: 'https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

مثال على حدث حذف مستخدم ما:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

الرد على الإشعارات

للإشارة إلى النجاح، يمكنك عرض أيّ من رموز الحالة التالية: 200 أو 201 أو 202 أو 204 أو 102.

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

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

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

https://www.googleapis.com/admin/directory_v1/channels/stop

تتطلّب هذه الطريقة تقديم المعلومات التالية على الأقل: id وresourceId، كما هو موضّح في القسم المثال أدناه. لاحظ أنه إذا كانت واجهة برمجة التطبيقات للدليل تحتوي على عدة أنواع من الموارد التي تتضمن watch طريقة، فهناك سبب واحد طريقة stop.

يمكن فقط للمستخدمين الذين يملكون الإذن المناسب إيقاف قناة معيّنة. وعلى وجه الخصوص:

  • إذا تم إنشاء القناة من خلال حساب مستخدم عادي، يتم استخدام المستخدم من العميل نفسه (كما هو موضح في معرِّفات عملاء OAuth 2.0 من رموز المصادقة) الذي أنشأ القناة يمكنه إيقاف القناة.
  • إذا تم إنشاء القناة باستخدام حساب خدمة، يمكن لأي مستخدم من العميل نفسه إيقاف القناة.

يوضّح نموذج الرمز البرمجي التالي كيفية إيقاف تلقّي الإشعارات:

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

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