إشعارات بتغييرات الموارد

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

نظرة عامة

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

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

  • إعداد عنوان URL المستلِم أو جهاز استقبال معاودة الاتصال "خطاف الويب"

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

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

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

تتيح Google Drive API حاليًا إشعارات بشأن التغييرات في الطريقتَين files وchanges.

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

لطلب إشعارات فورية، يجب إعداد قناة إشعارات لكل مورد تريد مراقبته. بعد إعداد قنوات الإشعارات، تُعلم Google Drive API تطبيقك عندما يتم تغيير أي مورد تتم مراقبته.

إجراء طلبات المراقبة

يحتوي كل مورد قابل للمراقبة في Google Drive API على طريقة watch مرتبطة به في عنوان URI بالتنسيق التالي:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

لإعداد قناة إشعارات للرسائل حول التغييرات في مورد معيّن، أرسِل طلب POST إلى طريقة watch للمورد.

ترتبط كل قناة إشعارات بمستخدم معيّن و مورد معيّن (أو مجموعة موارد). لن ينجح طلب watch إلا إذا كان المستخدم الحالي أو حساب الخدمة يملك هذا المورد أو لديه إذن بالوصول إليه.

أمثلة

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام مورد channels لبدء مراقبة التغييرات في مورد files واحد باستخدام طريقة files.watch:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

في نص الطلب، أدخِل id القناة وtype على أن تكون قيمته web_hook وعنوان URL المستلِم في address. يمكنك أيضًا اختيار تقديم ما يلي:

  • token لاستخدامه كرمز مميّز للقناة
  • وقت expiration بالملّي ثانية لوقت انتهاء صلاحية القناة المطلوب

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام مورد channels لبدء مراقبة جميع changes باستخدام طريقة changes.watch:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myChangesChannelDest",
  "expiration": 1426325213000
}

في نص الطلب، أدخِل id القناة وtype على أن تكون قيمته web_hook وعنوان URL المستلِم في address. يمكنك أيضًا اختيار تقديم ما يلي:

  • token لاستخدامه كرمز مميّز للقناة
  • وقت expiration بالملّي ثانية لوقت انتهاء صلاحية القناة المطلوب

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

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

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

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

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

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

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

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

الخصائص الاختيارية

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

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

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

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

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

    • عدم تضمين بيانات حساسة، مثل رموز OAuth المميّزة

  • سلسلة خاصية expiration مضبوطة على طابع زمني لحقبة Unix (بالملّي ثانية) للتاريخ والوقت اللذين تريد أن تتوقف فيهما Google Drive API عن إرسال الرسائل لقناة الإشعارات هذه.

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

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

الردّ على طلب المراقبة

إذا نجح طلب watch في إنشاء قناة إشعارات ، يعرض رمز حالة HTTP 200 OK

يقدّم نص رسالة الردّ على طلب المراقبة معلومات عن قناة الإشعارات التي أنشأتها للتو، كما هو موضّح في المثال أدناه.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1426325213000
}

يقدّم نص الردّ تفاصيل القناة، مثل:

  • kind: يحدّد هذا الخيار أنّه مورد قناة واجهة برمجة تطبيقات.
  • id: المعرّف الذي حدّدته لهذه القناة
  • resourceId: معرّف المورد الذي تتم مراقبته
  • resourceUri: المعرّف الخاص بالإصدار للمورد الذي تتم مراقبته
  • token: الرمز المميّز المقدَّم في نص الطلب
  • expiration: وقت انتهاء صلاحية القناة كطابع زمني لحقبة Unix بالملّي ثانية

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

يمكنك تمرير المعلومات المعروضة إلى عمليات أخرى لقناة الإشعارات مثل عندما تريد التوقف عن تلقّي الإشعارات.

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

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

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

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

في ما يلي تنسيق رسائل sync التي تُرسلها Google Drive 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. يحتوي كل إشعار لاحق لهذه القناة على رقم رسالة أكبر من الرقم السابق، على الرغم من أنّ أرقام الرسائل لن تكون متسلسلة.

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

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

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

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

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

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

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

العناوين

تتضمّن رسائل الإشعارات التي تنشرها Google Drive API على عنوان URL المستلِم عناوين HTTP التالية:

العنوان الوصف
تظهر دائمًا
X-Goog-Channel-ID معرّف فريد عالمي (UUID) أو سلسلة فريدة أخرى قدّمتها لتحديد قناة الإشعارات هذه
X-Goog-Message-Number عدد صحيح يحدّد هذه الرسالة لقناة الإشعارات هذه تكون القيمة دائمًا 1 لرسائل sync. تزداد أرقام الرسائل لكل رسالة لاحقة على القناة، ولكنّها ليست متسلسلة.
X-Goog-Resource-ID قيمة مبهمة تحدّد المورد الذي تتم مراقبته هذا المعرّف ثابت في جميع إصدارات واجهة برمجة التطبيقات.
X-Goog-Resource-State حالة المورد الجديدة التي أدّت إلى الإشعار القيم المحتمَلة: sync أو add أو remove أو update أو trash أو untrash أو change .
X-Goog-Resource-URI معرّف خاص بإصدار واجهة برمجة التطبيقات للمورد الذي تتم مراقبته
تظهر أحيانًا
X-Goog-Changed تفاصيل إضافية حول التغييرات القيم المحتمَلة: content، parents، children، أو permissions . لا يتم تقديمها مع رسائل sync.
X-Goog-Channel-Expiration تاريخ ووقت انتهاء صلاحية قناة الإشعارات، بتنسيق يسهل قراءته لا تظهر إلا إذا تم تحديدها.
X-Goog-Channel-Token الرمز المميّز لقناة الإشعارات الذي ضبطه تطبيقك، و الذي يمكنك استخدامه للتحقّق من مصدر الإشعار لا تظهر إلا إذا تم تحديدها.

تكون رسائل الإشعارات لكل من موارد files (بما في ذلك أحداث add وremove وupdate وtrash وuntrash) وموارد changes فارغة دائمًا (يكون نص طلب HTTP فارغًا، أي Content-Length: 0).

أمثلة

رسالة إشعار لموارد files عند إضافة مورد (يكون نص الطلب فارغًا):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  add
X-Goog-Message-Number: 10

رسالة إشعار بالتغيير لموارد files عند تعديل مورد (يكون نص الطلب فارغًا):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 3a98f1a2b3c4d5e6f7
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 11

رسالة إشعار بالتغيير لموارد changes (يكون نص الطلب فارغًا):

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

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

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

إذا كانت خدمتك تستخدم مكتبة برامج Google API للعملاء وتعرض 500 أو 502 أو 503 أو 504، تعيد Google Drive API المحاولة مع تراجع أسي. يُعتبر كل رمز حالة معروض آخر بمثابة فشل في الرسالة.

فهم أحداث الإشعارات في Google Drive API

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

X-Goog-Resource-State ينطبق على . يتم تسليمها عندما
sync files وchanges تم إنشاء قناة بنجاح. يمكنك توقُّع بدء تلقّي الإشعارات بشأنها.
add files تم إنشاء مورد أو تمت مشاركته.
remove files تم حذف مورد حالي أو إلغاء مشاركته.
update files تم تعديل خاصية واحدة أو أكثر (بيانات وصفية) لمورد.
trash files تم نقل مورد إلى المهملات.
untrash files تمت إزالة مورد من المهملات.
change changes تمت إضافة عنصر واحد أو أكثر إلى سجلّ التغييرات.

بالنسبة إلى أحداث update، قد يتم تقديم عنوان HTTP X-Goog-Changed. يحتوي سطر العنوان هذا على قائمة قيم مفصولة بفاصلة تصف أنواع التغييرات التي حدثت.

نوع التغيير ما يحدث في الواقع
content تم تعديل محتوى المورد.
properties تم تعديل خاصية واحدة أو أكثر للمورد.
parents تمت إضافة أصل واحد أو أكثر للمورد أو إزالته.
children تمت إضافة عنصر فرعي واحد أو أكثر للمورد أو إزالته.
permissions تم تعديل أذونات المورد.

مثال مع عنوان X-Goog-Changed:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

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

تتحكّم السمة expiration في الوقت الذي تتوقف فيه الإشعارات تلقائيًا. يمكنك اختيار التوقف عن تلقّي الإشعارات لقناة معيّنة قبل انتهاء صلاحيتها من خلال استدعاء طريقة stop في عنوان URI التالي:

https://www.googleapis.com/drive/v3/channels/stop

تتطلّب هذه الطريقة تقديم سمات القناة id وresourceId على الأقل، كما هو موضّح في المثال أدناه. يُرجى العِلم أنّه إذا كانت Google Drive API تحتوي على عدة أنواع من الموارد التي تتضمّن طرق watch، فلا تتوفّر إلا طريقة stop واحدة.

يمكن فقط للمستخدمين الذين لديهم الإذن المناسب إيقاف قناة. وعلى وجه الخصوص:

  • إذا أنشأ القناة حساب مستخدم عادي، يمكن للمستخدم نفسه فقط من العميل نفسه (كما هو محدّد من خلال معرّفات عملاء OAuth 2.0 من رموز التفويض المميّزة) الذي أنشأ القناة إيقافها.
  • إذا أنشأ القناة حساب خدمة، يمكن لأي مستخدم من العميل نفسه إيقافها.

يوضّح نموذج الرمز البرمجي التالي كيفية التوقف عن تلقّي الإشعارات:

POST https://www.googleapis.com/drive/v3/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}