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

الخلاصة

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

مقدمة

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

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

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

بحلول نهاية هذا الدليل، ستكون قادرًا على:

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

البدء

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

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

# Or download from elastic.co

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

curl -X GET "http://localhost:9200"

الاستجابة:

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

المصادقة

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

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

أو استخدم مفاتيح 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" }
      }
    }
  }'

فهرسة مستند

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"
  }'

الاستجابة:

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

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

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

تحديث مستند

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"
  }'

حذف مستند

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

عمليات مجمعة

فهرسة مستندات متعددة بكفاءة:

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}
'

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

بحث أساسي

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

استعلامات Bool

دمج شروط متعددة:

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

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

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

تحصل أسماء الحقول التي تحتوي على ^2 على وزن مضاعف في التقييم.

بحث العبارات

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

{
  "query": {
    "match_phrase": {
      "description": "noise canceling"
    }
  }
}

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

{
  "query": {
    "wildcard": {
      "name": "*headphone*"
    }
  }
}

الفرز

{
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "_score": "desc" }
  ]
}

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

{
  "from": 20,
  "size": 10,
  "query": { "match_all": {} }
}

التجميعات

تحسب التجميعات الإحصائيات الموجزة لبياناتك.

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

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" } }
        }
      }
    }
  }'

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

{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "price",
        "interval": 25
      }
    }
  }
}

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

{
  "size": 0,
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}

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

{
  "size": 0,
  "aggs": {
    "unique_categories": {
      "cardinality": { "field": "category" }
    }
  }
}

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

أنواع الحقول

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

لمعالجة النصوص المتخصصة:

{
  "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"
      }
    }
  }
}

إدارة الكتلة

صحة الكتلة

curl -X GET "http://localhost:9200/_cluster/health"

الاستجابة:

{
  "cluster_name": "elasticsearch",
  "status": "green",
  "number_of_nodes": 3,
  "active_primary_shards": 25
}

الحالات:

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

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

curl -X GET "http://localhost:9200/_cat/indices?v"

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

curl -X GET "http://localhost:9200/_nodes/stats"

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

curl -X POST "http://localhost:9200/_cache/clear"

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

يمكن أن تكون استعلامات Elasticsearch معقدة. اختبرها بدقة.

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

قم بتخزين قوالب البحث في Apidog:

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

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
})

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

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

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

403 ممنوع (Forbidden)

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

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

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

السبب: الفهرس غير موجود.

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

circuit_breaking_exception

السبب: يستخدم الاستعلام ذاكرة كبيرة جدًا.

الإصلاح: قلل معامل size، وبسّط الاستعلامات، وأضف عوامل تصفية لتقليل مجموعة النتائج.

search_phase_execution_exception

السبب: خطأ في بناء جملة الاستعلام.

الإصلاح: تحقق من ملف JSON الخاص بك. المشاكل الشائعة: علامات اقتباس مفقودة، مسارات حقول غير صحيحة.

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

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

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

البحث في التجارة الإلكترونية. يقوم موقع بيع بالتجزئة بفهرسة 100,000 منتج. يبحث المستخدمون بالاسم والوصف والفئة والنطاق السعري. يقترح الإكمال التلقائي المنتجات أثناء الكتابة. تقوم عوامل التصفية بتضييق النتائج حسب الفئة والتوافر.

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

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

ختامًا

إليك ما تعلمته:

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

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

1. تشغيل Elasticsearch محليًا
2. إنشاء فهرس مع التعيينات
3. فهرسة بعض المستندات التجريبية
4. كتابة استعلامات البحث
5. تجربة التجميعات

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

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

ما الفرق بين Elasticsearch و Solr؟كلاهما محركات بحث تعتمد على Lucene. يتميز Elasticsearch بتصميم موزع أفضل وواجهات برمجة تطبيقات أفضل. يحتوي Solr على المزيد من ميزات المؤسسات. تختار معظم المشاريع الجديدة Elasticsearch.

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

ما هو الجزء (shard)؟الأجزاء هي قطع من الفهرس. كل جزء هو فهرس Lucene. الأجزاء الأساسية مخصصة للكتابة، والأجزاء المنسوخة هي نسخ للتوسع في القراءة والتسامح مع الأخطاء.

كم عدد الأجزاء التي يجب أن أنشئها؟قاعدة عامة: 20-50 جيجابايت لكل جزء. ابدأ بجزء أساسي واحد، ثم أضف نسخًا متماثلة. قم بزيادة الأجزاء الأساسية فقط عند الحاجة (لا يمكن تقليلها).

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

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

كيف أتعامل مع البيانات المستندة إلى الوقت؟استخدم فهارس تعتمد على التاريخ: logs-2026.03.24. يتيح لك ذلك حذف البيانات القديمة عن طريق إسقاط الفهارس ويحسن أداء الاستعلام عن طريق البحث في عدد أقل من الفهارس.