توضّح هذه الصفحة أحداث Google Drive التي يمكن لتطبيقك الاشتراك فيها باستخدام Google Workspace Events API. بعد تحديد أنواع الأحداث التي تحتاج إليها، يمكنك إنشاء اشتراك لبدء تلقّي الأحداث من Drive.
لمزيد من المعلومات عن تطوير تطبيقات لـ Drive، يُرجى الاطّلاع على نظرة عامة على Google Drive API.
أحداث Drive المتوافقة
تتيح لك اشتراكات Google Workspace تلقّي أحداث حول أنواع التغييرات التالية في Drive:
تم إنشاء اقتراح بشأن إذن الوصول أو تمت الاستجابة إليه في ملف.
يتم إنشاء تعليق أو تعديله أو حلّه أو إعادة فتحه أو حذفه في ملف أو ملف داخل مساحة تخزين سحابي مشتركة.
الملف هو:
- تمت إضافته إلى مجلد أو مساحة تخزين سحابي مشتركة.
- تم نقله إلى مجلد أو مساحة تخزين سحابي مشتركة.
- تم تحميل نسخة معدّلة أو جديدة.
- تم نقلها إلى المهملات أو إزالتها منها.
- تمت إعادة التسمية (تم تغيير عنوان ملف أو مجلد).
يتم إنشاء رد أو تعديله أو حذفه في سلسلة محادثات تعليقات في ملف أو ملف ضمن مساحة تخزين سحابي مشتركة.
الموارد التي يمكنك مراقبة الأحداث فيها
لتلقّي الأحداث، عليك تحديد مورد Drive تريد تتبُّعه، ويُطلق عليه اسم المورد المستهدف للاشتراك.
تتيح واجهة برمجة التطبيقات Google Workspace Events API استخدام موارد الاستهداف التالية في Drive:
| المورد المستهدف | التنسيق | القيود (إذا كان ذلك منطبقًا) |
|---|---|---|
| ملف |
//drive.googleapis.com/files/FILE
حيث FILE هو رقم التعريف في
اسم المورد
لمورد |
يجب أن يكون لدى المستخدم الذي يمنح الإذن بالاشتراك إذن بالوصول إلى الملف ضمن الاشتراك بالنسبة إلى حدث الاشتراك. |
| مساحة تخزين سحابي مشتركة |
//drive.googleapis.com/drives/DRIVE
حيث DRIVE هو رقم التعريف في
اسم المورد
لمورد |
لا يتلقّى الاشتراك سوى أحداث العناصر في مساحة التخزين السحابي المشتركة التي يكون المستخدم عضوًا فيها من خلال حسابه على Google Workspace أو حسابه على Google. |
أنواع الأحداث لإنشاء الاشتراكات
عند إنشاء اشتراك في أحد موارد Drive، يمكنك استخدام الحقل
eventTypes[]
لتحديد أنواع الأحداث التي تريد تلقّيها. يتم تنسيق أنواع الأحداث وفقًا لمواصفات CloudEvents، مثل google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.
على سبيل المثال، لتلقّي أحداث حول إنشاء ملف في مجلد أو مساحة تخزين سحابي مشتركة، عليك تحديد الملف كمورد مستهدف، ونوع الحدث كـ google.workspace.drive.file.v3.created. لتلقّي أحداث حول إنشاء اقتراح بشأن منح إذن الوصول إلى ملف، عليك تحديد اقتراح منح إذن الوصول كمورد مستهدف، ونوع الحدث على أنّه google.workspace.drive.accessproposal.v3.created. لمزيد من المعلومات حول طريقة عمل الأحداث، يمكنك الاطّلاع على بنية أحداث Google Workspace.
يعرض الجدول التالي أنواع الأحداث المتاحة للاشتراك في موارد Drive:
| نوع الحدث | التنسيق | بيانات الموارد | ||
|---|---|---|---|---|
| الاشتراكات في الملفات ومساحات التخزين السحابي المشتركة | ||||
| يتم إنشاء اقتراح وصول على ملف. |
|
|
||
| تمت الاستجابة إلى اقتراح الوصول إلى ملف. |
|
|
||
| يتم إنشاء تعليق على ملف أو ملف داخل مساحة تخزين سحابي مشتركة. |
|
|
||
| تم تعديل تعليق على ملف أو ملف داخل مساحة تخزين سحابي مشتركة. |
|
|
||
| تم حلّ تعليق على ملف أو ملف داخل مساحة تخزين سحابي مشتركة. |
|
|
||
| إعادة فتح تعليق على ملف أو ملف داخل مساحة تخزين سحابي مشتركة |
|
|
||
| تم حذف تعليق على ملف أو ملف داخل مساحة تخزين سحابي مشتركة. |
|
|
||
| تمت إضافة ملف إلى مجلد أو مساحة تخزين سحابي مشتركة. |
|
|
||
| يتم نقل ملف إلى مجلد أو مساحة تخزين سحابي مشتركة. |
|
|
||
| تم تعديل ملف أو تحميل نسخة جديدة. |
|
|
||
| يتم حذف ملف. |
|
|
||
| تم نقل ملف إلى المهملات. |
|
|
||
| تمت إزالة ملف من المهملات. |
|
|
||
| تمت إعادة تسمية ملف. |
|
|
||
| يتم إنشاء ردّ في سلسلة تعليقات في ملف أو ملف ضمن مساحة تخزين سحابي مشتركة. |
|
|
||
| يتم تعديل ردّ في سلسلة تعليقات في ملف أو ملف ضمن مساحة تخزين سحابي مشتركة. |
|
|
||
| تم حذف ردّ في سلسلة تعليقات في ملف أو ملف ضمن مساحة تخزين سحابي مشتركة. |
|
|
||
بيانات الأحداث
يوضّح هذا القسم بيانات الأحداث وأمثلة على حمولات الأحداث في Drive.
عندما يتلقّى اشتراكك في Google Workspace حدثًا من Drive، يحتوي الحقل data على حمولة الحدث. تحتوي حمولة البيانات هذه على معلومات حول مرجع Google Workspace الذي تم تغييره. على سبيل المثال، إذا اشتركت في أحداث الملفات، سيحتوي حمولة هذه الأحداث على معلومات حول المورد files الذي تم تغييره.
بيانات الموارد في حمولة الحدث
عند إنشاء اشتراك، يمكنك تحديد ما إذا كنت تريد أن تتضمّن الحمولة تفاصيل حول المورد أو اسم المورد فقط. على سبيل المثال، إذا كنت تريد تلقّي أحداث حول الملفات في Drive، يمكنك تحديد الحقول التي تريد تلقّيها من مورد files في حمولة الحدث.
يقدّم الجدول التالي أمثلة على حمولات JSON لاشتراك في مصدر Drive. يحتوي معرّف الملف على أحرف وأرقام وبعض الرموز الخاصة منظَّمة على النحو التالي: files/^[01][0-9a-zA-Z_-]+$/. على سبيل المثال:
files/1aaabbbAAABBB111222-_. بالنسبة إلى كل حدث تتلقّاه الاشتراك، يظهر الحمولة في الحقل data الخاص بالحدث:
| مثال | نوع الحدث | حِمل JSON |
|---|---|---|
ينشئ المستخدم اقتراحًا بشأن إذن الوصول إلى ملف. |
|
تتضمّن بيانات الموارد
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "alex@altostrat.com",
"requesterEmailAddress": "kai@cymbalgroup.com",
"requestMessage": "grant me access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
لا يشمل بيانات الموارد
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
يحلّ المستخدم اقتراحًا بشأن الوصول إلى ملف. |
|
تتضمّن بيانات الموارد
{
"accessProposal": [
{
"file_id": "FILE_ID",
"proposalId": "PROPOSAL_ID",
"recipientEmailAddress": "alex@altostrat.com",
"requesterEmailAddress": "kai@cymbalgroup.com",
"requestMessage": "resolve access to this file",
"rolesAndViews": [
{
"role": "writer",
"view": "published"
}
]
}
]
}
لا يشمل بيانات الموارد
{
"accessProposal": [
{
"proposalId": "PROPOSAL_ID"
}
]
}
|
ينشئ مستخدم تعليقًا على ملف. |
|
تتضمّن بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
يعدّل مستخدم تعليقًا في ملف. |
|
تتضمّن بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
يحلّ مستخدم تعليقًا في ملف. |
|
تتضمّن بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
عندما يعيد مستخدم فتح تعليق على ملف |
|
تتضمّن بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
يحذف مستخدم تعليقًا في ملف. |
|
تتضمّن بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"comment": {
"id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
يضيف مستخدم ملفًا إلى مجلد أو مساحة تخزين سحابي مشتركة. |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
ينقل المستخدم ملفًا إلى مجلد أو مساحة تخزين سحابي مشتركة. |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
يعدّل مستخدم ملفًا أو يتم تحميل نسخة جديدة. |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
يحذف المستخدم ملفًا. |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
أضاف مستخدم ملفًا إلى سلة المهملات. |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
يستعيد المستخدم ملفًا من المهملات. |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
عندما يعيد المستخدم تسمية ملف أو مجلد |
|
تتضمّن بيانات الموارد
{
"file": {
"id": "FILE_ID",
"parent": "PARENT_ID",
"version": "63",
"mimeType": "application/vnd.google-apps.document"
}
}
لا يشمل بيانات الموارد
{
"file": {
"id": "FILE_ID"
}
}
|
ينشئ مستخدم ردًا على تعليق في سلسلة محادثات. |
|
تتضمّن بيانات الموارد
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
يعدّل مستخدم ردًا على تعليق في سلسلة محادثات. |
|
تتضمّن بيانات الموارد
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
يحذف مستخدم ردًا على تعليق في سلسلة تعليقات. |
|
تتضمّن بيانات الموارد
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID",
"mentioned_email_addresses": ["alex@altostrat.com", "kai@cymbalgroup.com"],
"assignee_email_address": "yuri@altostrat.com"
}
}
لا يشمل بيانات الموارد
{
"reply": {
"id": "REPLY_ID",
"comment_id": "COMMENT_ID",
"file_id": "FILE_ID"
}
}
|
القيود
- عندما يكون الحقل المنطقي
includeDescendantsفيDriveOptionstrue، ترسل اشتراكات Drive في مساحات التخزين السحابي المشتركة والمجلدات حدثًا دائمًا، حتى إذا كان الملف الذي أدى إلى تشغيل الحدث مضمّنًا في عدة طبقات أسفل المجلد المستخدَم في اشتراك Drive. - على الرغم من أنّك قد تكون قد أنشأت اشتراكًا في مجلد، قد لا تتلقّى جميع الأحداث ضمن التسلسل الهرمي للملفات لأنّه قد لا يتم منح المستخدم أو التطبيق إذن الوصول إليها. في هذه الحالة، يظل الاشتراك نشطًا ولكن لن تتلقّى أي أحداث للموارد التي لا يمكنك الوصول إليها.
- تتوفّر الاشتراكات للأحداث على جميع الملفات والمجلدات، ولكن ليس على المجلد الجذر لمساحات التخزين السحابي المشتركة. لا تتوفّر الاشتراكات إلا للملفات والمجلدات داخل مساحات التخزين السحابي المشتركة. لن تؤدي التغييرات التي يتم إجراؤها مباشرةً على المجلد الجذر في مساحة تخزين سحابي مشتركة إلى تشغيل الأحداث.
- يجب أن يكون لدى المستخدم الذي يمنح الإذن بالاشتراك إذن بالوصول إلى الملف الذي يتضمّن الأحداث التي يريد الاشتراك فيها.
- لا يتلقّى الاشتراك سوى أحداث الموارد التي يمكن للمستخدم الوصول إليها من خلال حسابه على Google Workspace أو حسابه على Google.