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