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

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

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

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

بالنسبة إلى جميع الطرق (باستثناء delete) في موارد comments، يجب ضبط fields مَعلمة system لتحديد الحقول التي سيتم عرضها في الاستجابة. في معظم methods في 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.

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

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