إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
في Azure AI Search، يستدعي simple استعلام محلل الاستعلام الافتراضي للبحث في النص الكامل. المحلل سريع ويعالج السيناريوهات الشائعة، بما في ذلك البحث الكامل عن النص والبحث المصفى والواجهات والبحث عن البادئة. تستخدم هذه المقالة أمثلة لتوضيح استخدام بناء الجملة البسيط في طلب مستندات البحث (REST API).
إشعار
بناء جملة استعلام بديل هو Lucene، الذي يدعم بنيات استعلام أكثر تعقيدا، مثل البحث الغامض وأحرف البدل. لمزيد من المعلومات، راجع أمثلة على بناء جملة بحث Lucene الكامل .
فهرس عينة الفنادق
الاستعلامات التالية تعتمد على مؤشر الفنادق العينة، والذي يمكنك إنشاؤه باتباع التعليمات في Quickstart: البحث الكامل في Azure portal.
يتم توضيح أمثلة الاستعلامات باستخدام REST API وطلبات POST. يمكنك لصقها وتشغيلها في عميل REST. أو استخدم عرض JSON ل Search explorer في Azure portal. في طريقة عرض JSON، يمكنك اللصق في أمثلة الاستعلام الموضحة هنا في هذه المقالة.
يجب أن تحتوي رؤوس الطلبات على القيم التالية:
| المفتاح | قيمة |
|---|---|
| نوع المحتوى | تطبيق/json |
| مفتاح واجهة برمجة التطبيقات |
<your-search-service-api-key>، إما الاستعلام أو مفتاح المسؤول |
يجب أن تتضمن معلمات URI نقطة نهاية search service الخاصة بك مع اسم الفهرس، مجموعات المستندات، أمر البحث، وإصدار واجهة برمجة التطبيقات (API)، مشابه للمثال التالي:
https://{{service-name}}.search.windows.net/indexes/hotels-sample/docs/search?api-version=2025-09-01
يجب تشكيل نص الطلب ك JSON صالح:
{
"search": "*",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Tags, Description",
"count": true
}
searchتعيين إلى * هو استعلام غير محدد، مكافئ للبحث الفارغ أو الفارغ. إنه ليس مفيدا بشكل خاص، ولكنه أبسط بحث يمكنك القيام به، ويعرض جميع الحقول القابلة للاسترداد في الفهرس، مع جميع القيم.queryTypeتعيين إلى بسيط هو الافتراضي ويمكن حذفه، ولكن يتم تضمينه للتأكيد على أن أمثلة الاستعلام في هذه المقالة يتم التعبير عنها في بناء الجملة البسيط.selectيتم استخدام تعيين إلى قائمة الحقول المحددة بفاصلة لتكوين نتائج البحث، بما في ذلك الحقول المفيدة فقط في سياق نتائج البحث.countإرجاع عدد المستندات المطابقة لمعايير البحث. في سلسلة بحث فارغة، يكون العدد هو جميع المستندات في الفهرس (50 في مؤشر الفنادق العينة).
مثال 1: البحث الكامل عن النص
يمكن أن يكون البحث الكامل في النص أي عدد من المصطلحات المستقلة أو العبارات المحاطة باقتباس، مع عوامل التشغيل المنطقية أو بدونها.
POST /indexes/hotel-samples-index/docs/search?api-version=2025-09-01
{
"search": "pool spa +airport",
"searchMode": "any",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
تميل عملية البحث عن الكلمات الأساسية التي تتكون من مصطلحات أو عبارات مهمة إلى العمل على أفضل نحو. تخضع حقول السلسلة لتحليل النص أثناء الفهرسة والاستعلام، مع إسقاط كلمات غير أساسية مثلوو. لمعرفة كيفية رمز سلسلة استعلام في الفهرس، مرر السلسلة في استدعاء تحليل النص إلى الفهرس.
تتحكم المعلمة في searchMode الدقة والاستدعاء. إذا كنت تريد المزيد من الاستدعاء، فاستخدم القيمة الافتراضية أي قيمة، والتي ترجع نتيجة إذا تمت مطابقة أي جزء من سلسلة الاستعلام. إذا كنت تفضل الدقة، حيث يجب مطابقة جميع أجزاء السلسلة، فقم بالتغيير searchMode إلى الكل. جرب الاستعلام السابق كلتا الطريقتين لمعرفة كيفية تغيير searchMode للنتيجة.
يجب أن تبدو الاستجابة لاستعلام تجمع spa +airport مشابهة للمثال التالي.
"@odata.count": 4,
"value": [
{
"@search.score": 6.090657,
"HotelId": "12",
"HotelName": "Winter Panorama Resort",
"Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs.",
"Category": "Resort and Spa"
},
{
"@search.score": 4.314683,
"HotelId": "21",
"HotelName": "Good Business Hotel",
"Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area.",
"Category": "Suite"
},
{
"@search.score": 3.575948,
"HotelId": "27",
"HotelName": "Starlight Suites",
"Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
"Category": "Suite"
},
{
"@search.score": 2.6926985,
"HotelId": "25",
"HotelName": "Waterfront Scottish Inn",
"Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
"Category": "Suite"
}
]
لاحظ درجة البحث في الاستجابة. هذه هي درجة الصلة للمباراة. افتراضيا، تعيد search service أفضل 50 مطابقة بناء على هذه النتيجة.
تحدث درجات منتظمة من 1.0 عندما لا يكون هناك رتبة، إما لأن البحث لم يكن بحث النص الكامل، أو لأنه لم يتم توفير معايير. على سبيل المثال، في بحث فارغ (search=*)، تعود الصفوف بترتيب عشوائي. عند تضمين معايير فعلية، سترى أن درجات البحث تتطور إلى قيم ذات معنى.
مثال 2: البحث حسب المعرف
بعد إرجاع نتائج البحث، تكون الخطوة المنطقية التالية هي توفير صفحة تفاصيل تتضمن المزيد من الحقول من المستند. يوضح لك هذا المثال كيفية إرجاع مستند واحد باستخدام الحصول على مستند عن طريق تمرير معرف المستند.
GET /indexes/hotels-sample/docs/41?api-version=2025-09-01
تحتوي جميع المستندات على معرف فريد. إذا كنت تستخدم Azure portal، اختر الفهرس من تبويب Indexes ثم انظر إلى تعريفات الحقول لتحديد أي حقل هو المفتاح. في واجهة برمجة تطبيقات REST، يقوم استدعاء GET Index بإرجاع تعريف الفهرس في نص الاستجابة.
تتكون استجابة الاستعلام السابق من المستند الذي يكون مفتاحه 41. يمكن إرجاع أي حقل تم وضع علامة عليه على أنه قابل للاسترداد في تعريف الفهرس في نتائج البحث وعرضه في تطبيقك.
{
"HotelId": "41",
"HotelName": "Windy Ocean Motel",
"Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
"Description_fr": "Cet hôtel en bord de mer donnant sur la plage propose des chambres dotées d'un balcon privé et de 2 piscines intérieure et extérieure. Inspiré par la beauté naturelle de l'île, chaque chambre comprend une peinture originale de scènes locales par le propriétaire. Les chambres comprennent un mini-réfrigérateur, une cafetière Keurig et une télévision à écran plat. Divers magasins et divertissements artistiques se trouvent sur la promenade, à quelques pas.",
"Category": "Suite",
"Tags": [
"pool",
"air conditioning",
"bar"
],
"ParkingIncluded": true,
"LastRenovationDate": "2021-05-10T00:00:00Z",
"Rating": 3.5,
"Location": {
"type": "Point",
"coordinates": [
-157.846817,
21.295841
],
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
}
},
"Address": {
"StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
"City": "Honolulu",
"StateProvince": "HI",
"PostalCode": "96814",
"Country": "USA"
}
}
مثال 3: تصفية النص
بناء جملة عامل التصفية هو تعبير OData يمكنك استخدامه بمفرده أو مع search. عند استخدامها معا في نفس الطلب، filter يتم تطبيقها أولا على الفهرس بأكمله، ثم search يتم تنفيذ على نتائج عامل التصفية. لذلك يمكن أن تكون عوامل التصفية تقنية مفيدة لتحسين أداء الاستعلام لأنها تقلل من مجموعة المستندات التي يحتاج استعلام البحث إلى معالجتها.
يمكن تعريف عوامل التصفية على أي حقل تم وضع علامة عليه ك filterable في تعريف الفهرس. بالنسبة لفهرس عينات الفنادق، تشمل الحقول القابلة للتصفية الفئة، العلامات، ParkingIncluded، Rating، ومعظم حقول العنوان .
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "art tours",
"queryType": "simple",
"filter": "Category eq 'Boutique'",
"searchFields": "HotelName,Description,Category",
"select": "HotelId,HotelName,Description,Category",
"count": true
}
يتم تحديد نطاق الاستجابة للاستعلام السابق فقط لتلك الفنادق المصنفة على أنها بوتيك، والتي تتضمن المصطلحات الفنية أو الجولات. في هذه الحالة، هناك تطابق واحد فقط.
"value": [
{
"@search.score": 1.2814453,
"HotelId": "2",
"HotelName": "Old Century Hotel",
"Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
"Category": "Boutique"
}
]
مثال 4: دالات التصفية
يمكن أن تتضمن تعبيرات التصفية وظائف search.ismatch و search.ismatchscoring، مما يسمح لك بإنشاء استعلام بحث داخل عامل التصفية. يستخدم تعبير عامل التصفية هذا حرف بدل مجانا لتحديد وسائل الراحة بما في ذلك شبكة wifi المجانية ومواقف السيارات المجانية وما إلى ذلك.
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "",
"filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
"select": "HotelName, Tags, Description",
"count": true
}
تتطابق الاستجابة للاستعلام السابق مع 27 فندقا توفر وسائل راحة مجانية. لاحظ أن درجة البحث هي 1 موحدة في جميع أنحاء النتائج. وذلك لأن تعبير البحث فارغ أو خال، مما يؤدي إلى تطابق عامل تصفية حرفي، ولكن لا يوجد بحث نصي كامل. يتم إرجاع درجات الصلة فقط في البحث عن النص الكامل. إذا كنت تستخدم عوامل تصفية بدون search، فتأكد من أن لديك حقولا كافية قابلة للفرز بحيث يمكنك التحكم في ترتيب البحث.
"@odata.count": 27,
"value": [
{
"@search.score": 1,
"HotelName": "Country Residence Hotel",
"Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door.",
"Tags": [
"laundry service",
"restaurant",
"free parking"
]
},
{
"@search.score": 1,
"HotelName": "Downtown Mix Hotel",
"Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
"Tags": [
"air conditioning",
"laundry service",
"free wifi"
]
},
{
"@search.score": 1,
"HotelName": "Starlight Suites",
"Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
"Tags": [
"pool",
"coffee in lobby",
"free wifi"
]
},
. . .
مثال 5: عوامل تصفية النطاق
يتم دعم تصفية النطاق من خلال تعبيرات عوامل التصفية لأي نوع بيانات. توضح الأمثلة التالية النطاقات الرقمية والسلسلة. تعد أنواع البيانات مهمة في عوامل تصفية النطاق وتعمل على أفضل نحو عندما تكون البيانات الرقمية في حقول رقمية، وبيانات السلسلة في حقول السلسلة. البيانات الرقمية في حقول السلسلة غير مناسبة للنطاقات لأن السلاسل الرقمية غير قابلة للمقارنة.
الاستعلام التالي هو نطاق رقمي. في مؤشر العينة للفندق، الحقل العددي الوحيد القابل للتصفية هو Rating.
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "*",
"filter": "Rating ge 2 and Rating lt 4",
"select": "HotelId, HotelName, Rating",
"orderby": "Rating desc",
"count": true
}
يجب أن تبدو الاستجابة لهذا الاستعلام مشابهة للمثال التالي، مقتسمة للإيجاز.
"@odata.count": 27,
"value": [
{
"@search.score": 1,
"HotelId": "22",
"HotelName": "Lion's Den Inn",
"Rating": 3.9
},
{
"@search.score": 1,
"HotelId": "25",
"HotelName": "Waterfront Scottish Inn",
"Rating": 3.8
},
{
"@search.score": 1,
"HotelId": "2",
"HotelName": "Old Century Hotel",
"Rating": 3.6
},
...
الاستعلام التالي هو عامل تصفية نطاق عبر حقل سلسلة (Address/StateProvince):
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "*",
"filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
"select": "HotelId, HotelName, Address/StateProvince",
"count": true
}
يجب أن تبدو الاستجابة لهذا الاستعلام مشابهة للمثال التالي، مقتسمة للإيجاز. في هذا المثال، لا يمكن الفرز حسب StateProvince لأنه لا يتم إسناد الحقل على أنه قابل للفرز في تعريف الفهرس.
{
"@odata.count": 9,
"value": [
{
"@search.score": 1,
"HotelId": "39",
"HotelName": "White Mountain Lodge & Suites",
"Address": {
"StateProvince": "CO"
}
},
{
"@search.score": 1,
"HotelId": "9",
"HotelName": "Smile Up Hotel",
"Address": {
"StateProvince": "CA "
}
},
{
"@search.score": 1,
"HotelId": "7",
"HotelName": "Roach Motel",
"Address": {
"StateProvince": "CA "
}
},
{
"@search.score": 1,
"HotelId": "34",
"HotelName": "Lakefront Captain Inn",
"Address": {
"StateProvince": "CT"
}
},
{
"@search.score": 1,
"HotelId": "37",
"HotelName": "Campus Commander Hotel",
"Address": {
"StateProvince": "CA "
}
},
. . .
مثال 6: البحث الجيوفضائي
يتضمن مؤشر عينات الفنادق حقل الموقع مع إحداثيات خطوط العرض والطول. يستخدم هذا المثال الدالة geo.distance التي تقوم بالتصفية على المستندات ضمن محيط نقطة البداية، إلى مسافة عشوائية (بالكيلومترات) التي توفرها. يمكنك تعديل القيمة الأخيرة في الاستعلام (10) لتقليل أو تكبير مساحة surface الاستعلام.
POST /indexes/v/docs/search?api-version=2025-09-01
{
"search": "*",
"filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
"select": "HotelId, HotelName, Address/City, Address/StateProvince",
"count": true
}
ترجع الاستجابة لهذا الاستعلام جميع الفنادق ضمن مسافة 10 كيلومترات من الإحداثيات المقدمة:
{
"@odata.count": 3,
"value": [
{
"@search.score": 1,
"HotelId": "45",
"HotelName": "Happy Lake Resort & Restaurant",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
},
{
"@search.score": 1,
"HotelId": "24",
"HotelName": "Uptown Chic Hotel",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
},
{
"@search.score": 1,
"HotelId": "16",
"HotelName": "Double Sanctuary Resort",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
}
]
}
مثال 7: القيم المنطقية مع searchMode
يدعم بناء الجملة البسيط عوامل التشغيل المنطقية في شكل أحرف (+, -, |) لدعم منطق الاستعلام AND وOR وNOT. يعمل البحث المنطقي كما قد تتوقع، مع بعض الاستثناءات الجديرة بالملاحظة.
في البحث المنطقي، ضع في اعتبارك إضافة المعلمة searchMode كآلية للتأثير على الدقة والاسترجاع. تتضمن "searchMode": "any" القيم الصالحة تفضيل الاستدعاء (يعتبر المستند الذي يفي بأي من المعايير مطابقا)، وتفضيل "searchMode": "all" الدقة (يجب مطابقة جميع المعايير في مستند).
في سياق البحث المنطقي، يمكن أن يكون الإعداد الافتراضي "searchMode": "any" مربكا إذا كنت تقوم بتكديس استعلام مع عوامل تشغيل متعددة والحصول على نتائج أوسع بدلا من نتائج أضيق. هذا صحيح بشكل خاص مع NOT، حيث تتضمن النتائج جميع المستندات التي لا تحتوي على مصطلح أو عبارة معينة.
يوفر المثال التالي رسما توضيحيا. يبحث الاستعلام عن التطابقات في المطعم التي تستبعد عبارة تكييف الهواء. إذا قمت بتشغيل الاستعلام التالي باستخدام searchMode (أي)، يتم إرجاع 43 مستندا: تلك التي تحتوي على مصطلح مطعم، بالإضافة إلى جميع المستندات التي لا تحتوي على العبارة *تكييف الهواء.
لاحظ أنه لا توجد مسافة بين عامل التشغيل المنطقي (-) وتكييف هواء العبارة. يتم إلغاء علامات الاقتباس (\").
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "restaurant -\"air conditioning\"",
"searchMode": "any",
"searchFields": "Tags",
"select": "HotelId, HotelName, Tags",
"count": true
}
يؤدي التغيير إلى "searchMode": "all" فرض تأثير تراكمي على المعايير وإرجاع مجموعة نتائج أصغر (سبع تطابقات) تتكون من مستندات تحتوي على مصطلح مطعم، مطروحا منها تلك التي تحتوي على عبارة تكييف الهواء.
ستبدو الاستجابة لهذا الاستعلام الآن مشابهة للمثال التالي، مقتسمة للإيجاز.
{
"@odata.count": 14,
"value": [
{
"@search.score": 3.1383743,
"HotelId": "18",
"HotelName": "Ocean Water Resort & Spa",
"Tags": [
"view",
"pool",
"restaurant"
]
},
{
"@search.score": 2.028083,
"HotelId": "22",
"HotelName": "Lion's Den Inn",
"Tags": [
"laundry service",
"free wifi",
"restaurant"
]
},
{
"@search.score": 2.028083,
"HotelId": "34",
"HotelName": "Lakefront Captain Inn",
"Tags": [
"restaurant",
"laundry service",
"coffee in lobby"
]
},
...
مثال 8: نتائج الترحيل
في الأمثلة السابقة، تعرفت على المعلمات التي تؤثر على تكوين نتائج البحث، بما في ذلك select التي تحدد الحقول الموجودة في نتيجة، وأوامر الفرز، وكيفية تضمين عدد جميع التطابقات. هذا المثال هو استمرار لتكوين نتيجة البحث في شكل معلمات ترحيل الصفحات التي تسمح لك بتجميع عدد النتائج التي تظهر في أي صفحة معينة.
افتراضيا، تعيد search service أفضل 50 مطابقة. للتحكم في عدد التطابقات في كل صفحة، استخدم top لتحديد حجم الدفعة، ثم استخدم skip لالتقاط الدفعات اللاحقة.
يستخدم المثال التالي ترتيب تصفية وفرز على Rating الحقل (التصنيف قابل للتصفية وقابل للفرز) لأنه من الأسهل رؤية تأثيرات الترحيل على النتائج التي تم فرزها. في استعلام بحث كامل عادي، يتم ترتيب أفضل التطابقات وصفحة حسب @search.score.
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "*",
"filter": "Rating gt 4",
"select": "HotelName, Rating",
"orderby": "Rating desc",
"top": 5,
"count": true
}
يبحث الاستعلام عن 21 مستندا متطابقا، ولكن لأنك حددت top، ترجع الاستجابة أفضل خمس تطابقات فقط، مع بدء التصنيفات عند 4.9، وتنتهي عند 4.7 مع Lakeside B وB.
للحصول على الخمسة التالية، تخطي الدفعة الأولى:
POST /indexes/hotels-sample/docs/search?api-version=2025-09-01
{
"search": "*",
"filter": "Rating gt 4",
"select": "HotelName, Rating",
"orderby": "Rating desc",
"top": 5,
"skip": 5,
"count": true
}
تتخطى الاستجابة للدفعة الثانية أول خمس مباريات، مع إرجاع الخمسة التالية، بدءا من Pull'r Inn موتيل. لمتابعة المزيد من الدفعات، يمكنك الاحتفاظ top بخمسة، ثم زيادة skip بمقدار خمسة على كل طلب جديد (skip=5، skip=10، skip=15، وما إلى ذلك).
{
"@odata.count": 21,
"value": [
{
"@search.score": 1,
"HotelName": "Head Wind Resort",
"Rating": 4.7
},
{
"@search.score": 1,
"HotelName": "Sublime Palace Hotel",
"Rating": 4.6
},
{
"@search.score": 1,
"HotelName": "City Skyline Antiquity Hotel",
"Rating": 4.5
},
{
"@search.score": 1,
"HotelName": "Nordick's Valley Motel",
"Rating": 4.5
},
{
"@search.score": 1,
"HotelName": "Winter Panorama Resort",
"Rating": 4.5
}
]
}
المحتوى ذو الصلة
الآن بعد أن أصبح لديك بعض الممارسات باستخدام بناء جملة الاستعلام الأساسي، حاول تحديد الاستعلامات في التعليمات البرمجية. الرابط التالي يغطي كيفية إعداد استعلامات البحث باستخدام Azure SDKs.
يمكن العثور على مزيد من مرجع بناء الجملة وبنية الاستعلام والأمثلة في الارتباطات التالية: