ניהול התגובות והתשובות

תגובות הן משוב שהמשתמשים סיפקו על קובץ, למשל קורא של מסמך מעבד תמלילים עם הצעות לניסוח מחדש של משפט. יש שני סוגים של תגובות: תגובות מעוגנות ותגובות לא מעוגנות. תגובה מעוגנת משויכת למיקום ספציפי, כמו משפט במסמך עיבוד תמלילים, בגרסה ספציפית של מסמך. לעומת זאת, תגובה לא מעוגנת תשויך רק למסמך.

הערה: בקובצי blob, ממשק Google Drive API תומך רק בתגובות לא מעוגנות. אין תמיכה בתגובות מעוגנות בקובצי blob או בקובצי עורך Google Docs.

תשובות מצורפות לתגובות ומייצגות את תגובת המשתמש לתגובה. ה-API של Drive מאפשר למשתמשים להוסיף תגובות ותשובות למסמכים שהאפליקציה שלכם יצרה. ביחד, תגובה עם תשובות נקראת דיון.

הוספת תגובה לא מעוגנת

כדי להוסיף תגובה לא מעוגנת למסמך, צריך לקרוא לשיטה comments.create עם הפרמטר fileId ולמשאב comments שמכיל את התגובה.

התגובה מוכנסת כטקסט פשוט, אבל גוף התשובה מספק שדה htmlContent שמכיל תוכן שמעוצב לתצוגה.

חשוב: מומלץ לבדוק שלמשתמש יש את ההרשאות המתאימות להוספת תגובות. בנוסף, רק יוצר התגובה או התשובה יכול למחוק או לערוך תגובה או תשובה. שגיאות מתרחשות כאשר משתמש בתפקיד שאינו יוצר מנסה למחוק או לערוך תגובה. כדי למנוע את השגיאות האלה, בודקים את השדה author.me במשאב התגובות כדי לוודא שהמשתמש ששלח את הבקשה הוא מי שכתב את התגובה, ואז מאמתים את ההרשאות שלו ביחס לתגובה.

הוספת תשובה לתגובה

כדי להוסיף תשובה לתגובה, קוראים לשיטה replies.create עם ההערה, לפרמטר fileId ולמשאב replies שמכיל את התשובה.

התשובה מתווספת כטקסט פשוט, אבל גוף התשובה מספק שדה htmlContent שמכיל תוכן שמעוצב לתצוגה.

הוספת תגובה מעוגנת לגרסה האחרונה של המסמך

כשאתם מוסיפים תגובה, כדאי לעגן אותה לאזור בקובץ. עוגן מגדיר את הגרסה הקודמת של הקובץ ואת האזור בקובץ שאליו התגובה מתייחסת. המשאב comments מגדיר את השדה anchor כמחרוזת JSON.

הערה: בקובצי blob, ה-API של Drive תומך רק בתגובות לא מעוגנות. אין תמיכה בתגובות מעוגנות בקובצי blob או בקבצים של עורך Google Docs.

חשוב לדעת: אי אפשר לשנות את עוגנים, ואי אפשר להבטיח את המיקום שלהם ביחס לתוכן של המסמך בין גרסאות שונות. מומלץ להשתמש בעוגנים במסמכים שבהם המיקום לא משתנה, למשל קובצי תמונה או מסמכים לקריאה בלבד.

כדי להוסיף תגובה מעוגנת:

1. (אופציונלי). קוראים ל-method revisions.list כדי להציג את כל revisionID של המסמך. בצעו את השלב הזה רק אם אתם רוצים לעגן תגובה לגרסה כלשהי שאינה הגרסה האחרונה. אם ברצונך להשתמש בגרסה העדכנית ביותר, יש להשתמש ב-head עבור revisionID.

2. קוראים לשיטה comments.create עם הפרמטר fileID, משאב comments שמכיל את התגובה ולמחרוזת עוגן של JSON שמכילה את revisionID (r) והאזור (a).

האופן שבו מגדירים אזור משתנה בהתאם לסוג תוכן המסמכים שאתם עובדים איתו. למידע נוסף, ראו הגדרת אזור.

הערה: מומלץ לבדוק שלמשתמש יש את ההרשאות המתאימות כדי להוסיף תגובות. בנוסף, רק יוצר התגובה או התשובה יכול למחוק או לערוך תגובה או תשובה. שגיאות מתרחשות כשאדם בתפקיד שאינו יוצר מנסה למחוק או לערוך תגובה. כדי להימנע משגיאות כאלה, בודקים את השדה author.me במשאב התגובות.

הגדרת אזור

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

חשוב: אם האפליקציה מאפשרת למשתמשים לעדכן ולשתף מספר גרסאות קודמות של מסמך, ייתכן שתגובות על גרסאות ישנות יותר לא יחולו על המיקום המקושר. לכן עליכם לציין בבירור לאיזו גרסה של כל תגובה שייכת כל תגובה בממשק המשתמש שלכם.

סימון שהתגובה טופלה

השתמשו בשיטה comment.update כדי להגדיר את המאפיין resolved במשאב comments ל-true לאחר הטיפול בתגובה.

כשהאפליקציה מגדירה את המאפיין resolved לערך true, ממשק המשתמש אמור לציין שהתגובה טופלה. לדוגמה, האפליקציה עשויה:

• חסימת תשובות נוספות ועמעום כל התשובות הקודמות וגם התגובה המקורית.
• הסתרת התגובות שהסתיימו.

מחיקת תגובה

משתמשים בשיטה comments.delete כדי למחוק תגובות. כשמוחקים תגובה, Drive מסמן את המשאב של התגובה בתור "deleted": "true".

הצגת רשימה של תגובות

משתמשים בשיטה comments.list כדי להציג את רשימת התגובות. אם רוצים לכלול תגובות שנמחקו בתוצאות, צריך להגדיר את השדה includedDeleted לערך true.