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