إشعارات بتغييرات الموارد

يصف هذا المستند كيفية استخدام الإشعارات الفورية التي تُعلِم تطبيقك عند تغيير أحد الموارد.

نظرة عامة

توفر واجهة برمجة تطبيقات 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 التالية:

العنوان الوصف
مشاركة العرض دائمًا
X-Goog-Channel-ID المعرّف الفريد العالمي (UUID) أو سلسلة فريدة أخرى قدّمتها لتحديد قناة الإشعارات هذه
X-Goog-Message-Number عدد صحيح يحدِّد هذه الرسالة لقناة الإشعارات هذه. تكون القيمة دائمًا 1 لـ sync رسالة. ترتفع أرقام الرسائل لكل رسالة لاحقة على القناة، إلا أنّها لا تكون تسلسلية.
X-Goog-Resource-ID قيمة مبهمة تحدد المورد الذي تتم مشاهدته. هذا المعرّف ثابت في جميع إصدارات واجهة برمجة التطبيقات.
X-Goog-Resource-State حالة المورد الجديدة التي أدّت إلى ظهور الإشعار. القيم المتاحة: sync أو add أو remove أو update أو trash أو untrash أو change .
X-Goog-Resource-URI معرّف إصدار واجهة برمجة التطبيقات للمصدر الذي تتم مشاهدته.
يقيم أحيانًا
X-Goog-Changed تفاصيل إضافية حول التغييرات القيم المتاحة: content أو parents أو children أو permissions . لا يتم توفير هذه الميزة مع sync رسائل.
X-Goog-Channel-Expiration تاريخ ووقت انتهاء صلاحية قناة الإشعار، معبرَين عنهما بتنسيق يمكن للمستخدمين قراءته لا يوجد إلا إذا تم تحديده.
X-Goog-Channel-Token الرمز المميز لقناة الإشعار الذي حدّده تطبيقك، والذي يمكنك استخدامه للتحقق من مصدر الإشعارات. ولا تتوفر إلا إذا تم تحديدها.

رسائل الإشعارات لـ 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.

X-Goog-Resource-State ينطبق على وقت التسليم
sync files، changes تم إنشاء قناة بنجاح. يُفترض أن تبدأ بتلقّي إشعارات بشأنه.
add files تم إنشاء مورد أو مشاركته.
remove files تم حذف مورد حالي أو إلغاء مشاركته.
update files تم تعديل خاصية واحدة أو أكثر (بيانات وصفية) لمورد.
trash files تم نقل مورد إلى المهملات.
untrash files تمت إزالة مورد من المهملات.
change 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"
}