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