التعليقات هي ملاحظات يقدّمها المستخدم بشأن ملف معيّن، مثل قارئ ملف معالجة ملف نصي يقترح كيفية إعادة صياغة جملة. هناك نوعان من التعليقات: التعليقات المرتبطة والتعليقات غير المرتبطة. يكون التعليق المرتبط بمكان معيّن مرتبطًا بموقع معيّن، مثل جملة في مستند معالجة ملف نصي، ضمن إصدار معيّن من المستند. في المقابل، يكون التعليق غير المرتبط بكلمة مرتبطًا بالمستند فقط.
يتم إرفاق الردود بالتعليقات، وهي تمثّل ردّ المستخدم على التعليق. تتيح واجهة برمجة التطبيقات Drive API للمستخدمين إضافة تعليقات وردود على المستندات التي أنشأها تطبيقك. ويُعرف التعليق الذي يتضمّن ردودًا باسم مناقشة.
يجب ضبط المَعلمة fields لتضمين الحقول التي سيتم عرضها في
الاستجابة عند استدعاء كل طريقة مُدرَجة في موارد
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) و
region (a). وregion (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 لتعديل التعليق.
تُرجع الطريقة الحقول المدرَجة في مَعلمة طلب البحث 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