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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مشاهدة الرد

إذا أنشأ طلب 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 التي ترسلها 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. بالإضافة إلى ذلك، يتم تضمين تاريخ ووقت انتهاء الصلاحية (بتنسيق يسهل قراءته) في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة في عنوان X-Goog-Channel-Expiration HTTP.

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

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

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

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

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، ستحاول واجهة برمجة التطبيقات Admin SDK API مع التراجع الأسي. ويعدّ كل رمز آخر لحالة الإرجاع بمثابة خطأ في الرسالة.

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

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

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

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