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

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

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

שימוש בפרמטר fields

בכל השיטות (למעט delete) במשאב comments, חובה להגדיר את fields הפרמטר system כדי לציין את השדות שיוחזרו בתגובה. ברוב ה-methods של משאבי Drive, הפעולה הזו נדרשת רק כדי להחזיר שדות שאינם ברירת מחדל, אבל היא חובה עבור משאב comments. אם משמיטים את הפרמטר fields, השיטה מחזירה שגיאה. מידע נוסף זמין במאמר החזרת שדות ספציפיים.

מגבלות על תגובות

כשעובדים עם הערות מקושרות ולא מקושרות באמצעות Drive API, נאכפות ההגבלות הבאות:

סוג התגובה	סוג הקובץ
מעוגן	מפתחים יכולים להגדיר פורמט משלהם למפרט של מודעות העוגן. העוגן נשמר ומוחזר כשמאחזרים את התגובה, אבל אפליקציות העריכה של Google Workspace מתייחסות לתגובות האלה כתגובות לא מקושרות.
לא מוצמד	התכונה נתמכת במסמכים ב-Google Workspace, והתגובות יופיעו בתצוגה 'כל התגובות'. תגובות לא מקושרות לא מוצגות בקובצי PDF שעברו עיבוד בתצוגה המקדימה של קבצים ב-Drive, אבל הן נשמרות ואפשר לאחזר אותן באמצעות Drive API.

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

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

כדי להוסיף תגובה שמוצמדת לטקסט:

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

עדכון תגובה

כדי לעדכן תגובה בקובץ, משתמשים ב-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

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

שימוש בפרמטר fields

מגבלות על תגובות

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

Python

הוספת תגובה לא מקושרת

Python

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

סיום הטיפול בתגובה

קבלת תגובה

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

עדכון תגובה

מחיקת תגובה

נושאים קשורים

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