تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

يتم فرض القيود التالية عند العمل باستخدام التعليقات المرتبطة بموضع والتعليقات غير المرتبطة بموضع باستخدام 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 علامة 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."
}

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

للحصول على تعليق على ملف، استخدِم طريقة 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)

تعديل تعليق

لتعديل تعليق على ملف، استخدِم الطريقة 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

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

حلّ تعليق

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

عرض التعليقات

تعديل تعليق

حذف تعليق

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

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