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

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

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

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

RESET_APPROVAL: تضمن عملية الموافقة أن يوافق كل مراجع على النسخة نفسها من المحتوى. إذا تم تعديل الملف بعد موافقة المراجع على الطلب وقبل اكتمال الطلب، ستتم إعادة ضبط موافقات المراجع (ستتم إعادة الرد إلى NO_RESPONSE)، وعلى المراجعين الموافقة على النسخة الجديدة. عندما تكون حالة الموافقة APPROVED، يكون الملف مقفلاً لمنع إجراء المزيد من التعديلات. سيؤدي إجراء تعديلات إضافية على المحتوى بعد الموافقة النهائية إلى ظهور بانر على المستند يشير إلى أنّ الإصدار الحالي يختلف عن الإصدار الذي تمت الموافقة عليه. هذا هو السلوك التلقائي.
NO_APPROVAL_ACTION: لا تؤدي التعديلات على محتوى الملف إلى إعادة ضبط قرارات المراجع أثناء انتظار الموافقة. بالإضافة إلى ذلك، لا يتم قفل الملف عند الموافقة النهائية. يمكن للمراجعين أيضًا إعادة ضبط قرارهم بشأن APPROVED إلى الحالة "في انتظار المراجعة" (أي إعادة الردّ إلى NO_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. على عكس الموارد الأخرى، لا تعرض طرق المورد approvals مجموعة تلقائية من الحقول عند حذف المَعلمة fields. لمزيد من المعلومات، يُرجى الاطّلاع على عرض حقول معيّنة.

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

يمكن استخدام مورد approvals لبدء عمليات الموافقة وإدارتها باستخدام Drive API. تعمل هذه الطرق مع أي من نطاقات Drive API الحالية التي تستخدم بروتوكول OAuth 2.0 وتسمح بكتابة بيانات وصفية للملفات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختيار نطاقات 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&fields=nextPageToken,items(approvalId,status)' \
  -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

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

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