يوضّح هذا المستند كيفية استخدام الإشعارات الفورية التي تُعلم تطبيقك عند حدوث تغيير في أحد الموارد.
نظرة عامة
توفّر 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", // 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 حرفًا.يتم تضمين الرمز المميز في عنوان HTTP
X-Goog-Channel-Token
في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة.إذا كنت تستخدم رموزًا مميّزة لقنوات الإشعارات، ننصحك بما يلي:
استخدِم تنسيق ترميز قابل للتوسيع، مثل مَعلمات طلب البحث في عنوان 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"", // 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
في "الدليل المرجعي لواجهة برمجة التطبيقات".
رسالة المزامنة
بعد إنشاء قناة إشعارات لمراقبة أحد الموارد، يرسل 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 إلى عنوان 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.
لا تتوفّر حاليًا طريقة تلقائية لتجديد قناة إشعارات. عندما توشك صلاحية قناة على الانتهاء، عليك استبدالها بقناة جديدة من خلال استدعاء الطريقة watch
. كما هو الحال دائمًا، يجب استخدام قيمة فريدة للسمة id
الخاصة بالقناة الجديدة. يُرجى العِلم أنّه من المحتمل أن تحدث فترة "تداخل" زمنية يكون فيها كلتا قناتَي الإشعارات للمرجع نفسه نشطتَين.
تلقّي إشعارات
عندما يتغيّر أي مصدر تمت مراقبته، يتلقّى تطبيقك رسالة إشعار تصف التغيير. ترسل واجهة برمجة التطبيقات Google Drive API هذه الرسائل كطلبات HTTPS POST
إلى عنوان URL الذي حدّدته كخاصية address
لقناة الإشعارات هذه.
تفسير تنسيق رسالة الإشعار
تتضمّن جميع رسائل الإشعارات مجموعة من عناوين HTTP التي تتضمّن البادئة X-Goog-
.
يمكن أن تتضمّن بعض أنواع الإشعارات أيضًا نص الرسالة.
العناوين
تتضمّن رسائل الإشعارات التي تنشرها Google Drive API إلى عنوان URL المستلِم عناوين HTTP التالية:
العنوان | الوصف |
---|---|
الظهور دائمًا | |
|
تمثّل هذه السمة المعرّف الفريد العالمي (UUID) أو السلسلة الفريدة الأخرى التي قدّمتها لتحديد قناة الإشعارات هذه. |
|
عدد صحيح يعرّف هذه الرسالة لقناة الإشعارات هذه. تكون القيمة دائمًا 1 لرسائل sync . تزداد أرقام الرسائل مع كل رسالة لاحقة في القناة، ولكنها ليست متسلسلة. |
|
قيمة مبهمة تحدّد المورد الذي تتم مراقبته. ويظلّ هذا المعرّف ثابتًا في جميع إصدارات واجهة برمجة التطبيقات. |
|
حالة المرجع الجديد التي شغّلت الإشعار
القيم المتاحة:
sync أو add أو remove أو update أو
trash أو untrash أو change
.
|
|
معرّف خاص بإصدار واجهة برمجة التطبيقات للمورد الذي تمت مشاهدته |
أحيانًا | |
|
تفاصيل إضافية حول التغييرات
القيم المتاحة:
content أو
parents أو
children أو
permissions
.
لا يتم توفيرها مع رسائل sync . |
|
تاريخ ووقت انتهاء صلاحية قناة الإشعارات، ويتم التعبير عنهما بتنسيق يمكن للمستخدمين قراءته. يظهر هذا الحقل فقط إذا تم تحديده. |
|
رمز مميّز لقناة الإشعارات تم ضبطه بواسطة تطبيقك، ويمكنك استخدامه للتحقّق من مصدر الإشعار. يظهر هذا الحقل فقط إذا تم تحديد قيمته. |
رسائل الإشعارات الخاصة بـ 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.
يتم عرض الإعلان عند | ||
---|---|---|
sync |
"files " و"changes " |
تم إنشاء قناة بنجاح. يمكنك توقُّع بدء تلقّي إشعارات بشأنها. |
add |
files |
تم إنشاء مرجع أو تمت مشاركته. |
|
files |
تم حذف مرجع حالي أو إلغاء مشاركته. |
|
files |
تم تعديل خاصية واحدة أو أكثر (البيانات الوصفية) لمورد. |
|
files |
تم نقل مرجع إلى المهملات. |
|
files |
تمت إزالة مرجع من المهملات. |
|
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" }