DEV Community

Cover image for كيفية استخدام واجهات برمجة تطبيقات Elasticsearch؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام واجهات برمجة تطبيقات Elasticsearch؟

#backend #api #tutorial #database

الخلاصة

واجهات برمجة التطبيقات (APIs) لـ Elasticsearch تدعم البحث والتحليلات على نطاق واسع. يمكنك فهرسة المستندات بصيغة JSON، والاستعلام باستخدام لغة استعلام قوية (DSL)، وتجميع النتائج للتحليلات. المصادقة تتم عبر مفاتيح API أو المصادقة الأساسية. لاختبار الاستعلامات والتعيينات والتجميعات قبل النشر في الإنتاج، استخدم Apidog.

جرِّب Apidog اليوم

مقدمة

Elasticsearch هو محرك بحث وتحليلات موزع يدعم النصوص المهيكلة والسجلات والمقاييس وغير ذلك. يُستخدم في البحث النصي الكامل في التطبيقات، وتحليل السجلات، ولوحات المعلومات التحليلية في الوقت الفعلي.

يوجد Elasticsearch في قلب مكدس ELK (Elasticsearch, Logstash, Kibana)، ويمكن استخدامه مباشرةً عبر API بدون Logstash.

💡 إذا كنت تطوّر ميزات بحث أو تحليلات سجلات، يسهّل عليك Apidog اختبار الاستعلامات، التحقق من التعيينات، وتصحيح التجميعات. يمكنك أيضًا حفظ ومشاركة قوالب البحث مع فريقك.

اختبر واجهات برمجة تطبيقات Elasticsearch باستخدام Apidog - مجانًا

بنهاية هذا الدليل ستتمكن من:

  • فهرسة وإدارة المستندات
  • كتابة استعلامات البحث باستخدام لغة استعلام Elasticsearch (DSL)
  • استخدام التجميعات للتحليلات
  • تكوين التعيينات والمحللات
  • مراقبة صحة الكتلة

البدء

تشغيل Elasticsearch محليًا 

# Docker
docker run -p 9200:9200 \
  -e "discovery.type=single-node" \
  elasticsearch:8.11.0

# أو حمله من elastic.co
Enter fullscreen mode Exit fullscreen mode

التحقق من التثبيت 

curl -X GET "http://localhost:9200"
Enter fullscreen mode Exit fullscreen mode

الاستجابة المتوقعة:

{
  "name": "elasticsearch-1",
  "cluster_name": "elasticsearch",
  "cluster_uuid": "abc123",
  "version": {
    "number": "8.11.0",
    "build_flavor": "default"
  },
  "tagline": "You know, for search"
}
Enter fullscreen mode Exit fullscreen mode

المصادقة

بدءًا من Elasticsearch 8.x، يُطلب المصادقة افتراضيًا:

curl -X GET "http://localhost:9200/_cluster/health" \
  -u elastic:your_password
Enter fullscreen mode Exit fullscreen mode

أو استخدم مفاتيح API (أنشئها من Kibana أو عبر API).

الفهارس والمستندات

إنشاء فهرس

اضبط إعدادات الفهرس والتعيينات عبر الأمر التالي:

curl -X PUT "http://localhost:9200/products" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "name": { "type": "text" },
        "price": { "type": "float" },
        "category": { "type": "keyword" },
        "in_stock": { "type": "boolean" },
        "created_at": { "type": "date" }
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

فهرسة مستند 

curl -X POST "http://localhost:9200/products/_doc" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones",
    "price": 79.99,
    "category": "electronics",
    "in_stock": true,
    "created_at": "2026-03-24T10:00:00Z"
  }'
Enter fullscreen mode Exit fullscreen mode

الاستجابة:

{
  "_index": "products",
  "_id": "abc123",
  "_version": 1,
  "result": "created",
  "_seq_no": 0,
  "_primary_term": 1
}
Enter fullscreen mode Exit fullscreen mode

الحصول على مستند 

curl -X GET "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password
Enter fullscreen mode Exit fullscreen mode

تحديث مستند 

curl -X PUT "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones Pro",
    "price": 99.99,
    "category": "electronics",
    "in_stock": true,
    "created_at": "2026-03-24T10:00:00Z"
  }'
Enter fullscreen mode Exit fullscreen mode

حذف مستند 

curl -X DELETE "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password
Enter fullscreen mode Exit fullscreen mode

عمليات مجمعة

فهرسة عدة مستندات دفعة واحدة:

curl -X POST "http://localhost:9200/products/_bulk" \
  -u elastic:your_password \
  -H "Content-Type: application/x-ndjson" \
  -d '{"index":{"_id":"1"}}
{"name":"Product A","price":10.99,"category":"books","in_stock":true}
{"index":{"_id":"2"}}
{"name":"Product B","price":20.99,"category":"electronics","in_stock":false}
'
Enter fullscreen mode Exit fullscreen mode

استعلامات البحث

بحث أساسي 

curl -X GET "http://localhost:9200/products/_search" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "name": "headphones"
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

استعلامات Bool

ادمج شروط متعددة عبر الاستعلامات المركبة:

{
  "query": {
    "bool": {
      "must": [
        { "match": { "name": "headphones" } }
      ],
      "filter": [
        { "term": { "category": "electronics" } },
        { "range": { "price": { "lte": 100 } } },
        { "term": { "in_stock": true } }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

بحث بالنص الكامل مع التقييم 

{
  "query": {
    "multi_match": {
      "query": "wireless audio headphones",
      "fields": ["name^2", "description"],
      "type": "best_fields",
      "fuzziness": "AUTO"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

لاحظ: الحقول مثل name^2 تحصل على وزن أعلى في التقييم.

بحث العبارات

للعثور على عبارات مطابقة بدقة:

{
  "query": {
    "match_phrase": {
      "description": "noise canceling"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

البحث بالحروف البديلة والتعبيرات العادية 

{
  "query": {
    "wildcard": {
      "name": "*headphone*"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

الفرز 

{
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "_score": "desc" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

التقسيم إلى صفحات 

{
  "from": 20,
  "size": 10,
  "query": { "match_all": {} }
}
Enter fullscreen mode Exit fullscreen mode

التجميعات

التجميعات تستخدم للحصول على إحصائيات سريعة حول بياناتك.

متوسط السعر حسب الفئة 

curl -X GET "http://localhost:9200/products/_search" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "aggs": {
      "by_category": {
        "terms": { "field": "category" },
        "aggs": {
          "avg_price": { "avg": { "field": "price" } },
          "min_price": { "min": { "field": "price" } },
          "max_price": { "max": { "field": "price" } }
        }
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

مخطط بياني للأسعار 

{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "price",
        "interval": 25
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

مخططات بيانية زمنية 

{
  "size": 0,
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

العددية (العدد الفريد) 

{
  "size": 0,
  "aggs": {
    "unique_categories": {
      "cardinality": { "field": "category" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

التعيينات والمحللات

أنواع الحقول

النوع يستخدم لـ
text بحث بالنص الكامل، محلل
keyword قيم دقيقة، تصفية، فرز
integer, float الأرقام
boolean صحيح/خطأ
date التواريخ والأوقات
object كائنات JSON متداخلة
nested مصفوفات من الكائنات (تحافظ على العلاقات)
geo_point إحداثيات خط العرض/الطول

المحللات المخصصة

لإنشاء محلل نص مخصص (مثال: للإكمال التلقائي):

{
  "settings": {
    "analysis": {
      "analyzer": {
        "autocomplete": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "autocomplete_filter"]
        }
      },
      "filter": {
        "autocomplete_filter": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 20
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "autocomplete",
        "search_analyzer": "standard"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

إدارة الكتلة

صحة الكتلة 

curl -X GET "http://localhost:9200/_cluster/health"
Enter fullscreen mode Exit fullscreen mode

استجابة نموذجية:

{
  "cluster_name": "elasticsearch",
  "status": "green",
  "number_of_nodes": 3,
  "active_primary_shards": 25
}
Enter fullscreen mode Exit fullscreen mode

الحالات:

  • أخضر: جميع الأجزاء مخصصة
  • أصفر: نسخ متماثلة غير مخصصة (عادة عند وجود عقدة واحدة)
  • أحمر: أجزاء أساسية مفقودة

إحصائيات الفهرس 

curl -X GET "http://localhost:9200/_cat/indices?v"
Enter fullscreen mode Exit fullscreen mode

إحصائيات العقدة 

curl -X GET "http://localhost:9200/_nodes/stats"
Enter fullscreen mode Exit fullscreen mode

مسح ذاكرة التخزين المؤقت 

curl -X POST "http://localhost:9200/_cache/clear"
Enter fullscreen mode Exit fullscreen mode

الاختبار باستخدام Apidog

استعلامات Elasticsearch قد تصبح معقدة. استخدم Apidog لاختبارها وضمان صحتها.

اختبار استعلامات Elasticsearch في Apidog

1. حفظ الاستعلامات الشائعة

يمكنك تخزين قوالب البحث في Apidog مع متغيرات ديناميكية:

{
  "query": {
    "bool": {
      "must": [
        { "match": { "{{search_field}}": "{{search_term}}" } }
      ],
      "filter": [
        { "range": { "{{price_field}}": { "lte": "{{max_price}}" } } }
      ]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

2. التحقق من صحة الاستجابات

أضف اختبارات تلقائية لضمان صحة البيانات:

pm.test('Search returns results', () => {
  const response = pm.response.json()
  pm.expect(response.hits.total.value).to.be.above(0)
})

pm.test('Aggregations present', () => {
  const response = pm.response.json()
  pm.expect(response.aggregations).to.exist
})
Enter fullscreen mode Exit fullscreen mode

3. فصل البيئات

اضبط متغيرات البيئة لتسهيل التنقل بين بيئات التطوير والإنتاج:

# Local
ES_HOST: http://localhost:9200
ES_USER: elastic
ES_PASSWORD: your_password

# Production
ES_HOST: https://search.yourcompany.com
ES_API_KEY: prod_api_key
Enter fullscreen mode Exit fullscreen mode

اختبر واجهات برمجة تطبيقات Elasticsearch باستخدام Apidog - مجانًا

الأخطاء الشائعة والإصلاحات

403 ممنوع (Forbidden)

السبب: فشل المصادقة أو أذونات غير كافية.
الإصلاح: تحقق من بيانات الاعتماد أو الأذونات لمفتاح الـ API.

404 index_not_found_exception (فهرس غير موجود)

السبب: الفهرس غير موجود.
الإصلاح: أنشئ الفهرس أولاً أو فعّل الإنشاء التلقائي (غير موصى به للإنتاج).

circuit_breaking_exception

السبب: الاستعلام يستهلك ذاكرة مرتفعة.
الإصلاح: قلّل قيمة size، بسّط الاستعلامات، وأضف عوامل تصفية.

search_phase_execution_exception

السبب: خطأ في بناء جملة الاستعلام.
الإصلاح: راجع JSON بعناية (علامات اقتباس، مسارات حقول صحيحة).

البدائل والمقارنات

الميزة Elasticsearch OpenSearch Meilisearch Typesense
الإعداد مستضاف ذاتيًا مستضاف ذاتيًا ملف تنفيذي واحد ملف تنفيذي واحد
جودة البحث ممتازة جيدة ممتازة جيدة
منحنى التعلم صعب صعب سهل سهل
قابلية التوسع ممتازة ممتازة جيدة جيدة
عرض السحابة Elastic Cloud OpenSearch Serverless Meilisearch Cloud Typesense Cloud

Elasticsearch يمتلك أغلب الميزات وأكبر مجتمع. Meilisearch وTypesense أبسط للبحث الأساسي.

حالات الاستخدام في العالم الحقيقي

البحث في التجارة الإلكترونية: متجر يضم 100,000 منتج، يدعم البحث بالاسم والوصف والفئة والسعر، مع إكمال تلقائي وتصفية النتائج.

سجلات التطبيق: شحن السجلات إلى Elasticsearch عبر Filebeat، والبحث فيها حسب الخدمة والخطورة والزمن، مع لوحات معلومات للأخطاء والأداء.

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

ختامًا

تعلمت في هذا الدليل:

  • فهرسة المستندات بصيغة JSON
  • الاستعلام باستخدام لغة استعلام Elasticsearch (DSL)
  • استخدام التجميعات للتحليلات
  • تكوين التعيينات للبحث الأمثل
  • مراقبة صحة الكتلة

خطواتك التالية:

  1. شغّل Elasticsearch محليًا
  2. أنشئ فهرسًا مع التعيينات المطلوبة
  3. فهرس مستندات تجريبية
  4. اكتب استعلامات بحث
  5. جرّب التجميعات

اختبر واجهات برمجة تطبيقات Elasticsearch باستخدام Apidog - مجانًا

الأسئلة الشائعة

ما الفرق بين Elasticsearch و Solr؟

كلاهما محركات بحث مبنية على Lucene، لكن Elasticsearch يتميز بتوزيع أفضل وواجهات API أسهل. Solr يحتوي على ميزات مؤسساتية أكثر. غالبية المشاريع الجديدة تفضل Elasticsearch.

كيف أتعامل مع الأحرف الخاصة في البحث؟

استخدم الشرطة المائلة للخلف للهروب من الأحرف الخاصة: ()[]{}:^\"\+-!~*?| أو استخدم simple_query_string الأكثر مرونة.

ما هو الجزء (shard)؟

الجزء هو قسم من الفهرس، كل واحد هو فهرس Lucene مستقل. هناك أجزاء أساسية للكتابة وأجزاء منسوخة للقراءة وتحمل الخطأ.

كم عدد الأجزاء التي يجب إنشاؤها؟

قاعدة عامة: 20-50 جيجابايت لكل جزء. ابدأ بجزء أساسي واحد وأضف نسخًا متماثلة، وزد الأجزاء الأساسية فقط إذا استدعى الأمر.

هل يمكن تغيير التعيينات بعد الفهرسة؟

يمكنك إضافة حقول جديدة، لكن لتغيير نوع حقل موجود، يجب إعادة فهرسة البيانات. استخدم قوالب الفهرسة لإدارة التعيينات.

ما هو معامل _routing؟

يحدد إلى أي جزء يُكتب المستند استنادًا إلى قيمة حقل. الافتراضي هو _id. استخدمه إذا كانت الاستعلامات دائمًا تُصفى على حقل معين (مثلاً user_id) لتحسين الأداء.

كيف أتعامل مع البيانات الزمنية؟

استخدم فهارس حسب التاريخ مثل logs-2026.03.24، ما يسمح بحذف البيانات القديمة ويحسن أداء الاستعلامات الزمنية.

Top comments (0)