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

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

نظرة عامة

توفر واجهة برمجة التطبيقات 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 التالية:

العنوان الوصف
مشاركة العرض دائمًا
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#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 بشكل عام:
  • وإذا لم يتم تقديم eventName، يعرض التقرير جميع النُسخ الممكنة من eventName.
  • وعندما تطلب السمة eventName، يعرض ردّ واجهة برمجة التطبيقات جميع الأنشطة التي تحتوي على eventName. من المحتمل أن يكون للأنشطة التي تم إرجاعها خصائص 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"
}