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

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

نظرة عامة

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

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

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

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

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

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

ملاحظة: تشير كلمة "قناة" كما في هذا المستند إلى قناة الإشعارات بالتحديد وليس إلى أي أنواع أخرى من القنوات المستخدَمة في واجهة برمجة التطبيقات أو الخدمة هذه.

في الوقت الحالي، تتيح واجهة برمجة التطبيقات Admin SDK API تلقّي إشعارات بشأن التغييرات التي تطرأ على مورد الأنشطة.

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

لطلب الإشعارات الفورية، عليك إعداد قناة إشعارات لكل مورد تريد مراقبته. بعد إعداد قنوات الإشعارات، ستُعلِم واجهة برمجة التطبيقات Admin SDK API تطبيقك عند حدوث أي تغيير في الموارد التي تتم مشاهدتها.

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

يتضمّن كل مورد لواجهة برمجة تطبيقات SDK للمشرف القابل للمشاهدة طريقة 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/[e-mail]/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 (بتنسيق يمكن للمستخدمين قراءته) في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة.

ملاحظة: بالنسبة إلى واجهة برمجة التطبيقات Admin SDK API، يبلغ الحد الأقصى لوقت انتهاء الصلاحية 21, 600 ثانية. في حال عدم ضبط السمة expiration في طلبك، سيتم ضبط وقت انتهاء الصلاحية تلقائيًا على 21, 600 ثانية بعد الوقت الحالي.

للاطّلاع على مزيد من التفاصيل حول الطلب، يُرجى الرجوع إلى طريقة 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 لتحديد المورد الذي تتم مشاهدته على قناة الإشعارات هذه.

ملاحظة: السمة resourceId هي معرِّف ثابت ومستقل عن الإصدار للمورد. السمة resourceUri هي معرّف الموارد المنتظم (URI) الأساسي للمصدر الذي تمت مشاهدته في سياق إصدار واجهة برمجة التطبيقات الحالي، وبالتالي إنّه خاص بالإصدار.

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: تحدّد طلبات HTTPS لتسليم الإشعارات وكيل مستخدم APIs-Google وتلتزم بتوجيهات robots.txt، على النحو الموضّح في وكيل مستخدم Google الخاص بواجهات برمجة التطبيقات.

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

تتضمّن جميع رسائل الإشعارات مجموعة من عناوين 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	اسم التطبيق الذي ينتمي إليه الحدث. وتشمل القيم المحتمَلة ما يلي: admin تقويم قيادة المجموعات groups_enterprise login جهاز جوّال saml الرمز المميّز user_accounts
id.customerId	المعرّف الفريد لحساب Google Workspace
actor	المستخدم الذي ينفّذ الإجراء.
actor.callerType	نوع المؤلف الذي أجرى النشاط المدرَج في التقرير في هذا الإصدار من واجهة برمجة التطبيقات، يشير callerType إلى طلب الكيان USER أو OAuth 2LO الذي نفّذ الإجراء الوارد في التقرير .
actor.email	عنوان البريد الإلكتروني الرئيسي للمستخدم الذي يتم الإبلاغ عن أنشطته.
actor.profileId	المعرّف الفريد للملف الشخصي في Google Workspace للمستخدم
ownerDomain	نطاق وحدة تحكّم المشرف أو مالك مستند تطبيق "مستندات Google". هذا هو النطاق الذي سيتأثر بحدث التقرير.
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": "[e-mail]",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "[e-mail]"
        }
      ]
    }
  ]
}

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

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

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

فهم أحداث إشعارات واجهة برمجة التطبيقات Admin SDK API

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

تحتوي الإشعارات الفورية في Reports API على نوعين من الرسائل: مزامنة الرسائل وإشعارات الأحداث. وتتم الإشارة إلى نوع الرسالة في عنوان HTTP يتضمّن العنصر X-Goog-Resource-State. القيم المحتملة لإشعارات الأحداث هي نفسها قيم طريقة activities.list. لكل تطبيق أحداث فريدة:

• admin
• تقويم
• قيادة
• المجموعات
• login
• جهاز جوّال
• saml
• الرمز المميّز
• user_accounts

ملاحظة: يمكن إضافة أحداث حالة موارد إضافية بمرور الوقت. ويجب أن تتجاهل معالِجات رسالة الإشعارات أي قيم غير متوقعة على نحو ملائم.

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

تتحكّم السمة 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"
}

اعتبارات خاصة

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

الإشعارات ليست موثوقة بنسبة 100%. توقَّع أن يتم تجاهل نسبة صغيرة من الرسائل في ظل ظروف العمل العادية. احرص على التعامل مع هذه الرسائل المفقودة بشكل ملائم، بحيث يستمر التطبيق في المزامنة حتى إذا لم يتم استلام أي رسائل فورية.

قد لا يتم تسليم الإشعارات حسب الترتيب الذي تقع به الأحداث.