التعامل مع المقالات

نشرح في هذا المقال طريقة التعامل مع مقالات قاعدة المعرفة من عرض المقالات، وإنشاء مقالات جديدة في قاعدة المعرفة وتعديلها وترتيبها من خلال الواجهة البرمجية لزيتون.

لتطبيق الأمثلة، سنفترض وجود مركز مساعدة على النطاق example.com، ومفتاح الواجهة البرمجية لزيتون مخزن ضمن متغير TOKEN$ لاستخدامه في الطلبات المختلفة.

export TOKEN="YOUR_API_KEY"

عرض المقالات

لعرض كافة مقالات قاعدة المعرفة نرسل طلب GET إلى نقطة الوصول List all articles مع إمكانية تصفية المقالات المعروضة وترتيبها.

ولعرض محتوى مقال معين نرسل طلب GET إلى نقطة الوصول Retrieve an article مع تمرير الرقم التعريفي للمقال المطلوب في عنوان الطلب.

كافة المقالات

لعرض كافة المقالات الموجودة في مركز المساعدة، مع تحديد عدد المقالات المعروضة لتكون 20، نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/articles?limit=20" \
  -H "Authorization: Bearer @TOKEN"

مقال واحد

لعرض المقال رقم 1005 في مركز المساعدة نرسل الطلب التالي:

curl 'https://example.com/api/agent/v1/articles/1005' \
     -H 'Authorization: Bearer @TOKEN' \

أول خمس مقالات

للحصول على أول خمس مقالات ضمن قاعدة المعرفة نكتب التالي:

curl  "https://example.com/api/agent/v1/articles?after[sort]=0\
&before[sort]=6" \
  -H "Authorization: Bearer @TOKEN' \
  --globoff

مقالات وكيل معين

لعرض مقالات قاعدة المعرثقة التي أنشأها الوكيل رقم 1008 نكتب التالي:

curl "https://example.com/api/agent/v1/articles?agent_ids[]=1008" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

مقالات تتضمن كلمة معينة

لعرض المقالات التي تتضمن عناوينها كلمة معينة ولتكن How مثلًا نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/articles?query=How" \
  -H "Authorization: Bearer @TOKEN" \

مقالات مرتبة

لعرض المقالات المنشورة، مع ترتيبها من الأكثر مشاهدة إلى الأقل مشاهدة نكتب الطلب على النحو التالي:

curl  "https://example.com/api/agent/v1/articles?statuses[]=published&sort=views.desc&limit=20" \
  -H 'Authorization: Bearer @TOKEN' \
  --globoff

إنشاء مقالات

لإضافة مقال جديد إلى قاعدة المعرفة، نرسل طلب من نوع POST إلى نقطة الوصول Create an article مع تمرير بيانات المقال في جسم الطلب.

مقال واحد

لإنشاء مقال جديد في قاعدة المعرفة الخاصة نكتب الطلب على النحو التالي:

curl -X POST "https://example.com/api/agent/v1/articles" \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "من أين أحصل على تطبيق الشركة؟",
    "meta_keywords": "app,تطبيق",
    "meta_description": "طريقة تحميل وتثبيت التطبيق",
    "slug": "how-to-download-app",
    "sort": 0,
    "category_ids": [1007],
    "featured": true,
    "tags": ["تعليمي", "شائع"],
    "knowledgebase_id": 1004,
    "locale": "ar",
    "status": "published",
    "blocks": [
      {
        "content": "<p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">اتبع الخطوات التالية:</span></p><p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">الخطوة 1:</span></p><p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">الخطوة 2:</span></p><p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">الخطوة 3:</span></p>",
        "sort": 0
      },
      {
        "form_id": "1012",
        "sort": 1
      }
    ]
  }'

تعديل المقالات

لتعديل مقال معين فيقاعدة المعرفة نرسل طلب PUT لنقطة الوصول Update an article مع تمرير الرقم التعريفي للمقال المطلوب تعديله في عنوان الطلب والبيانات المطلوب تعديلها إضافة للبيانات الإجبارية في جسم الطلب.

ولتعديل عدة مقالات نرسل طلب PUT إلى نقطة الوصول Update articles مع تمرير الأرقام التعريفية للمقالات والبيانات الإجبارية والمطلوب تعديلها في جسم الطلب.

مقال واحد

لنجرب تعديل المقال رقم 1005 بتعديل ترتيب المقال ليصبح 2 وتعديل وسوم المقال بإزالة الوسم شائع منها وحذف نموذج التواصل من محتويات المقال، والإبقاء على المحتوى النصي فقط نكتب الطلب كما يلي:

curl -X PUT "https://example.com/api/agent/v1/articles/1005" \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "من أين أحصل على تطبيق الشركة؟",
    "slug": "how-to-download-app",
    "sort": 2,
    "category_ids": [1007],
    "tags": ["تعليمي"],
    "status": "published",
    "blocks": [
      {
        "id": 773,
        "content": "<p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">اتبع الخطوات التالية:</span></p><p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">الخطوة 1:</span></p><p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">الخطوة 2:</span></p><p class=\"editor__paragraph\" dir=\"rtl\" style=\"\"><span style=\"white-space: pre-wrap;\">الخطوة 3:</span></p>",
        "sort": 0
      }
    ]
  }'

عدة مقالات

لتعديل ثلاثة مقالات في مركز المساعدة لها الأرقام التعريفية 15 و 105 و 1005 بطلب واحد وضمها إلى تصنيف رقم 1007 نكتب التالي:

curl "https://example.com/api/agent/v1/articles" \
  -X PUT 
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "article_ids": [15, 105, 1005],
    "status": "published",
    "category_ids": [1007]
  }'

ترتيب المقالات

يمكننا إعادة ترتيب عدة مقالات قاعدة المعرفة من خلال إرسال طلب من النوع POST إلى نقطة الوصول Sort articles مع تمرير الرقم التعريفي لكل مقال مع ترتيبه في جسم الطلب، كما يمكننا تعديل ترتيب مقال محدد في قاعدة المعرفة بإرسال طلب POST لنقطة الوصول Sort an article مع تمرير رقم المقال المطلوب في عنوان الطلب وترتيبه في جسم الطلب.

مقال واحد

لتعديل ترتيب المقال رقم 1005 في مركز المساعدة ليكون في الموضع الرابع نكتب الطلب كما يلي:

curl "https://example.com/api/agent/v1/articles/1005/sort" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": 3
  }'

عدة مقالات

لترتيب مجموعة مقالات لها الأرقام التعريفية 15 و 105 و 1005 نكتب الطلب التالي:

curl -X POST "https://example.com/api/agent/v1/articles/bulk-sort" \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "articles": [
      {
        "id": 15,
        "sort": 0
      },
      {
        "id": 105,
        "sort": 1
      },
      {
        "id": 1005,
        "sort": 2
      }
    ]
  }'

حذف مقال

لحذف مقال معين من مركز المساعدة نرسل طلب DELETE إلى نقطة الوصول Delete an article مع تمرير الرقم التعريفي للمقال المُراد حذفه ضمن عنوان الطلب.

مقال واحد

لحذف المقال رقم 1005 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/articles/1005" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"