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

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

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

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

قبل البدء

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

    تكون إمكانية canStartApproval المنطقية false في الحالات التالية:

    • تفرض إعدادات المشرف قيودًا على الوصول إلى الميزة.
    • يكون إصدار Google Workspace غير مؤهّل.
    • يملك الملف مستخدم خارج نطاقك.
    • لا يملك المستخدم الإذن role=writer على الملف.

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

المفاهيم

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

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

عند طلب الموافقة على مستند، تتأكّد عملية الموافقة من أنّ كل مراجع يمكنه تقديم ملاحظات حول المستند.

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

يتم تحديد سلوك الموافقة عند تغيير محتوى الملف أثناء ضبط الموافقة Status على IN_PROGRESS من خلال حقل fileContentChangeBehavior في مورد approvals. يمكن تطبيق السلوكيات التالية:

  • RESET_APPROVAL: تتأكّد عملية الموافقة من أنّ كل مراجع يوافق على الإصدار نفسه من المحتوى. إذا تم تعديل الملف بعد أن يوافق أحد المراجعين على الطلب وقبل اكتمال الطلب، تتم إعادة ضبط الموافقات التي قدّمها المراجع (تتم إعادة ضبط الردّ على NO_RESPONSE)، ويجب أن يوافق المراجعون على الإصدار الجديد. عندما تكون حالة الموافقة APPROVED، يتم قفل الملف لمنع إجراء المزيد من التعديلات. ستؤدي التعديلات الإضافية على المحتوى بعد الموافقة النهائية إلى ظهور بانر على المستند يشير إلى أنّ الإصدار الحالي يختلف عن الإصدار الذي تمت الموافقة عليه. هذا هو السلوك التلقائي.

  • NO_APPROVAL_ACTION: لا تؤدي التعديلات على محتوى الملف إلى إعادة ضبط قرارات المراجع أثناء انتظار الموافقة. بالإضافة إلى ذلك، لا يتم قفل الملف عند الموافقة النهائية. يمكن للمراجعين أيضًا إعادة ضبط قرارهم APPROVED إلى الحالة "في انتظار المراجعة" (تتم إعادة ضبط الردّ على NO_RESPONSE) في أي وقت قبل اكتمال الموافقة.

بعد اكتمال الموافقة، لا يعود هذا السلوك ساريًا.

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

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

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

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

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

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

  1. بدء الموافقة : استدعِ start لبدء طلب الموافقة. بعد ذلك، يتم ضبط status على IN_PROGRESS.

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

  3. الموافقة في الحالة المكتملة : تنتقل الموافقة إلى الحالة المكتملة (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: رسالة مخصّصة يتم إرسالها إلى المراجعين.
  • fileContentChangeBehavior: سلوك الموافقة عند تغيير محتوى الملف. القيمتان المسموح بهما هما:
    • RESET_APPROVAL: (تلقائي) تتم إعادة ضبط أي ردّ من المراجعين على APPROVED إلى NO_RESPONSE عند تغيير المحتوى أثناء تقدّم الموافقة. يتم قفل الملف بعد اكتمال الموافقة بحالة APPROVED.
    • NO_APPROVAL_ACTION: لا تتم إعادة ضبط ردود المراجعين عند تغيير المحتوى، ولا يتم قفل الملف عند اكتمال الموافقة.

يحتوي نص الردّ على مثال لمورد 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.",
    "fileContentChangeBehavior": "RESET_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 مَعلمات المسار.

لا يمكن استدعاء طريقة 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 المَعلمات. إذا كنت لا تعرف رقم تعريف الموافقة، يمكنك إدراج الموافقات باستخدام طريقة 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 لتطبيقك