نظرات بازخورد ارائه شده توسط کاربر در مورد یک فایل است، مانند خواننده یک سند پردازش کلمه که نحوه بازنویسی یک جمله را پیشنهاد می کند. دو نوع نظر وجود دارد: نظرات لنگر و نظرات بدون لنگر . یک نظر لنگر با یک مکان خاص، مانند یک جمله در یک سند پردازش کلمه، در یک نسخه خاص از یک سند مرتبط است. برعکس، یک نظر بدون لنگر فقط با سند مرتبط است.
پاسخها به نظرات پیوست میشوند و پاسخ کاربر به نظر را نشان میدهند. 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