תגובות הן משוב שמשתמשים מספקים על קובץ, למשל קורא של מסמך לעיבוד תמלילים שמציע איך לנסח מחדש משפט. יש שני סוגים של תגובות: תגובות שמקושרות למיקום מסוים ותגובות שלא מקושרות למיקום מסוים. תגובה מוצמדת משויכת למיקום ספציפי, כמו משפט במסמך לעיבוד תמלילים, בגרסה ספציפית של המסמך. לעומת זאת, תגובה לא מקושרת משויכת רק למסמך.
תשובות מצורפות לתגובות ומייצגות את התגובה של המשתמש לתגובה. ה-Drive API מאפשר למשתמשים להוסיף תגובות ותשובות למסמכים שנוצרו על ידי האפליקציה שלכם. תגובה עם תשובות נקראת דיון.
שימוש בפרמטר fields
בכל השיטות (למעט delete) במשאב comments, חובה להגדיר את fields
הפרמטר system כדי לציין את השדות שיוחזרו בתגובה. ברוב השיטות של משאבי Drive, הפעולה הזו נדרשת רק כדי להחזיר שדות שאינם ברירת מחדל, אבל היא חובה עבור משאב comments. אם משמיטים את הפרמטר fields, השיטה מחזירה שגיאה. מידע נוסף זמין במאמר החזרת שדות ספציפיים.
מגבלות על תגובות
כשעובדים עם הערות מקושרות ולא מקושרות באמצעות Drive API, נאכפות ההגבלות הבאות:
| סוג התגובה | סוג הקובץ |
|---|---|
| מעוגן |
|
| לא מוצמד |
|
הוספת תגובה מקושרת לגרסה האחרונה של מסמך
כשמוסיפים תגובה, כדאי לעגן אותה לאזור מסוים בקובץ. עוגן מגדיר אזור בקובץ שאליו מתייחסת התגובה. המשאב comments מגדיר את השדה anchor כמחרוזת JSON.
כדי להוסיף תגובה שמקושרת לטקסט:
(אופציונלי). כדי לראות רשימה של כל
revisionIDבמסמך, קוראים לשיטהlistבמשאבrevisions. צריך לבצע את השלב הזה רק אם רוצים להוסיף הערה לגרסה קודמת ולא לגרסה האחרונה. אם רוצים להשתמש בגרסה האחרונה, צריך להשתמש ב-headבשבילrevisionID.קוראים ל-method
createבמשאבcommentsעם הפרמטרfileID, משאבcommentsשמכיל את התגובה ומחרוזת עוגן בפורמט JSON שמכילה אתrevisionID(r) ואת האזור (a).
בדוגמת הקוד הבאה מוצג איך יוצרים תגובה שמוצמדת לטקסט:
Python
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 שמכיל תוכן בפורמט שמתאים לתצוגה.
בדוגמת הקוד הבאה אפשר לראות איך יוצרים תגובה לא מעוגנת:
Python
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."
}סיום הטיפול בתגובה
אפשר לסמן תגובה כפתורה רק על ידי פרסום תשובה לתגובה.
כדי לפתור תגובה, משתמשים ב-method 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."
}קבלת תגובה
כדי לקבל תגובה על קובץ, משתמשים ב-method get במשאב comments עם הפרמטרים fileId ו-commentId. אם אתם לא יודעים את מזהה התגובה, אתם יכולים לרשום את כל התגובות באמצעות שיטת list.
השיטה מחזירה מופע של משאב comments.
כדי לכלול בתוצאות תגובות שנמחקו, מגדירים את פרמטר השאילתה 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)
עדכון תגובה
כדי לעדכן תגובה בקובץ, משתמשים ב-method 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."
}מחיקת תגובה
כדי למחוק תגובה בקובץ, משתמשים ב-method delete במשאב comments עם הפרמטרים fileId ו-commentId.
כשמוחקים תגובה, Drive מסמן את משאב התגובה כ-deleted: true. השדות htmlContent או content לא נכללים בתגובות שנמחקו.
בקשה
בדוגמה הזו, אנחנו מספקים את פרמטרים הנתיב fileId ו-commentId.
DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID