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

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

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

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

إضافة تعليق غير مرتبط بموضع

لإضافة تعليق غير مرتبط بعنصر إلى مستند، استدعِ طريقة create مع المَعلمة fileId ومورد comments يحتوي على التعليق.

يتم إدراج التعليق كنص عادي، ولكن يتضمّن نص الردّ الحقل htmlContent الذي يحتوي على محتوى منسَّق للعرض.

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

لإضافة ردّ على تعليق، استخدِم طريقة replies.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."
}

حلّ تعليق

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

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

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

عند حلّ تعليق، يضع Drive علامة 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."
}

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

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

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

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

  2. استدعِ طريقة create مع المَعلمة fileID، وهي مصدر comments يحتوي على التعليق، وسلسلة مرساة JSON تحتوي على revisionID (r) والمنطقة (a).

تعتمد طريقة تحديد المنطقة على نوع محتوى المستند الذي تعمل عليه. لمزيد من المعلومات، يُرجى الرجوع إلى مقالة تحديد منطقة.

تحديد منطقة

كما ذكرنا سابقًا، تحتوي سلسلة الربط في 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 أو بمعرّف مراجعة معيّنة.

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

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