مدیریت تاییدیه‌ها

این سند نحوه مدیریت تأییدیه‌ها در API گوگل درایو را توضیح می‌دهد.

کاربران می‌توانند اسناد را از طریق یک فرآیند تأیید رسمی در گوگل درایو ارسال کنند. شما می‌توانید از این فرآیند برای دریافت تأییدیه برای بررسی قرارداد یا یک سند رسمی قبل از انتشار استفاده کنید. تأییدیه، وضعیت بررسی (مانند در حال انجام، تأیید شده یا رد شده) و همچنین وضعیت داوران مربوطه را پیگیری می‌کند. تأییدیه‌ها راهی عالی برای اعتبارسنجی محتوا و ثبت سوابق داوران هستند.

شما می‌توانید تأییدیه‌های محتوا را در درایو ایجاد و مدیریت کنید. رابط برنامه‌نویسی کاربردی گوگل درایو، منبع approvals را برای کار با تأییدیه‌های فایل فراهم می‌کند. روش‌های منبع approvals روی موارد موجود در درایو، گوگل داکز و سایر ویرایشگرهای گوگل ورک‌اسپیس کار می‌کنند. داوران می‌توانند مستقیماً اسناد را تأیید، رد یا بازخورد خود را در مورد آنها ثبت کنند.

قبل از اینکه شروع کنی

  1. فایل شما باید شامل قابلیت canStartApproval باشد. برای بررسی قابلیت‌های فایل، متد get را روی منبع files با پارامتر مسیر fileId فراخوانی کنید و از فیلد قابلیت canStartApproval در پارامتر fields استفاده کنید. برای اطلاعات بیشتر، به بخش «درک قابلیت‌های فایل» مراجعه کنید.

    قابلیت بولی canStartApproval در موارد زیر false است:

    • تنظیمات مدیر، دسترسی به این ویژگی را محدود می‌کند.
    • نسخه Google Workspace شما واجد شرایط نیست.
    • این فایل متعلق به کاربری خارج از دامنه شما است.
    • کاربر فاقد مجوز role=writer در فایل است.

  2. مطمئن شوید که فایل هدف را به صورت دستی با داوران به اشتراک می‌گذارید. درایو این کار را به صورت خودکار انجام نمی‌دهد. اگر داور به فایل دسترسی نداشته باشد، درخواست تأیید با موفقیت انجام می‌شود، اما او اعلانی دریافت نمی‌کند یا نمی‌تواند فایل را مشاهده کند.

مفاهیم

مفاهیم کلیدی زیر، پایه و اساس تاییدیه‌ها را تشکیل می‌دهند.

وضعیت تأیید

وقتی درخواست تأیید سندی را می‌دهید، فرآیند تأیید تضمین می‌کند که هر داور نسخه یکسانی از محتوا را تأیید می‌کند. اگر فایل پس از تأیید درخواست توسط داور و قبل از تکمیل درخواست ویرایش شود، تأییدهای داور مجدداً تنظیم می‌شوند و داوران باید نسخه جدید را تأیید کنند. اگر محتوا پس از تأیید نهایی ویرایش شود، بنری روی سند ظاهر می‌شود که نشان می‌دهد نسخه فعلی با نسخه تأیید شده متفاوت است.

منبع approvals شامل یک شیء Status است که وضعیت تأیید را هنگام درخواست منبع شرح می‌دهد. همچنین شامل شیء ReviewerResponse است که پاسخ‌های مربوط به تأیید انجام شده توسط بررسی‌کنندگان خاص را شرح می‌دهد. پاسخ هر بررسی‌کننده توسط شیء Response نمایش داده می‌شود.

هر عملی در فرآیند تأیید، اعلان‌های ایمیلی ایجاد می‌کند که برای آغازگر (کاربری که درخواست تأیید می‌کند) و همه بررسی‌کنندگان ارسال می‌شود. همچنین به گزارش فعالیت تأیید اضافه می‌شود.

همه بررسی‌کنندگان باید یک تأیید را تأیید کنند. هر بررسی‌کننده‌ای که تأیید را رد کند، وضعیت تکمیل‌شده را به DECLINED تغییر می‌دهد.

پس از تکمیل یک تأیید (وضعیت APPROVED ، CANCELLED یا DECLINED )، در حالت تکمیل شده باقی می‌ماند و آغازگر یا بررسی‌کنندگان نمی‌توانند با آن تعامل داشته باشند. تا زمانی که هیچ تأییدیه‌ای در فایلی با وضعیت IN_PROGRESS وجود نداشته باشد، می‌توانید نظرات خود را به یک تأیید تکمیل شده اضافه کنید.

چرخه حیات یک تاییدیه

چرخه حیات یک تاییدیه.
شکل ۱. چرخه حیات یک تاییدیه.

یک تاییدیه در طول چرخه حیات خود از چندین مرحله عبور می‌کند. شکل 1 مراحل سطح بالای چرخه حیات یک تاییدیه را نشان می‌دهد:

  1. شروع تأیید . برای شروع درخواست تأیید، start را فراخوانی کنید. سپس status روی IN_PROGRESS تنظیم می‌شود.

  2. تأیید در انتظار است . در حالی که تأیید در انتظار است ( status روی IN_PROGRESS تنظیم شده است)، هم آغازگر و هم بررسی‌کنندگان می‌توانند با آن تعامل داشته باشند. آن‌ها می‌توانند comment اضافه کنند، آغازگر می‌تواند بررسی‌کنندگان را reassign و یک یا چند بررسی‌کننده می‌توانند درخواست را approve .

  3. تأیید در حالت تکمیل‌شده است . یک تأیید زمانی وارد حالت تکمیل‌شده می‌شود ( status روی APPROVED ، CANCELLED یا DECLINED تنظیم می‌شود) که همه بررسی‌کنندگان درخواست را تأیید کنند، آغازکننده تصمیم به cancel درخواست بگیرد، یا هر یک از بررسی‌کنندگان تصمیم به decline درخواست بگیرد.

استفاده از پارامتر فیلدها

اگر می‌خواهید فیلدهایی را که باید در پاسخ برگردانده شوند، مشخص کنید، می‌توانید پارامتر سیستمی fields را با هر متدی از منبع approvals تنظیم کنید. اگر پارامتر fields را حذف کنید، سرور مجموعه‌ای پیش‌فرض از فیلدهای خاص متد را برمی‌گرداند. برای برگرداندن فیلدهای مختلف، به بخش Return specific fields مراجعه کنید.

شروع و مدیریت تاییدیه‌ها

منبع approvals می‌تواند برای شروع و مدیریت تأییدیه‌ها با استفاده از Drive API مورد استفاده قرار گیرد. این روش‌ها با هر یک از محدوده‌های موجود OAuth 2.0 Drive API که امکان نوشتن فراداده‌های فایل را فراهم می‌کنند، کار می‌کنند. برای اطلاعات بیشتر، به Choose Google Drive API scopes مراجعه کنید.

شروع تأیید

برای شروع یک تایید جدید روی یک فایل، از متد start روی منبع approvals استفاده کنید و پارامتر مسیر fileId را نیز اضافه کنید.

متن درخواست شامل یک فیلد الزامی reviewerEmails است که آرایه‌ای از رشته‌ها شامل آدرس‌های ایمیل داورانی است که برای بررسی فایل تعیین شده‌اند. هر آدرس ایمیل داور باید با یک حساب گوگل مرتبط باشد، در غیر این صورت درخواست با شکست مواجه می‌شود. علاوه بر این، سه فیلد اختیاری ارائه می‌شود:

  • dueTime : آخرین مهلت برای تأیید در قالب RFC 3339.
  • lockFile : یک مقدار بولی که نشان می‌دهد آیا فایل هنگام شروع تأیید قفل شود یا خیر. این کار مانع از تغییر فایل توسط کاربران در طول فرآیند تأیید می‌شود. هر کاربری که دارای مجوز role=writer باشد می‌تواند این قفل را حذف کند.
  • message : یک پیام سفارشی که برای داوران ارسال می‌شود.

بدنه پاسخ شامل نمونه‌ای از منبع approvals است و شامل فیلد initiator است که کاربری است که درخواست تأییدیه را داده است. Status تأییدیه روی IN_PROGRESS تنظیم شده است.

اگر یک تاییدیه موجود با Status IN_PROGRESS وجود داشته باشد، متد start با شکست مواجه می‌شود. شما فقط در صورتی می‌توانید یک تاییدیه را شروع کنید که هیچ تاییدیه موجودی در فایل وجود نداشته باشد یا تاییدیه موجود در حالت تکمیل شده باشد (وضعیت APPROVED ، CANCELLED یا DECLINED باشد).

حلقه زدن 

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 -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 -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 -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 (designed method) فقط زمانی قابل فراخوانی است که وضعیت تایید ( Status IN_PROGRESS باشد.

بدنه درخواست شامل یک فیلد message اختیاری است که رشته‌ای حاوی پیامی است که باید همراه با رد درخواست تأیید ارسال شود.

بدنه پاسخ شامل نمونه‌ای از منبع approvals است. پیام به عنوان یک اعلان ارسال می‌شود و همچنین در گزارش فعالیت تأیید قرار می‌گیرد. فیلد response شیء ReviewerResponse کاربر درخواست‌کننده روی DECLINED تنظیم شده است. علاوه بر این، Status تأیید روی DECLINED تنظیم شده و در حالت تکمیل‌شده قرار دارد.

حلقه زدن 

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 -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 -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 تنظیم نکنید، سرور تا ۱۰۰ تاییدیه برمی‌گرداند.

  • pageToken : یک توکن صفحه که از فراخوانی لیست قبلی دریافت شده است. این توکن برای بازیابی صفحه بعدی استفاده می‌شود. باید روی مقدار nextPageToken از پاسخ قبلی تنظیم شود.

حلقه زدن 

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 برنامه شما.