نظرات بازخورد ارائه شده توسط کاربر در مورد یک فایل است، مانند خواننده یک سند پردازش کلمه که نحوه بازنویسی یک جمله را پیشنهاد می کند. دو نوع نظر وجود دارد: نظرات لنگر و نظرات بدون لنگر . یک نظر لنگر با یک مکان خاص، مانند یک جمله در یک سند پردازش کلمه، در یک نسخه خاص از یک سند مرتبط است. برعکس، یک نظر بدون لنگر فقط با سند مرتبط است.
پاسخ‌ها به نظرات پیوست می‌شوند و پاسخ کاربر به نظر را نشان می‌دهند. Drive API به کاربران شما امکان می دهد نظرات و پاسخ هایی را به اسناد ایجاد شده توسط برنامه شما اضافه کنند. در مجموع، یک نظر با پاسخ به عنوان یک بحث شناخته می شود.
از پارامتر فیلدها استفاده کنید
برای همه روش ها (به استثنای delete ) در منبع comments ، باید پارامتر سیستم fields را تنظیم کنید تا فیلدهایی را که باید در پاسخ بازگردانده شوند، مشخص کنید. در اکثر روش‌های منبع Drive، این عمل فقط برای برگرداندن فیلدهای غیر پیش‌فرض مورد نیاز است، اما برای منبع comments اجباری است. اگر پارامتر fields حذف کنید، متد یک خطا برمی‌گرداند. برای اطلاعات بیشتر، به قسمت‌های خاص بازگشت مراجعه کنید.
محدودیت های نظر دادن
محدودیت‌های زیر هنگام کار با نظرات لنگر و بدون لنگر با Drive API اعمال می‌شوند:
| نوع نظر | نوع فایل |
|---|---|
| لنگر انداخته است |
|
| بدون لنگر |
|
یک نظر لنگر به آخرین ویرایش یک سند اضافه کنید
وقتی نظری را اضافه می کنید، ممکن است بخواهید آن را به منطقه ای در فایل متصل کنید. یک لنگر منطقه ای را در یک فایل تعریف می کند که یک نظر به آن اشاره دارد. منبع comments ، فیلد anchor را به عنوان یک رشته JSON تعریف می کند.
برای افزودن یک نظر لنگر:
(اختیاری). برای فهرست کردن همه
revisionIDبرای یک سند، متدlistموجود در منبعrevisionsرا فراخوانی کنید. فقط در صورتی این مرحله را دنبال کنید که می خواهید نظری را به هر ویرایشی غیر از آخرین ویرایش لنگر بزنید. اگر می خواهید از آخرین نسخه استفاده کنید،headبرایrevisionIDاستفاده کنید.متد
createرا در منبعcommentsبا پارامترfileID، یک منبعcommentsحاوی نظر، و یک رشته لنگر JSON حاویrevisionID(r) و منطقه (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()
Drive 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 را برای اضافه کردن پاسخی تنظیم کنید که نظر را می‌بندد.
وقتی نظری حل می‌شود، Drive منبع 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 ، پارامتر 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 برای به روز رسانی نظر استفاده می کند.
فیلد resolved بولی در منبع comments فقط خواندنی است. یک نظر فقط با ارسال یک پاسخ به یک نظر قابل حل است. برای اطلاعات بیشتر، به حل نظر مراجعه کنید.
این روش فیلدهای فهرست شده در پارامتر پرس و جو 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