תגובות הן משוב שמשתמשים מספקים לגבי קובץ, למשל, קורא של מסמך עיבוד טקסט שמציע איך לנסח מחדש משפט. יש שני סוגים של תגובות: תגובות מוצמדות ותגובות לא מוצמדות. תגובה מוצמדת משויכת למיקום ספציפי, כמו משפט במסמך עיבוד טקסט, בגרסה ספציפית של המסמך. לעומת זאת, תגובה ללא עיגון משויכת רק למסמך.
תשובות מצורפות לתגובות ומייצגות את התגובה של המשתמש לתגובה. באמצעות Drive API, המשתמשים יכולים להוסיף תגובות ותשובות למסמכים שנוצרו על ידי האפליקציה שלכם. תגובה עם תשובות נקראת דיון.
צריך להגדיר את הפרמטר fields כדי לרשום את השדות שיוחזרו בתגובה כשקוראים לכל method שמופיע במשאב comments. אם משמיטים את הפרמטר, השיטה מחזירה שגיאה. במאמר החזרת שדות ספציפיים מוסבר איך מחזירים את השדות הספציפיים שדרושים לכם.
הוספת תגובה ללא עיגון
כדי להוסיף תגובה לא מעוגנת למסמך, צריך להפעיל את השיטה create() עם הפרמטר fileId ומשאבי comments שמכילים את התגובה.
התגובה מוכנסת כטקסט פשוט, אבל גוף התשובה כולל את השדה htmlContent שמכיל תוכן בפורמט להצגה.
איך עונים לתגובות?
כדי להוסיף תשובה לתגובה, משתמשים ב-method replies.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 replies.create() במשאב replies עם הפרמטרים fileId ו-commentId.
גוף הבקשה משתמש בשדה action כדי לטפל בתגובה. אפשר גם להגדיר את השדה content כדי להוסיף תשובה שסוגרת את התגובה.
כשתגובה נסגרת, מערכת Drive מסמנת את משאב התגובה בתווית 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."
}
הוספת תגובה מוצמדת לגרסה האחרונה של מסמך
כשאתם מוסיפים תגובה, כדאי לקשר אותה לאזור בקובץ. עוגן מגדיר את הגרסה של הקובץ ואת האזור בקובץ שאליו מתייחסת התגובה. המשאב comments מגדיר את השדה anchor כמחרוזת JSON.
כדי להוסיף תגובה מוצמדת:
(אופציונלי). כדי לקבל רשימה של כל
revisionIDשל מסמך, צריך להפעיל את השיטהrevisions.list(). צריך לבצע את השלב הזה רק אם רוצים לצרף תגובה לגרסה כלשהי מלבד הגרסה האחרונה. אם רוצים להשתמש בגרסה האחרונה, צריך להשתמש ב-headעבורrevisionID.קוראים ל-method
create()עם הפרמטרfileID, משאבcommentsשמכיל את התגובה ומחרוזת עוגן JSON שמכילה אתrevisionID(r) ואת האזור (a).
אופן ההגדרה של אזור משתנה בהתאם לסוג התוכן של המסמך שבו אתם עובדים. מידע נוסף זמין במאמר הגדרת אזור.
הגדרת אזור
כפי שצוין קודם, מחרוזת הצירוף של ה-JSON מכילה את השדה revisionID (r) ואת האזור (a). האזור (a) הוא מערך JSON שמכיל סיווגים של אזורים שמציינים את הפורמט והמיקום שאליהם מצורף התגובה. סיווג יכול להיות מלבן דו-מימדי של תמונה, שורת טקסט במסמך או משך זמן בסרטון. כדי להגדיר אזור, בוחרים את סיווג האזור שתואם לסוג התוכן שאתם מנסים לקשר. לדוגמה, אם התוכן הוא טקסט, סביר להניח שתשתמשו במסווג האזורים txt או line.
רשימה של סיווגים של אזורים ב-Drive API מופיעה במאמר סיווגים של אזורים.
בדוגמה הבאה מוצגת מחרוזת עוגן של JSON שמקשרת הערות לשורות בשני אזורים נפרדים במסמך:
- האזור הראשון מתחיל בשורה 12 (
'n':12) ונמשך שלוש שורות ('l':3). - האזור השני מכסה רק את השורה 18 (
'n':18, 'l':1).
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
מחליפים את REVISION_ID ב-head או במזהה של גרסה ספציפית.
אחזור תגובה
כדי לקבל תגובה על קובץ, משתמשים ב-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 כדי לעדכן את התגובה.
השיטה מחזירה את השדות שמפורטים בפרמטר השאילתה 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