Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

يوضّح هذا المستند كيفية إدارة الموافقات في 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 الخطوات العامة لدورة حياة الموافقة:

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

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

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

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

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

لا يمكن استدعاء الطريقة 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 الخاص بتطبيقك.

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

قبل البدء

المفاهيم

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

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

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

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

بدء عملية الموافقة

curl

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

curl

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

curl

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

curl

رفض الموافقة

curl

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

curl

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

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

curl

قائمة الموافقات

curl

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

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