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

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

نظرة عامة

توفّر واجهة Google Drive API إشعارات فورية تتيح لك تتبُّع البيانات. التغيرات في الموارد. يمكنك استخدام هذه الميزة لتحسين أداء تطبيقك. فهي تتيح لك التخلص من الشبكة الإضافية واحتساب والتكاليف المرتبطة باستطلاع الموارد لتحديد ما إذا كانت قد تغيرت أم لا. عندما يتغيّر مورد تمت مشاهدته، ترسل Google Drive API إشعارًا إلى التطبيق.

لاستخدام الإشعارات الفورية، عليك اتّخاذ إجراءين:

  • إعداد عنوان 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 التالية:

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

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