يصف هذا المستند كيفية استخدام الإشعارات الفورية التي تُعلِم تطبيقك عند تغيير أحد الموارد.
نظرة عامة
توفر واجهة برمجة التطبيقات Admin SDK API إشعارات فورية تتيح لك مراقبة التغييرات في الموارد. ويمكنك استخدام هذه الميزة لتحسين أداء تطبيقك. وهو يتيح لك التخلص من الشبكة الإضافية واحتساب التكاليف المرتبطة باستطلاع رأي الموارد لتحديد ما إذا كانت قد تغيّرت. كلما تغير مورد تمت مشاهدته، ترسل Admin SDK API إشعارًا إلى تطبيقك.
لاستخدام الإشعارات الفورية، يجب تنفيذ أمرين:
يمكنك إعداد عنوان URL للاستلام أو متلقي معاودة الاتصال "الرد التلقائي على الويب".
هذا خادم HTTPS يتعامل مع رسائل إشعارات واجهة برمجة التطبيقات التي يتم تشغيلها عند تغيير أحد الموارد.
يمكنك إعداد قناة إشعارات لكل نقطة نهاية مورد تريد مشاهدتها.
تحدد القناة معلومات التوجيه لرسائل الإشعارات. كجزء من عملية إعداد القناة، يجب تحديد عنوان URL المحدّد الذي تريد تلقّي الإشعارات عليه. عندما يتغيّر مورد القناة، ترسل Admin SDK API رسالة إشعار على شكل طلب
POST
إلى عنوان URL هذا.
في الوقت الحالي، تتيح واجهة برمجة التطبيقات Admin SDK API إرسال الإشعارات بشأن التغييرات التي تطرأ على مورد الأنشطة.
إنشاء قنوات إشعارات
لطلب الإشعارات الفورية، عليك إعداد قناة إشعارات لكل مورد تريد مراقبته. بعد إعداد قنوات الإشعارات، ستُعلِم واجهة برمجة التطبيقات Admin SDK API تطبيقك عند إجراء أي تغييرات على أي مورد تمت مشاهدته.
تقديم طلبات المشاهدة
يحتوي كل مورد في Admin SDK API قابل للمشاهدة على طريقة watch
مرتبطة به على معرّف موارد منتظم (URI) بالنموذج التالي:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
لإعداد قناة إشعارات لتلقّي الرسائل عن التغييرات التي تطرأ على مورد معيّن، أرسِل طلب POST
إلى طريقة
watch
الخاصة بالمورد.
وترتبط كل قناة إشعارات بمستخدم محدد
ومورد معيّن (أو مجموعة من الموارد). لن يتم تنفيذ طلب watch
ما لم يكن المستخدم الحالي
أو حساب الخدمة
يملك هذا المورد أو لديه إذن بالوصول إليه.
أمثلة
تحتوي جميع طلبات المشاهدة لمورد الأنشطة على النموذج العام:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/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-myFilesChannelDest", // (Optional) Your channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
يمكنك استخدام المَعلمات userKey وapplicationName وeventName
وfilters
لتلقّي إشعارات فقط بشأن أحداث أو مستخدمين أو تطبيقات معيّنة.
ملاحظة: تحذف الأمثلة التالية نص الطلب لمزيد من الوضوح.
مشاهدة جميع أنشطة المشرفين:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
مشاهدة جميع أنشطة المستندات:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
مراقبة نشاط المشرف لمستخدم معيّن:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
الانتباه إلى حدث معيّن، مثل تغيير كلمة مرور المستخدم:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
انتبه للتغييرات التي تطرأ على مستند معين:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
السمات المطلوبة
مع كل طلب watch
، يجب تقديم الحقول التالية:
-
سلسلة السمة
id
التي تحدّد قناة الإشعارات الجديدة هذه بشكلٍ فريد ضمن مشروعك ونقترح استخدام معرّف فريد عالمي (UUID) أو أي سلسلة فريدة مشابهة. الحدّ الأقصى للطول: 64 حرفًا.يتم صدى قيمة المعرّف التي تحدّدها في عنوان HTTP الذي يتضمّن العنصر
X-Goog-Channel-Id
لكل رسالة إشعار تتلقّاها لهذه القناة. -
سلسلة السمة
type
التي تم ضبطها على القيمةweb_hook
. -
تمثّل هذه السمة سلسلة السمة
address
التي يتم ضبطها على عنوان URL الذي يتلقى الإشعارات من قناة الإشعارات هذه ويستجيب لها. هذا هو عنوان URL لرد الاتصال التلقائي على الويب، ويجب أن يستخدم HTTPS.وتجدُر الإشارة إلى أنّ Admin SDK API لا يمكنها إرسال إشعارات إلى عنوان HTTPS هذا إلا إذا تم تثبيت شهادة طبقة مقابس آمنة (SSL) صالحة على خادم الويب. تشتمل الشهادات غير الصالحة على:
- الشهادات الموقعة ذاتيًا.
- الشهادات الموقَّعة من مصدر غير موثوق به.
- الشهادات التي تم إبطالها.
- الشهادات التي لا يتطابق موضوعها مع اسم المضيف المستهدف.
السمات الاختيارية
يمكنك أيضًا تحديد هذه الحقول الاختيارية مع طلب
watch
:
-
السمة
token
التي تحدّد قيمة سلسلة عشوائية لاستخدامها كرمز مميّز للقناة. يمكنك استخدام الرموز المميّزة لقناة الإشعارات لأغراض مختلفة. على سبيل المثال، يمكنك استخدام الرمز المميّز للتحقّق من أنّ كل رسالة واردة خاصة بقناة أنشأها تطبيقك، لضمان عدم انتحال الإشعار، أو لتوجيه الرسالة إلى الوجهة الصحيحة داخل تطبيقك بناءً على الغرض من هذه القناة. الحدّ الأقصى للطول: 256 حرفًا.ويتم تضمين الرمز المميّز في عنوان HTTP الذي يتضمّن السمة
X-Goog-Channel-Token
في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة.إذا كنت تستخدم الرموز المميّزة لقناة الإشعارات، ننصحك بما يلي:
استخدِم تنسيق ترميز قابل للامتداد، مثل مَعلمات طلب البحث لعنوان URL. مثلاً:
forwardTo=hr&createdBy=mobile
لا تُدرِج بيانات حسّاسة، مثل رموز OAuth المميزة.
-
تم ضبط سلسلة السمة
expiration
على الطابع الزمني لـ Unix (بالمللي ثانية) للتاريخ والوقت اللذين تريد فيهما أن تتوقّف واجهة Admin SDK API عن إرسال الرسائل إلى قناة الإشعارات هذه.إذا انتهت صلاحية القناة، يتم تضمينها كقيمة عنوان HTTP الذي يتضمّن العنصر
X-Goog-Channel-Expiration
(بتنسيق يمكن للمستخدمين قراءته) في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة.
لمزيد من التفاصيل حول الطلب، يُرجى الرجوع إلى طريقة watch
لمورد الأنشطة في مرجع واجهة برمجة التطبيقات.
مشاهدة الردّ
إذا أنشأ طلب watch
قناة إشعارات بنجاح، يعرض رمز حالة HTTP 200 OK
.
يقدّم نص رسالة استجابة الساعة معلومات حول قناة الإشعارات التي أنشأتها للتو، كما هو موضّح في المثال أدناه.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
بالإضافة إلى السمات التي أرسلتها كجزء من طلبك، تشمل المعلومات التي تم إرجاعها أيضًا resourceId
وresourceUri
لتحديد المورد الذي تتم مشاهدته على قناة الإشعارات هذه.
يمكنك تمرير المعلومات المعروضة إلى عمليات قناة الإشعارات الأخرى، مثلاً عندما تريد إيقاف تلقّي الإشعارات.
لمزيد من التفاصيل حول الرد، يمكنك الاطّلاع على طريقة watch
لمورد الأنشطة في مرجع واجهة برمجة التطبيقات.
مزامنة الرسالة
بعد إنشاء قناة إشعارات لمشاهدة مورد، ترسل Admin SDK API رسالة sync
للإشارة إلى بدء إرسال الإشعارات. وتكون قيمة عنوان HTTP X-Goog-Resource-State
لهذه الرسائل هي sync
. بسبب مشاكل في توقيت الشبكة، من الممكن تلقّي رسالة sync
حتى قبل تلقّي الردّ بطريقة watch
.
يمكنك تجاهل إشعار sync
، ولكن يمكنك
أيضًا استخدامه. على سبيل المثال، إذا قرّرت عدم الاحتفاظ
بالقناة، يمكنك استخدام القيمتَين X-Goog-Channel-ID
وX-Goog-Resource-ID
في مكالمة
لإيقاف تلقّي الإشعارات. ويمكنك أيضًا استخدام إشعار sync
لإجراء بعض الإعدادات للاستعداد للفعاليات اللاحقة.
يظهر أدناه تنسيق رسائل sync
التي ترسلها واجهة برمجة تطبيقات SDK للمشرف إلى عنوان 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
. يتضمّن كل إشعار لاحق لهذه القناة
رقم رسالة أكبر من الرقم السابق، إلا أنّ أرقام
الرسائل لن تكون تسلسلية.
تجديد قنوات الإشعارات
يمكن أن يكون لقناة الإشعارات وقت انتهاء صلاحية، مع قيمة
يتم تحديدها إما من خلال طلبك أو بواسطة أي حدود داخلية لواجهة برمجة تطبيقات Admin SDK API
أو إعدادات تلقائية (يتم استخدام القيمة الأكثر تقييدًا). ويتم تضمين وقت انتهاء صلاحية القناة، في حال توفّره، كطابع زمني Unix (بالمللي ثانية) في المعلومات التي تعرضها الطريقة watch
. بالإضافة إلى ذلك، يتم
تضمين تاريخ انتهاء الصلاحية والوقت (بتنسيق يمكن للمستخدمين قراءته) في كل
رسالة إشعار يتلقّاها تطبيقك بخصوص هذه القناة في
عنوان HTTP الذي يتضمّن العنصر X-Goog-Channel-Expiration
.
لا تتوفّر حاليًا طريقة تلقائية لتجديد قناة الإشعارات. وعند
الاقتراب من انتهاء صلاحية القناة، يجب استبدالها بقناة جديدة من خلال
استخدام طريقة watch
. وكالعادة، يجب استخدام قيمة فريدة
للسمة id
للقناة الجديدة. تجدر الإشارة إلى أنّه من المحتمل أن تكون هناك فترة "تداخل" تكون فيها قناتا الإشعارات التابعتان للمورد نفسه نشطتين.
استلام الإشعارات
وكلما تغيّر مورد مُراقب، يتلقّى تطبيقك رسالة إشعار تصف التغيير. ترسل واجهة Admin SDK API هذه
الرسائل كطلبات HTTPS POST
إلى عنوان URL الذي حدّدته
كسمة address
لقناة
الإشعارات هذه.
تفسير تنسيق رسالة الإشعار
تشمل جميع رسائل الإشعارات مجموعة من عناوين HTTP التي تتضمّن
بادئات X-Goog-
.
وقد تتضمن بعض أنواع الإشعارات أيضًا
نص الرسالة.
العناوين
تتضمّن رسائل الإشعارات التي تم نشرها من خلال Admin SDK API إلى عنوان URL المستلِم عناوين HTTP التالية:
العنوان | الوصف |
---|---|
مشاركة العرض دائمًا | |
|
المعرّف الفريد العالمي (UUID) أو سلسلة فريدة أخرى قدّمتها لتحديد قناة الإشعارات هذه |
|
عدد صحيح يحدِّد هذه الرسالة لقناة الإشعارات هذه. تكون القيمة دائمًا 1 لـ sync رسالة. ترتفع
أرقام الرسائل لكل رسالة لاحقة على القناة، إلا أنّها
لا تكون تسلسلية. |
|
قيمة مبهمة تحدد المورد الذي تتم مشاهدته. هذا المعرّف ثابت في جميع إصدارات واجهة برمجة التطبيقات. |
|
حالة المورد الجديدة التي أدّت إلى ظهور الإشعار.
القيم المحتملة:
sync أو اسم الحدث.
|
|
معرّف إصدار واجهة برمجة التطبيقات للمصدر الذي تتم مشاهدته. |
يقيم أحيانًا | |
|
تاريخ ووقت انتهاء صلاحية قناة الإشعار، معبرَين عنهما بتنسيق يمكن للمستخدمين قراءته لا يوجد إلا إذا تم تحديده. |
|
الرمز المميز لقناة الإشعار الذي حدّده تطبيقك، والذي يمكنك استخدامه للتحقق من مصدر الإشعارات. ولا تتوفر إلا إذا تم تحديدها. |
تحتوي رسائل الإشعارات الخاصة بالأنشطة على المعلومات التالية في نص الطلب:
الموقع | الوصف |
---|---|
kind |
تحدد هذا النشاط كمورد نشاط. القيمة: السلسلة الثابتة "admin#reports#activity ". |
id |
المعرّف الفريد لسجل النشاط. |
id.time |
وقت حدوث النشاط. ويجب أن تكون القيمة بتنسيق ISO 8601 للتاريخ والوقت. ويكون الوقت هو التاريخ الكامل مضافًا إليه الساعات والدقائق والثواني على النحو التالي: YYYY-MM-DDThh:mm:ssTZD. على سبيل المثال، 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
مؤهِّل فريد إذا كانت هناك أحداث متعدّدة في الوقت نفسه. |
id.applicationName |
اسم التطبيق الذي ينتمي إليه الحدث. وتشمل القيم المحتملة ما يلي: |
id.customerId |
المعرّف الفريد لحساب Google Workspace |
actor |
المستخدِم الذي ينفّذ الإجراء. |
actor.callerType |
تمثّل هذه السمة نوع المؤلف الذي أجرى النشاط المدرَج في التقرير. في هذا الإصدار من واجهة برمجة التطبيقات، يشير callerType إلى طلب الكيان USER أو OAuth 2LO الذي نفّذ الإجراء المذكور في التقرير . |
actor.email |
عنوان البريد الإلكتروني الرئيسي للمستخدم الذي يتم الإبلاغ عن أنشطته. |
actor.profileId |
رقم تعريف الملف الشخصي الفريد للمستخدم في Google Workspace |
ownerDomain |
نطاق وحدة تحكم المشرف أو مالك مستند تطبيق المستندات. هذا هو النطاق الذي يتأثر بحدث التقرير. |
ipAddress |
عنوان IP للمستخدم الذي يجري الإجراء. هذا هو عنوان بروتوكول الإنترنت (IP) للمستخدم عند تسجيل الدخول إلى Google Workspace، وقد يعكس ذلك الموقع الجغرافي للمستخدم أو لا. على سبيل المثال، قد يكون عنوان IP هو عنوان الخادم الوكيل للمستخدم أو عنوان شبكة افتراضية خاصة (VPN). تتوافق واجهة برمجة التطبيقات مع IPv4 وIPv6. |
events[] |
أحداث الأنشطة في التقرير |
events[].type |
نوع الحدث هي خدمة أو ميزة Google Workspace التي يغيّرها المشرف في السمة type التي تحدِّد حدثًا باستخدام السمة eventName . |
events[].name |
اسم الحدث هذا هو الاسم المحدّد للنشاط الذي تم الإبلاغ عنه من خلال واجهة برمجة التطبيقات. ويرتبط كل eventName بخدمة أو ميزة معيّنة في Google Workspace تنظّم واجهة برمجة التطبيقات هذه الخدمات ضمن أنواع من الأحداث.
بالنسبة إلى معلَمات طلب eventName بشكل عام:
|
events[].parameters[] |
أزواج قيم المعلَمات لتطبيقات مختلفة. |
events[].parameters[].name |
اسم المَعلمة. |
events[].parameters[].value |
قيمة السلسلة للمَعلمة |
events[].parameters[].intValue |
قيمة عددية للمَعلمة |
events[].parameters[].boolValue |
القيمة المنطقية للمعلَمة |
أمثلة
تكون رسائل الإشعارات الخاصة بأحداث مورد النشاط على النحو العام:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId 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/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
مثال على حدث نشاط المشرف:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.com" } ] } ] }
الرد على الإشعارات
للإشارة إلى نجاح العملية، يمكنك عرض أي من رموز الحالة التالية:
200
أو 201
أو 202
أو 204
أو 102
.
إذا كانت خدمتك تستخدم مكتبة برامج واجهة برمجة التطبيقات من Google
وتعرض 500
أو 502
أو 503
أو 504
، تعيد واجهة برمجة تطبيقات SDK للمشرف إعادة محاولة الوصول باستخدام الرقود الأسي.
يتم اعتبار كل رمز آخر لحالة الإرجاع على أنه خطأ في الرسالة.
فهم أحداث إشعارات واجهة برمجة تطبيقات SDK للمشرف
يقدّم هذا القسم تفاصيل حول رسائل الإشعارات التي يمكنك تلقّيها عند استخدام الإشعارات الفورية من خلال Admin SDK API.
تحتوي الإشعارات الفورية في Reporting API على نوعين من الرسائل: مزامنة الرسائل وإشعارات الأحداث. تتم الإشارة إلى نوع الرسالة في عنوان HTTP يتضمّن العنصر X-Goog-Resource-State
. القيم المحتملة لإشعارات الأحداث هي نفسها قيم طريقة activities.list
. لكل تطبيق أحداث فريدة:
إيقاف الإشعارات
تتحكّم السمة expiration
في وقت توقّف الإشعارات تلقائيًا. يمكنك
اختيار إيقاف تلقّي الإشعارات من قناة معيّنة قبل
انتهاء صلاحيتها، وذلك من خلال استدعاء طريقة stop
على
معرّف الموارد المنتظم التالي:
https://www.googleapis.com/admin/reports_v1/channels/stop
تتطلّب هذه الطريقة تقديم السمتَين id
وresourceId
للقناة على الأقل، كما هو موضّح في المثال أدناه. تجدر الإشارة إلى أنّه إذا كانت واجهة برمجة التطبيقات Admin SDK API تحتوي على عدة أنواع من
الموارد التي تتضمّن طرق watch
، تتوفّر طريقة
stop
واحدة فقط.
يمكن فقط للمستخدمين الذين يملكون الإذن المناسب إيقاف قناة. وعلى وجه الخصوص:
- وإذا تم إنشاء القناة من خلال حساب مستخدم عادي، لن يتمكن من إيقاف القناة سوى المستخدم نفسه من العميل نفسه (كما هو موضح من خلال معرّفات عميل OAuth 2.0 من رموز المصادقة المميزة).
- إذا تم إنشاء القناة من خلال حساب خدمة، يمكن لأي مستخدم من العميل نفسه إيقافها.
يوضح الرمز النموذجي التالي كيفية إيقاف تلقّي الإشعارات:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }