يشرح هذا المستند طريقة استخدام الإشعارات الفورية التي تُعلِم تطبيقك عند حدوث تغيير في الموارد.
نظرة عامة
توفّر واجهة برمجة تطبيقات Google Drive إشعارات فورية تتيح لك مراقبة التغييرات في الموارد. يمكنك استخدام هذه الميزة لتحسين أداء تطبيقك. تتيح لك هذه الميزة التخلص من الشبكة الإضافية وحساب التكاليف المرتبطة باستطلاع الموارد لتحديد ما إذا كانت قد تغيرت أم لا. عندما يتغير مورد تمت مشاهدته، ترسل واجهة 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 حرفًا.ويتم عرض قيمة رقم التعريف التي حدّدتها في عنوان HTTP يتضمّن العنصر
X-Goog-Channel-Id
لكل رسالة إشعار تتلقّاها لهذه القناة. -
يتم ضبط سلسلة السمة
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
تحتوي رسائل المزامنة دائمًا على قيمة عنوان HTTP X-Goog-Message-Number
وهي 1
. يتضمّن كل إشعار لاحق لهذه القناة
رقم رسالة أكبر من الرقم السابق، إلا أنّ أرقام الرسائل
لن تكون تسلسلية.
تجديد قنوات الإشعارات
يمكن أن يكون لقناة الإشعارات وقت انتهاء صلاحية بقيمة
يتم تحديدها إما من خلال طلبك أو بواسطة أي حدود داخلية لواجهة Google Drive API
أو إعدادات تلقائية (يتم استخدام القيمة الأكثر تقييدًا). يتم تضمين وقت انتهاء صلاحية القناة، في حال توفّره، كطابع زمني لـ Unix (بالمللي ثانية) في المعلومات التي تعرضها الطريقة watch
. بالإضافة إلى ذلك، يتم تضمين تاريخ ووقت انتهاء الصلاحية (بتنسيق يمكن للمستخدمين قراءته) في كل رسالة إشعار يتلقّاها تطبيقك لهذه القناة في عنوان HTTP X-Goog-Channel-Expiration
.
لا تتوفّر حاليًا طريقة تلقائية لتجديد قناة الإشعارات. عند اقتراب تاريخ انتهاء صلاحية قناة معيّنة، يجب استبدالها بأخرى جديدة من خلال استخدام طريقة 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
وتعرض 500
أو 502
أو 503
أو 504
، تعيد واجهة برمجة تطبيقات Google Drive
إعادة المحاولة باستخدام الرقود الأسي الثنائي.
يتم اعتبار كل رموز حالة الإرجاع الأخرى بمثابة إخفاق الرسالة.
فهم أحداث إشعارات 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
على
معرّف الموارد المنتظم التالي:
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" }