نظرات بازخورد ارائه شده توسط کاربر در مورد یک فایل است، مانند خواننده یک سند پردازش کلمه که نحوه بازنویسی یک جمله را پیشنهاد می کند. دو نوع نظر وجود دارد: نظرات لنگر و نظرات بدون لنگر . یک نظر لنگر با یک مکان خاص، مانند یک جمله در یک سند پردازش کلمه، در یک نسخه خاص از یک سند مرتبط است. برعکس، یک نظر بدون لنگر فقط با سند مرتبط است.
پاسخ‌ها به نظرات پیوست می‌شوند و پاسخ کاربر به نظر را نشان می‌دهند. Drive API به کاربران شما امکان می دهد نظرات و پاسخ هایی را به اسناد ایجاد شده توسط برنامه شما اضافه کنند. در مجموع، یک نظر با پاسخ به عنوان یک بحث شناخته می شود.
تنظیم پارامتر fields برای فهرست کردن فیلدهایی که باید در هنگام فراخوانی هر روش فهرست شده در منبع comments ، در پاسخ برگردند، لازم است. اگر پارامتر را حذف کنید، متد یک خطا برمی گرداند. برای برگرداندن فیلدهای دقیق مورد نیاز، به بازگشت فیلدهای خاص مراجعه کنید.
یک نظر بدون پیوند اضافه کنید
برای افزودن یک نظر بدون لنگر به یک سند، متد create() با پارامتر fileId و یک منبع comments حاوی نظر فراخوانی کنید.
نظر به عنوان متن ساده درج می شود، اما بدنه پاسخ یک فیلد htmlContent حاوی محتوای قالب بندی شده برای نمایش را ارائه می دهد.
یک پاسخ به یک نظر اضافه کنید
برای افزودن پاسخ به نظر، از متد replies.create() در منبع replies با پارامترهای fileId و commentId استفاده کنید. بدنه درخواست از فیلد content برای افزودن پاسخ استفاده می کند.
پاسخ به صورت متن ساده درج می شود، اما بدنه پاسخ یک فیلد htmlContent حاوی محتوای قالب بندی شده برای نمایش را ارائه می دهد.
متد فیلدهای فهرست شده در فیلد fields را برمی گرداند.
یک مثال نشان دهید
درخواست کنید
در این مثال، پارامترهای مسیر fileId و commentId و چندین فیلد را ارائه می کنیم.
POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment
درخواست بدن
{
"content": "This is a reply to a comment."
}یک نظر را حل کنید
یک نظر فقط با ارسال یک پاسخ به یک نظر قابل حل است.
برای حل یک نظر، از متد replies.create() در منبع replies با پارامترهای fileId و commentId استفاده کنید.
بدنه درخواست از فیلد action برای حل نظر استفاده می کند. همچنین می‌توانید فیلد content را برای اضافه کردن پاسخی تنظیم کنید که نظر را می‌بندد.
وقتی نظری حل می‌شود، Drive منبع نظر را به‌عنوان resolved: true . برخلاف نظرات حذف شده ، نظرات حل شده می توانند شامل فیلدهای htmlContent یا content باشند.
هنگامی که برنامه شما نظری را حل می کند، رابط کاربری شما باید نشان دهد که نظر مورد نظر قرار گرفته است. برای مثال، برنامه شما ممکن است:
- پاسخ‌های بیشتر را مجاز نکنید و همه پاسخ‌های قبلی به اضافه نظر اصلی را کم‌رنگ کنید.
- پنهان کردن نظرات حل شده
یک مثال نشان دهید
درخواست کنید
در این مثال، پارامترهای مسیر fileId و commentId و چندین فیلد را ارائه می کنیم.
POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment
درخواست بدن
{
"action": "resolve",
"content": "This comment has been resolved."
}یک نظر لنگر به آخرین ویرایش یک سند اضافه کنید
وقتی نظری را اضافه می کنید، ممکن است بخواهید آن را به منطقه ای در فایل متصل کنید. یک لنگر بازبینی فایل و منطقه را در فایلی که نظر به آن اشاره دارد، تعریف می کند. منبع comments ، فیلد anchor را به عنوان یک رشته JSON تعریف می کند.
برای افزودن یک نظر لنگر:
(اختیاری). متد
revisions.list()را فراخوانی کنید تا همهrevisionIDبرای یک سند فهرست شوند. فقط در صورتی این مرحله را دنبال کنید که می خواهید نظری را به هر ویرایشی غیر از آخرین ویرایش لنگر بزنید. اگر می خواهید از آخرین نسخه استفاده کنید،headبرایrevisionIDاستفاده کنید.متد
create()را با پارامترfileID، یک منبعcommentsحاوی کامنت، و یک رشته لنگر JSON حاویrevisionID(r) و منطقه (a) فراخوانی کنید.
نحوه تعریف یک منطقه به نوع محتوای سندی که با آن کار می کنید بستگی دارد. برای اطلاعات بیشتر، به تعریف منطقه مراجعه کنید.
یک منطقه را تعریف کنید
همانطور که قبلا ذکر شد، رشته لنگر JSON شامل revisionID ( r ) و ناحیه ( a ) است. منطقه ( a ) یک آرایه JSON است که شامل طبقه‌بندی‌کننده‌های ناحیه است که فرمت و مکانی را که یک نظر به آن لنگر می‌یابد مشخص می‌کند. یک طبقه‌بندی‌کننده ممکن است یک مستطیل دو بعدی برای یک تصویر، یک خط متن در یک سند یا مدت زمان در یک ویدیو باشد. برای تعریف منطقه، طبقه‌بندی‌کننده منطقه‌ای را انتخاب کنید که با نوع محتوایی که می‌خواهید به آن متصل شوید مطابقت دارد. به عنوان مثال، اگر محتوای شما متنی است، احتمالاً از طبقه‌بندی‌کننده txt یا line منطقه استفاده می‌کنید.
برای فهرستی از طبقه‌بندی‌کننده‌های منطقه در Drive API، به طبقه‌بندی‌کننده‌های منطقه مراجعه کنید.
مثال زیر یک رشته لنگر JSON را نشان می دهد که نظرات را به خطوط در دو ناحیه جداگانه از یک سند متصل می کند:
- ناحیه اول از خط 12 (
'n':12) شروع می شود و تا سه خط ('l':3) امتداد می یابد. - ناحیه دوم فقط خط 18 را پوشش می دهد (
'n':18, 'l':1').
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
REVISION_ID با head یا شناسه یک نسخه خاص جایگزین کنید.
نظر بدهید
برای دریافت نظر روی یک فایل، از متد get() در منبع comments با پارامترهای fileId و commentId استفاده کنید. اگر شناسه نظر را نمی‌دانید، می‌توانید همه نظرات را با استفاده از متد list() فهرست کنید.
این روش نمونه ای از یک منبع comments را برمی گرداند.
برای گنجاندن نظرات حذف شده در نتایج، پارامتر query includedDeleted را روی true تنظیم کنید.
یک مثال نشان دهید
درخواست کنید
در این مثال، پارامترهای مسیر fileId و commentId و چندین فیلد را ارائه می کنیم.
GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved
لیست نظرات
برای فهرست کردن نظرات روی یک فایل، از متد list() در منبع comments با پارامتر fileId استفاده کنید. این روش فهرستی از نظرات را برمی گرداند.
برای سفارشی کردن صفحه بندی یا فیلتر کردن نظرات، پارامترهای پرس و جو زیر را ارسال کنید:
includeDeleted: برای اضافه کردن نظرات حذف شده رویtrueتنظیم کنید. نظرات حذف شده شامل فیلدهایhtmlContentیاcontentنمی شود.pageSize: حداکثر تعداد نظرات برای بازگشت در هر صفحه.pageToken: یک نشانه صفحه، دریافت شده از یک تماس فهرست قبلی. این نشانه را برای بازیابی صفحه بعدی ارائه دهید.startModifiedTime: حداقل مقدار فیلدmodifiedTimeبرای نظرات نتیجه.
یک مثال نشان دهید
درخواست کنید
در این مثال، پارامتر مسیر fileId ، پارامتر query includeDeleted و چندین فیلد را ارائه می کنیم.
GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)
یک نظر را به روز کنید
برای به روز رسانی یک نظر در یک فایل، از متد update() در منبع comments با پارامترهای fileId و commentId استفاده کنید. بدنه درخواست از فیلد content برای به روز رسانی نظر استفاده می کند.
این روش فیلدهای فهرست شده در پارامتر پرس و جو fields را برمی گرداند.
یک مثال نشان دهید
درخواست کنید
در این مثال، پارامترهای مسیر fileId و commentId و چندین فیلد را ارائه می کنیم.
PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment
درخواست بدن
{
"content": "This comment is now updated."
}یک نظر را حذف کنید
برای حذف نظر روی یک فایل، از متد delete() در منبع comments با پارامترهای fileId و commentId استفاده کنید.
وقتی نظری حذف می‌شود، Drive منبع نظر را به‌عنوان deleted: true . نظرات حذف شده شامل فیلدهای htmlContent یا content نمی شود.
یک مثال نشان دهید
درخواست کنید
در این مثال، پارامترهای مسیر fileId و commentId را ارائه می دهیم.
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID