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

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

نظرة عامة

توفّر واجهة 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 التالية:

العنوان الوصف
مشاركة العرض دائمًا
X-Goog-Channel-ID المعرّف الفريد العالمي أو سلسلة فريدة أخرى قدّمتها لتحديد قناة الإشعار هذه
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 API إعادة المحاولة مع إيقاف أسي. ويعدّ كل رمز آخر لحالة الإرجاع بمثابة خطأ في الرسالة.

فهم أحداث إشعارات 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 على معرّف الموارد المنتظم (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"
}