إدارة التعليقات والردود

التعليقات هي ملاحظات يقدّمها المستخدمون حول ملف، مثل أن يقترح قارئ مستند لمعالجة الكلمات طريقة لإعادة صياغة جملة. يتوفّر نوعان من التعليقات: التعليقات المثبَّتة والتعليقات غير المثبَّتة. يرتبط التعليق المثبَّت بموقع جغرافي معيّن، مثل جملة في مستند لمعالجة الكلمات، ضمن إصدار معيّن من مستند. في المقابل، يرتبط التعليق غير المثبَّت بالمستند فقط.

الردود مرتبطة بالتعليقات وتمثّل استجابة المستخدم للتعليق. تتيح Drive API للمستخدمين إضافة تعليقات وردود على المستندات التي ينشئها تطبيقك. ويُعرف التعليق الذي يتضمّن ردودًا باسم مناقشة.

استخدام مَعلمة fields

بالنسبة إلى جميع الطرق (باستثناء delete) في مورد comments، يجب ضبط fields مَعلمة النظام لتحديد الحقول المطلوب عرضها في الردّ. في معظم طرق موارد Drive، يكون هذا الإجراء مطلوبًا فقط لعرض الحقول غير التلقائية، ولكنّه إلزامي لمورد comments. إذا تم حذف مَعلمة fields، ستعرض الطريقة خطأً. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة عرض حقول معيّنة.

قيود التعليقات

يتم فرض القيود التالية عند استخدام التعليقات المثبَّتة وغير المثبَّتة مع Drive API:

نوع التعليقات	نوع الملف
مثبَّتة	يمكن للمطوّرين تحديد تنسيقهم الخاص لمواصفات الرابط. يتم حفظ الرابط وعرضه عند استرداد التعليق، ولكنّ تطبيقات محرّر Google Workspace تتعامل مع هذه التعليقات على أنّها تعليقات غير مثبَّتة.
غير مثبَّتة	تتوفّر هذه التعليقات في مستندات Google Workspace، والتي ستعرضها في طريقة العرض "كل التعليقات". لا تظهر التعليقات غير المثبَّتة على ملفات PDF التي يتم عرضها في أداة معاينة ملفات Drive، على الرغم من حفظها وإمكانية استردادها من خلال Drive API.

نوع التعليقات

نوع الملف

مثبَّتة

يمكن للمطوّرين تحديد تنسيقهم الخاص لمواصفات الرابط.
يتم حفظ الرابط وعرضه عند استرداد التعليق، ولكنّ تطبيقات محرّر Google Workspace تتعامل مع هذه التعليقات على أنّها تعليقات غير مثبَّتة.

غير مثبَّتة

تتوفّر هذه التعليقات في مستندات Google Workspace، والتي ستعرضها في طريقة العرض "كل التعليقات".
لا تظهر التعليقات غير المثبَّتة على ملفات PDF التي يتم عرضها في أداة معاينة ملفات Drive، على الرغم من حفظها وإمكانية استردادها من خلال Drive API.

إضافة تعليق مثبَّت إلى أحدث مراجعة لمستند

عند إضافة تعليق، قد تريد تثبيته في منطقة معيّنة في الملف. يحدّد الرابط منطقة في ملف يشير إليها تعليق. يحدّد المورد comments الحقل anchor كسلسلة JSON.

لإضافة تعليق مثبَّت:

(اختياريّ): استدعِ طريقة list في مورد revisions لعرض كل revisionID لمستند. اتّبِع هذه الخطوة فقط إذا كنت تريد تثبيت تعليق في أي مراجعة غير أحدث مراجعة. إذا كنت تريد استخدام أحدث مراجعة، استخدِم head لـ revisionID.
استدعِ طريقة 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."
}

حلّ تعليق

لا يمكن حلّ تعليق إلا من خلال نشر ردّ عليه.

لحلّ تعليق، استخدِم الـ create طريقة في مورد الـ replies مع المَعلمتَين fileId و commentId.

يستخدم نص الطلب الحقل action لحلّ التعليق. يمكنك أيضًا ضبط الحقل content لإضافة ردّ يغلق التعليق.

عند حلّ تعليق، يضع Drive علامة resolved: true على مورد comments. على عكس التعليقات المحذوفة، يمكن أن تتضمّن التعليقات التي تم حلّها الحقلَين 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."
}

الحصول على تعليق

للحصول على تعليق في ملف، استخدِم الـ get طريقة في مورد الـ comments مع المَعلمتَين fileId وcommentId. إذا كنت لا تعرف رقم تعريف التعليق، يمكنك عرض كل التعليقات باستخدام طريقة list.

تعرض الطريقة نموذجًا لمورد comments.

لتضمين التعليقات المحذوفة في النتائج، اضبط مَعلمة طلب البحث includedDeleted query على 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)

تعديل تعليق

لتعديل تعليق في ملف، استخدِم الـ 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."
}

حذف تعليق

لحذف تعليق في ملف، استخدِم الـ 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

إضافة ردّ على تعليق

حلّ تعليق

الحصول على تعليق

عرض قائمة بالتعليقات

تعديل تعليق

حذف تعليق

مواضيع ذات صلة

إدارة التعليقات والردود