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

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

يجب توفير الحقول التالية مع كل طلب من طلبات "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" إشعارًا بنجاح فستعرض رمز حالة 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 للقناة الجديدة. لاحظ أنه من المحتمل ليكون "تداخلاً" فترة زمنية تصل فيها قناتا الإشعارات المصدر نفسه نشط.

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

تتضمن جميع رسائل الإشعارات مجموعة من عناوين 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 على نوعَين من الرسائل: مزامنة الرسائل والإشعارات المتعلّقة بالأحداث. تتم الإشارة إلى نوع الرسالة في عنوان HTTP X-Goog-Resource-State. القيم المحتملة لإشعارات الأحداث هي نفسها القيم المتاحة لطريقة activities.list. لكل تطبيق أحداث فريدة:

• المشرف
• تقويم Google
• drive
• مجموعات
• login
• جهاز جوّال
• SAML
• الرمز المميّز
• user_accounts