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