يصف هذا المستند كيفية استخدام الإشعارات الفورية التي تُعلِم تطبيقك عند تغيير أحد الموارد.
نظرة عامة
توفر واجهة برمجة تطبيقات Google Drive إشعارات فورية تتيح لك مراقبة التغييرات في الموارد. ويمكنك استخدام هذه الميزة لتحسين أداء تطبيقك. وهو يتيح لك التخلص من الشبكة الإضافية واحتساب التكاليف المرتبطة باستطلاع رأي الموارد لتحديد ما إذا كانت قد تغيّرت. كلما تغير مورد تمت مشاهدته، ترسل Google Drive API إشعارًا إلى تطبيقك.
لاستخدام الإشعارات الفورية، يجب تنفيذ أمرين:
يمكنك إعداد عنوان URL للاستلام أو متلقي معاودة الاتصال "الرد التلقائي على الويب".
هذا خادم HTTPS يتعامل مع رسائل إشعارات واجهة برمجة التطبيقات التي يتم تشغيلها عند تغيير أحد الموارد.
يمكنك إعداد قناة إشعارات لكل نقطة نهاية مورد تريد مشاهدتها.
تحدد القناة معلومات التوجيه لرسائل الإشعارات. كجزء من عملية إعداد القناة، يجب تحديد عنوان URL المحدّد الذي تريد تلقّي الإشعارات عليه. عندما يتغيّر مورد القناة، ترسل واجهة برمجة التطبيقات Google Drive API رسالة إشعار على شكل طلب
POST
إلى عنوان URL هذا.
في الوقت الحالي، تتيح واجهة برمجة تطبيقات Google Drive إرسال إشعارات بشأن التغييرات التي تطرأ على الطريقتَين 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 حرفًا.يتم صدى قيمة المعرّف التي تحدّدها في عنوان 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 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
. بالإضافة إلى ذلك، يتم
تضمين تاريخ انتهاء الصلاحية والوقت (بتنسيق يمكن للمستخدمين قراءته) في كل
رسالة إشعار يتلقّاها تطبيقك بخصوص هذه القناة في
عنوان 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" }