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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

لا تتوفّر حاليًا طريقة تلقائية لتجديد قناة إشعارات. فعندما أوشكت القناة على الانتهاء، فيجب استبدالها بأخرى جديدة من خلال الاتصال طريقة 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": "[email protected]",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "[email protected]"
        }
      ]
    }
  ]
}

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

للإشارة إلى النجاح، يمكنك عرض أيّ من رموز الحالة التالية: 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
• تقويم
• drive
• المجموعات
• login
• جهاز جوّال
• SAML
• الرمز المميّز
• user_accounts