תגובות הן משוב שמשתמשים מספקים על קובץ, למשל קורא של מסמך לעיבוד תמלילים שמציע איך לנסח מחדש משפט. יש שני סוגים של תגובות: תגובות שמקושרות למיקום מסוים ותגובות שלא מקושרות למיקום מסוים. תגובה מוצמדת משויכת למיקום ספציפי, כמו משפט במסמך לעיבוד תמלילים, בגרסה ספציפית של המסמך. לעומת זאת, תגובה לא מוצמדת משויכת רק למסמך.
תשובות מצורפות לתגובות ומייצגות את התגובה של המשתמש לתגובה. באמצעות 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)
עדכון תגובה
כדי לעדכן תגובה בקובץ, משתמשים בשיטה 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