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

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

نظرة عامة

توفّر 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 مرتبطة في عنوان URL بالشكل التالي:

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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام مرجع 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

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

مع كل طلب 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 عن إرسال الرسائل لقناة الإشعارات هذه.

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

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

مشاهدة الرد

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

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

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

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

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

بعد إنشاء قناة إشعارات لمشاهدة مورد، تُرسِل sync 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

تحتوي رسائل المزامنة دائمًا على قيمة 1 لرأس HTTP X-Goog-Message-Number. يحمل كل إشعار لاحق لهذه القناة رقم رسالة أكبر من الرقم السابق، ولكن لن تكون أرقام الرسائل متسلسلة.

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

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

لا تتوفّر حاليًا طريقة تلقائية لتجديد قناة إشعارات. عندما يقترب موعد انتهاء صلاحية قناة، يجب استبدالها بقناة جديدة من خلال memanggil metode 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 وchanges فارغة.

أمثلة

رسالة إشعار التغيير لموارد files التي لا تتضمّن نص الطلب:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
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: 10

رسالة إشعار التغيير لموارد changes، والتي تتضمّن نص الطلب:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
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

{
  "kind": "drive#changes"
}

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

للإشارة إلى النجاح، يمكنك عرض أيّ من رموز الحالة التالية: 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 على عنوان URL التالي:

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"
}