نظرات، بازخوردی هستند که توسط کاربر در مورد یک فایل ارائه میشوند، مانند خواننده یک سند پردازش کلمه که پیشنهاد میدهد چگونه یک جمله را به صورت دیگری بیان کند. دو نوع نظر وجود دارد: نظرات مرتبط و نظرات غیر مرتبط . یک نظر مرتبط با یک مکان خاص، مانند یک جمله در یک سند پردازش کلمه، در یک نسخه خاص از یک سند مرتبط است. برعکس، یک نظر غیر مرتبط فقط با سند مرتبط است.
پاسخها به نظرات پیوست میشوند و نشاندهندهی پاسخ کاربر به نظر هستند. Drive API به کاربران شما اجازه میدهد تا نظرات و پاسخها را به اسناد ایجاد شده توسط برنامهی شما اضافه کنند. در مجموع، یک نظر با پاسخها به عنوان یک بحث شناخته میشود.
استفاده از پارامتر فیلدها
برای همه متدها (به جز delete ) روی منبع comments ، باید پارامتر سیستمی fields را برای مشخص کردن فیلدهایی که باید در پاسخ برگردانده شوند، تنظیم کنید. در اکثر متدهای منبع Drive، این عمل فقط برای برگرداندن فیلدهای غیر پیشفرض لازم است، اما برای منبع comments اجباری است. اگر پارامتر fields را حذف کنید، متد خطا برمیگرداند. برای اطلاعات بیشتر، به بخش «بازگرداندن فیلدهای خاص» مراجعه کنید.
محدودیتهای نظر
محدودیتهای زیر هنگام کار با نظرات لنگردار و بدون لنگر با Drive API اعمال میشوند:
| نوع نظر | نوع فایل |
|---|---|
| لنگر انداخته شده |
|
| بدون لنگر |
|
افزودن یک نظر ضمیمهشده به آخرین ویرایش یک سند
وقتی یک نظر اضافه میکنید، ممکن است بخواهید آن را به ناحیهای در فایل متصل کنید. یک لنگر، ناحیهای را در یک فایل تعریف میکند که یک نظر به آن اشاره دارد. منبع comments ، فیلد anchor را به عنوان یک رشته JSON تعریف میکند.
برای اضافه کردن یک کامنت لنگردار:
(اختیاری). متد
listرا در منبعrevisionsفراخوانی کنید تا هرrevisionIDمربوط به یک سند را فهرست کند. فقط در صورتی که میخواهید یک نظر را به هر نسخهای غیر از آخرین نسخه متصل کنید، از این مرحله پیروی کنید. اگر میخواهید از آخرین نسخه استفاده کنید،headبرایrevisionIDاستفاده کنید.متد
createرا روی منبعcommentsبا پارامترfileID، یک منبعcommentsحاوی comment و یک رشتهی لنگر JSON حاویrevisionID(r) و region (a) فراخوانی کنید.
نمونه کد زیر نحوه ایجاد یک کامنت لنگردار را نشان میدهد:
پایتون
from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError
# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'
# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'
# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---
SCOPES = ["https://www.googleapis.com/auth/drive"]
creds = Credentials.from_authorized_user_file("token.json", SCOPES)
def create_anchored_comment():
"""
Create an anchored comment on a specific line in a Google Doc.
Returns:
The created comment object or None if an error occurred.
"""
try:
# Build the Drive API service
service = build("drive", "v3", credentials=creds)
# Define the anchor region for the comment.
# For Google Docs, the region is typically defined by 'line' and 'revision'.
# Other file types might use different region classifiers.
anchor = {
'region': {
'kind': 'drive#commentRegion',
'line': ANCHOR_LINE,
'rev': 'head'
}
}
# The comment body.
comment_body = {
'content': COMMENT_TEXT,
'anchor': anchor
}
# Create the comment request.
comment = (
service.comments()
.create(fileId=FILE_ID, fields="*", body=comment_body)
.execute()
)
print(f"Comment ID: {comment.get('id')}")
return comment
except HttpError as error:
print(f"An error occurred: {error}")
return None
create_anchored_comment()
API درایو، نمونهای از شیء منبع comments را برمیگرداند که شامل رشتهی anchor است.
یک نظر بدون لینک اضافه کنید
برای افزودن یک کامنت بدون لنگر، متد create را با پارامتر fileId و یک منبع comments حاوی کامنت فراخوانی کنید.
نظر به صورت متن ساده درج میشود، اما بدنه پاسخ یک فیلد htmlContent ارائه میدهد که حاوی محتوایی است که برای نمایش قالببندی شده است.
نمونه کد زیر نحوه ایجاد یک کامنت بدون لنگر را نشان میدهد:
پایتون
from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError
# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'
# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---
SCOPES = ["https://www.googleapis.com/auth/drive"]
creds = Credentials.from_authorized_user_file("token.json", SCOPES)
def create_unanchored_comment():
"""
Create an unanchored comment on a specific line in a Google Doc.
Returns:
The created comment object or None if an error occurred.
"""
try:
# Build the Drive API service
service = build("drive", "v3", credentials=creds)
# The comment body. For an unanchored comment,
# omit the 'anchor' property.
comment_body = {
'content': COMMENT_TEXT
}
# Create the comment request.
comment = (
service.comments()
.create(fileId=FILE_ID, fields="*", body=comment_body)
.execute()
)
print(f"Comment ID: {comment.get('id')}")
return comment
except HttpError as error:
print(f"An error occurred: {error}")
return None
create_unanchored_comment()
افزودن پاسخ به یک نظر
برای افزودن پاسخ به یک نظر، از متد 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."
}حل یک نظر
یک نظر فقط با ارسال پاسخ به یک نظر قابل حل است.
برای حل یک نظر، از متد create روی منبع replies با پارامترهای fileId و commentId استفاده کنید.
بدنه درخواست از فیلد action برای حل مشکل کامنت استفاده میکند. همچنین میتوانید فیلد content را طوری تنظیم کنید که پاسخی اضافه کند که کامنت را ببندد.
وقتی یک نظر حل میشود، درایو منبع comments را به صورت 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."
}نظر دریافت کنید
برای دریافت نظر در مورد یک فایل، از متد 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 ، پارامتر کوئری 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 برای بهروزرسانی نظر استفاده میکند.
فیلد بولی resolved در منبع comments فقط خواندنی است. یک نظر فقط با ارسال پاسخ به آن قابل حل است. برای اطلاعات بیشتر، به بخش حل یک نظر مراجعه کنید.
این متد فیلدهای لیست شده در پارامتر query 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 استفاده کنید.
وقتی یک نظر حذف میشود، درایو منبع نظر را به صورت deleted: true علامتگذاری میکند. نظرات حذف شده شامل فیلدهای htmlContent یا content نمیشوند.
درخواست
در این مثال، پارامترهای مسیر fileId و commentId را ارائه میدهیم.
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID