إدارة الموافقات

يوضّح هذا المستند كيفية إدارة الموافقات في Google Drive API.

يمكن للمستخدمين إرسال المستندات في Google Drive من خلال عملية موافقة رسمية. يمكنك استخدام هذه العملية للحصول على موافقة على مراجعة عقد أو مستند رسمي قبل نشره. تتتبّع الموافقة حالة كلّ من المراجعة (مثل "قيد التقدّم" أو "تمت الموافقة" أو "تم الرفض") والمراجعين المعنيّين. تُعدّ الموافقات طريقة ممتازة للتحقّق من صحة المحتوى والاحتفاظ بسجلّ للمراجعين.

يمكنك إنشاء الموافقات على المحتوى وإدارتها في Drive. توفر Google Drive API مورد approvals للتعامل مع الموافقات على الملفات. تعمل طرق مورد approvals على العناصر في Drive و"مستندات Google" وأدوات التحرير الأخرى في Google Workspace. يمكن للمراجعين الموافقة على المستندات أو رفضها أو ترك ملاحظات عليها مباشرةً.

قبل البدء

يجب أن يحتوي ملفك على الـ canStartApproval إمكانية . للتحقّق من إمكانيات الملف، استخدِم طريقة get في مورد files مع مَعلمة المسار fileId واستخدِم حقل إمكانية canStartApproval في مَعلمة fields. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التعرّف على إمكانيات الملفات.

تكون إمكانية canStartApproval المنطقية false في الحالات التالية:
- تقيّد إعدادات المشرف الوصول إلى الميزة.
- يكون إصدار Google Workspace غير مؤهَّل.
- يكون مالك الملف مستخدمًا خارج نطاقك.
- لا يملك المستخدم الإذن role=writer في الملف.
تأكَّد من مشاركة الملف المستهدَف يدويًا مع المراجعين. لا ينفّذ Drive ذلك تلقائيًا. إذا لم يكن لدى أحد المراجعين إذن الوصول إلى الملف، سينجح طلب الموافقة، ولكن لن يتلقّى المراجع إشعارات ولن يتمكّن من عرض الملف.

المفاهيم

تشكّل المفاهيم الرئيسية التالية أساس الموافقات.

حالة الموافقة

عند طلب الموافقة على مستند، تضمن عملية الموافقة أن يوافق كل مراجع على الإصدار نفسه من المحتوى. إذا تم تعديل الملف بعد أن يوافق أحد المراجعين على الطلب وقبل اكتماله، تتم إعادة ضبط الموافقات التي منحها المراجع ويجب أن يوافق المراجعون على الإصدار الجديد. إذا تم تعديل المحتوى بعد الموافقة النهائية، يظهر بانر على المستند يشير إلى أنّ الإصدار الحالي يختلف عن الإصدار الذي تمت الموافقة عليه.

يتضمّن مورد approvals كائنًا Status يقدّم تفاصيل عن حالة الموافقة عند طلب المورد. ويتضمّن أيضًا الكائن ReviewerResponse الذي يقدّم تفاصيل عن الردود على الموافقة التي منحها مراجعون محدّدون. يتم تمثيل ردّ كل مراجع بـ الكائن Response.

يؤدي كل إجراء في عملية الموافقة إلى إنشاء إشعارات بالبريد الإلكتروني يتم إرسالها إلى المستخدم الذي بدأ العملية (المستخدم الذي طلب الموافقة) وجميع المراجعين. تتم أيضًا إضافة الإجراء إلى سجلّ نشاط الموافقة.

يجب أن يوافق جميع المراجعين على الموافقة. يؤدي رفض أي مراجع للموافقة إلى ضبط الحالة المكتملة على DECLINED.

بعد اكتمال الموافقة (تكون الحالة APPROVED أو CANCELLED أو DECLINED)، تظل في الحالة المكتملة ولا يمكن للمستخدم الذي بدأ العملية أو المراجعين التفاعل معها. يمكنك إضافة تعليقات إلى موافقة مكتملة طالما أنّه لا توجد موافقة حالية على ملف بحالة IN_PROGRESS.

دورة حياة الموافقة

مراحل الموافقة — **الشكل 1.** دورة حياة الموافقة

تمرّ الموافقة بعدة حالات خلال دورة حياتها. يوضّح الشكل 1 الخطوات العالية المستوى لدورة حياة الموافقة:

بدء الموافقة : استخدِم طريقة start لبدء طلب الموافقة. بعد ذلك، يتم ضبط status على IN_PROGRESS.
الموافقة في انتظار المراجعة : بينما تكون الموافقة في انتظار المراجعة (status مضبوط على IN_PROGRESS)، يمكن للمستخدم الذي بدأ العملية والمراجعين التفاعل معها. يمكنهم إضافة comment، ويمكن للمستخدم الذي بدأ العملية أن reassign المراجعين، ويمكن لمراجع واحد أو أكثر أن approve الطلب.
الموافقة في الحالة المكتملة : تنتقل الموافقة إلى الحالة المكتملة (status مضبوط على APPROVED أو CANCELLED أو DECLINED) عندما يوافق جميع المراجعين على الطلب، أو يختار المستخدم الذي بدأ العملية cancel الطلب، أو إذا اختار أي مراجع أن decline الطلب.

استخدام مَعلمة fields

إذا أردت تحديد الحقول التي سيتم عرضها في الاستجابة، يمكنك ضبط الـ fields مَعلمة النظام مع أي طريقة من طرق مورد الـ approvals. إذا لم تضبط مَعلمة fields، يعرض الخادم مجموعة حقول تلقائية خاصة بالطريقة. لعرض حقول مختلفة، يُرجى الاطّلاع على مقالة عرض حقول محدّدة.

بدء الموافقات وإدارتها

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

بدء الموافقة

لبدء موافقة جديدة على ملف، استخدِم طريقة start في مورد approvals وضِّمن مَعلمة المسار fileId.

يتألّف نص الطلب من حقل reviewerEmails مطلوب وهو عبارة عن مصفوفة من السلاسل النصية التي تحتوي على عناوين البريد الإلكتروني للمراجعين الذين تم تعيينهم لمراجعة الملف. يجب ربط كل عنوان بريد إلكتروني للمراجع بحساب Google وإلا سيفشل الطلب. بالإضافة إلى ذلك، يتم توفير ثلاثة حقول اختيارية:

dueTime: الموعد النهائي للموافقة بتنسيق RFC 3339.
lockFile: قيمة منطقية تشير إلى ما إذا كان سيتم قفل الملف عند بدء الموافقة. يمنع هذا الإعداد المستخدمين من تعديل الملف أثناء عملية الموافقة. يمكن لأي مستخدم لديه الإذن role=writer إزالة هذا القفل.
message: رسالة مخصّصة يتم إرسالها إلى المراجعين.

يحتوي نص الاستجابة على مثال لمورد approvals ويتضمّن الحقل الذي يمثّل المستخدم الذي طلب الموافقة.initiator يتم ضبط Status الموافقة على IN_PROGRESS.

إذا كانت هناك موافقة حالية بحالة Status من IN_PROGRESS، ستفشل طريقة start. لا يمكنك بدء الموافقة إلا إذا لم تكن هناك موافقة حالية على الملف أو إذا كانت الموافقة الحالية في الحالة المكتملة (تكون الحالة APPROVED أو CANCELLED أو DECLINED).

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval."
 }'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

التعليق على الموافقة

للتعليق على الموافقة، استخدِم طريقة comment في مورد approvals وضِّمن مَعلمتَي المسار fileId وapprovalId المسار.

يتألّف نص الطلب من حقل message مطلوب وهو عبارة عن سلسلة نصية تحتوي على التعليق الذي تريد إضافته إلى الموافقة.

يحتوي نص الاستجابة على مثال لمورد approvals. يتم إرسال الرسالة إلى المستخدم الذي بدأ عملية الموافقة والمراجعين كإشعار، ويتم تضمينها أيضًا في سجلّ نشاط الموافقة.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
APPROVAL_ID: رقم تعريف الموافقة.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

إعادة تعيين المراجعين في الموافقة

لإعادة تعيين المراجعين في الموافقة، استخدِم الـ reassign طريقة في الـ approvals مورد وضِّمن الـ fileId و approvalId مَعلمات المسار.

تسمح طريقة reassign للمستخدم الذي بدأ عملية الموافقة (أو مستخدم لديه الإذن role=writer بإضافة مراجعين أو استبدالهم في الكائن ReviewerResponse لمورد approvals. لا يمكن للمستخدم الذي لديه الإذن role=reader إعادة تعيين موافقة تم تعيينها له إلا. يسمح ذلك للمستخدم بإعادة تعيين طلب إلى شخص آخر يكون مراجعًا أكثر كفاءة.

لا يمكن إعادة تعيين المراجعين إلا عندما تكون Status هي IN_PROGRESS ويتم ضبط الحقل response للمراجع الذي تتم إعادة تعيينه على NO_RESPONSE.

يُرجى العِلم أنّه لا يمكنك إزالة مراجع في الموافقة. إذا كنت بحاجة إلى إزالة مراجع، عليك إلغاء الموافقة وبدء موافقة جديدة.

يتألّف نص الطلب من الحقلَين الاختياريَين addReviewers وreplaceReviewers. يحتوي كل حقل على كائن متكرّر لـAddReviewer وReplaceReviewer، ويحتوي كل منهما على مراجع واحد لإضافته أو زوج من المراجعين لاستبدالهما. يمكنك أيضًا إضافة الحقل الاختياري message الذي يحتوي على التعليق الذي تريد إرساله إلى المراجعين الجدد.

يحتوي نص الاستجابة على مثال لمورد approvals. يتم إرسال الرسالة إلى المراجعين الجدد كإشعار، ويتم تضمينها أيضًا في سجلّ نشاط الموافقة.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
APPROVAL_ID: رقم تعريف الموافقة.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

إلغاء الموافقة

لإلغاء الموافقة، استخدِم طريقة cancel في مورد approvals وضِّمن مَعلمتَي المسار fileId وapprovalId.

لا يمكن استدعاء طريقة cancel إلا من قِبل المستخدم الذي بدأ عملية الموافقة (أو مستخدم لديه الإذن role=writer) عندما تكون الموافقة Status هي IN_PROGRESS.

يتألّف نص الطلب من حقل اختياري message وهو عبارة عن سلسلة نصية تحتوي على الرسالة التي ستصاحب إلغاء الموافقة.

يحتوي نص الاستجابة على مثال لمورد approvals. يتم إرسال الرسالة كإشعار، ويتم تضمينها أيضًا في سجلّ نشاط الموافقة. يتم ضبط Status الموافقة على CANCELLED وتكون في حالة مكتملة.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
APPROVAL_ID: رقم تعريف الموافقة.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

رفض الموافقة

لرفض الموافقة، استخدِم طريقة decline في مورد approvals وضِّمن مَعلمتَي المسار fileId وapprovalId path parameters.

لا يمكن استدعاء طريقة decline إلا عندما تكون Status الموافقة هي IN_PROGRESS.

يتألّف نص الطلب من حقل message اختياري وهو عبارة عن سلسلة نصية تحتوي على الرسالة التي ستصاحب رفض الموافقة.

يحتوي نص الاستجابة على مثال لمورد approvals. يتم إرسال الرسالة كإشعار، ويتم تضمينها أيضًا في سجلّ نشاط الموافقة. يتم ضبط الحقل response للكائن ReviewerResponse الخاص بالمستخدم الذي يقدّم الطلب على DECLINED. بالإضافة إلى ذلك، يتم ضبط Status الموافقة على DECLINED وتكون في حالة مكتملة.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
APPROVAL_ID: رقم تعريف الموافقة.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

الموافقة على الموافقة

للموافقة على الموافقة، استخدِم الـ approve طريقة في مورد الـapprovals وضِّمن الـfileId والـapprovalId مَعلمات المسار.

لا يمكن استدعاء طريقة approve إلا عندما تكون Status الموافقة هي IN_PROGRESS.

يتألّف نص الطلب من حقل اختياري message وهو عبارة عن سلسلة نصية تحتوي على الرسالة التي ستصاحب الموافقة.

يحتوي نص الاستجابة على مثال لمورد approvals. يتم إرسال الرسالة كإشعار، ويتم تضمينها أيضًا في سجلّ نشاط الموافقة. يتم ضبط الحقل response للكائن ReviewerResponse الخاص بالمستخدم الذي يقدّم الطلب على APPROVED. بالإضافة إلى ذلك، إذا كان هذا هو آخر ردّ مطلوب من المراجع، يتم ضبط Status الموافقة على APPROVED وتكون في حالة مكتملة.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
APPROVAL_ID: رقم تعريف الموافقة.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

تحديد موقع الموافقات الحالية

يمكن أيضًا استخدام مورد approvals للحصول على حالة الموافقات وعرضها باستخدام Drive API.

لعرض الموافقات على ملف، يجب أن يكون لديك إذن قراءة البيانات الوصفية للملف. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الأدوار و الأذونات.

الحصول على الموافقة

للحصول على موافقة على ملف، استخدِم طريقة get في مورد approvals مع مَعلمتَي المسار fileId وapprovalId path parameters. إذا كنت لا تعرف رقم تعريف الموافقة، يمكنك إدراج الموافقات باستخدام طريقة list.

يحتوي نص الاستجابة على مثال لمورد approvals.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
APPROVAL_ID: رقم تعريف الموافقة.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

إدراج الموافقات

لإدراج الموافقات على ملف، استخدِم طريقة list في مورد approvals وضِّمن مَعلمة المسار fileId.

يتألّف نص الاستجابة من قائمة بالموافقات على الملف. يتضمّن الحقل items معلومات عن كل موافقة على شكل مورد approvals.

يمكنك أيضًا تمرير مَعلمتَي طلب البحث التاليتَين لتخصيص ترقيم الموافقات على صفحات أو فلترتها:

pageSize: الحد الأقصى لعدد الموافقات التي سيتم عرضها في كل صفحة. إذا لم تضبط pageSize، يعرض الخادم ما يصل إلى 100 موافقة.
pageToken: رمز مميّز للصفحة تم استلامه من استدعاء سابق لقائمة. يُستخدم هذا الرمز المميز لاسترداد الصفحة اللاحقة. يجب ضبطه على قيمة nextPageToken من استجابة سابقة.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

غيِّر القيم في السلسلة على الشكل التالي:

FILE_ID: رقم تعريف الملف الذي تتم الموافقة عليه.
ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.

إدارة الموافقات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

قبل البدء

المفاهيم

حالة الموافقة

دورة حياة الموافقة

استخدام مَعلمة fields

بدء الموافقات وإدارتها

بدء الموافقة

curl

التعليق على الموافقة

curl

إعادة تعيين المراجعين في الموافقة

curl

إلغاء الموافقة

curl

رفض الموافقة

curl

الموافقة على الموافقة

curl

تحديد موقع الموافقات الحالية

الحصول على الموافقة

curl

إدراج الموافقات

curl

مواضيع ذات صلة

إدارة الموافقات