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

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

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

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

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

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

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

نوع التعليقات نوع الملف
مثبّتة
  • يمكن للمطوّرين تحديد تنسيقهم الخاص لمواصفات التثبيت.
  • يتم حفظ التثبيت وعرضه عند استرداد التعليق، ولكن تتعامل تطبيقات محرّر Google Workspace مع هذه التعليقات على أنّها تعليقات غير مثبّتة.
  • عند استرداد التعليقات على ملفات Google Workspace (مثل "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google") التي تم إنشاؤها في المحرّر، يحتوي حقل anchor على بيانات التثبيت الداخلية الخاصة بالمحرّر (مثل سلسلة JSON workbook-range في ملفات "جداول بيانات Google"). تتعامل Drive API مع هذه البيانات على أنّها غير شفافة ولا يمكنها حلّ مناطق المستند الداخلية أو إحداثيات الخلايا أو عناصر الشريحة. للعمل مع التعليقات المثبّتة مباشرةً على أنواع الملفات هذه، استخدِم واجهات برمجة التطبيقات الخاصة بها: Google Docs API، Google Sheets API، أو Google Slides API.
غير مثبّتة
  • تتوفّر هذه التعليقات في مستندات Google Workspace، التي تعرضها في طريقة العرض "كل التعليقات".
  • لا تظهر التعليقات غير المثبّتة على ملفات PDF التي يتم عرضها في أداة معاينة ملفات Drive، على الرغم من حفظها وإمكانية استردادها من خلال Drive API.

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

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

لإضافة تعليق مثبّت، اتّبِع الخطوات التالية:

  1. (اختياريّ): استدعِ طريقة list في مورد revisions لعرض كل revisionID لمستند. اتّبِع هذه الخطوة فقط إذا كنت تريد تثبيت تعليق في أي مراجعة غير أحدث مراجعة. إذا كنت تريد استخدام أحدث مراجعة، استخدِم head للسمة revisionID.

  2. استدعِ طريقة create في مورد comments باستخدام مَعلمة fileId ومورد comments يحتوي على التعليق وسلسلة تثبيت JSON تحدّدها أنت في تطبيقك.

تعرض عيّنة التعليمات البرمجية التالية كيفية إنشاء تعليق مثبّت:

Python

import json

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
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 in your application to anchor the comment to.
# Note: Google Workspace editor apps (such as Google Docs, Sheets, and
# Slides) treat comments created using the Drive API as unanchored
# comments. Custom anchors are intended for your own applications or
# custom file viewers.
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 with a custom application-defined anchor.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define a custom anchor specification for your application.
        # The Drive API stores the anchor as an opaque string. Your custom
        # application or file viewer can parse this JSON string to position
        # the comment in your UI.
        anchor_data = {
            'line': ANCHOR_LINE,
            'revision': 'head'
        }

        # The comment body. The 'anchor' field must be a serialized
        # JSON string.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': json.dumps(anchor_data)
        }

        # 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.discovery import build
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 file in Drive.

    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 method في الـ replies resource مع الـ fileId والـ commentId parameters. يستخدم نص الطلب حقل 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. على عكس التعليقات المحذوفة، يمكن أن تتضمّن التع101}ليقات التي تم حلّها الحقلَين 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.

لتضمين التعليقات المحذوفة في النتائج، اضبط includeDeleted مَعلمة طلب البحث على 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 parameters. يستخدم نص الطلب حقل 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