التشغيل السريع: البحث عن النص باستخدام REST
توفر واجهات برمجة تطبيقات REST في Azure الذكاء الاصطناعي Search وصولا برمجيا إلى جميع قدراتها، بما في ذلك ميزات المعاينة، وهي طريقة سهلة لمعرفة كيفية عمل الميزات. في هذا التشغيل السريع، تعرف على كيفية استدعاء واجهات برمجة تطبيقات البحث REST لإنشاء فهرس بحث وتحميله والاستعلام منه في Azure الذكاء الاصطناعي Search.
في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.
المتطلبات الأساسية
- Visual Studio Code مع عميل REST.
- Azure الذكاء الاصطناعي Search. إنشاء مورد Azure الذكاء الاصطناعي Search موجود أو العثور عليه ضمن اشتراكك الحالي. يمكنك استخدام خدمة مجانية لهذه البداية السريعة.
تحميل الملفات
قم بتنزيل نموذج REST من GitHub لإرسال الطلبات في هذا التشغيل السريع. لمزيد من المعلومات، راجع تنزيل الملفات من GitHub.
يمكنك أيضا بدء تشغيل ملف جديد على النظام المحلي وإنشاء الطلبات يدويا باستخدام الإرشادات الواردة في هذه المقالة.
نسخ مفتاح خدمة البحث وعنوان URL
تتطلب استدعاءات REST نقطة نهاية خدمة البحث ومفتاح API في كل طلب. يمكنك الحصول على هذه القيم من مدخل Microsoft Azure.
قم بتسجيل الدخول إلى بوابة Azure. ثم انتقل إلى صفحة نظرة عامة على خدمة البحث وانسخ عنوان URL. قد يبدو مثال نقطة النهاية بالشكل
https://mydemo.search.windows.net.حدد الإعدادات> Keys ثم انسخ مفتاح مسؤول. يتم استخدام مفاتيح مسؤول لإضافة الكائنات وتعديلها وحذفها. هناك مفتاحان للمسؤول قابلان للتبديل. انسخ أي منهما.
إعداد Visual Studio Code
إذا لم تكن على دراية بعميل REST ل Visual Studio Code، يتضمن هذا القسم الإعداد بحيث يمكنك إكمال المهام في هذا التشغيل السريع.
ابدأ تشغيل Visual Studio Code وحدد الإطار المتجانب Extensions.
ابحث عن عميل REST وحدد تثبيت.
افتح أو أنشئ ملفا جديدا باسم إما
.restبملحق ملف أو.http.الصق في المثال التالي. استبدل عنوان URL الأساسي ومفتاح API بالقيم التي نسختها سابقا.
@baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE @apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE ### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2023-11-01&$select=name HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}حدد إرسال طلب. يجب أن تظهر استجابة في جزء مجاور. إذا كان لديك فهارس موجودة، يتم سردها. وإلا، تكون القائمة فارغة. إذا كان رمز HTTP هو
200 OK، فأنت جاهز للخطوات التالية.
النقاط الرئيسية:
- يتم تحديد المعلمات باستخدام
@بادئة. ###تعيين مكالمة REST. يحتوي السطر التالي على الطلب، والذي يجب أن يتضمنHTTP/1.1.Send requestيجب أن يظهر أعلى الطلب.
- يتم تحديد المعلمات باستخدام
إنشاء فهرس
إضافة طلب ثان إلى ملفك .rest . ينشئ Create Index (REST) فهرس بحث وينشئ بنيات البيانات الفعلية على خدمة البحث.
الصق في المثال التالي لإنشاء الفهرس على
hotels-quickstartخدمة البحث.### Create a new index POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "name": "hotels-quickstart", "fields": [ {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true}, {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false}, {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"}, {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true}, {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true}, {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true}, {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true}, {"name": "Address", "type": "Edm.ComplexType", "fields": [ {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true}, {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true} ] } ] }حدد إرسال طلب. يجب أن يكون لديك استجابة
HTTP/1.1 201 Createdويجب أن يتضمن نص الاستجابة تمثيل JSON لمخطط الفهرس.إذا تلقيت خطأ
Header name must be a valid HTTP token ["{"]، فتأكد من وجود خط فارغ بينapi-keyنص الطلب. إذا حصلت على HTTP 504، فتحقق من أن عنوان URL يحدد HTTPS. إذا رأيت HTTP 400 أو 404، فتحقق من نص الطلب للتأكد من عدم وجود أخطاء في الصق والنسخ. يشير HTTP 403 عادة إلى وجود مشكلة في مفتاح API. إما أنه مفتاح غير صالح أو مشكلة في بناء الجملة مع كيفية تحديد مفتاح API.لديك الآن العديد من الطلبات في الملف الخاص بك. تذكر أن
###يبدأ طلب جديد ويتم تشغيل كل طلب بشكل مستقل.
حول تعريف الفهرس
ضمن مخطط الفهرس، تعرف مجموعة الحقول بنية المستند. يجب أن يحتوي كل مستند تقوم بتحميله على هذه الحقول. يجب تعيين كل حقل إلى نوع بيانات نموذج بيانات الكيان (EDM). يتم استخدام حقول السلسلة من أجل البحث عن النص الكامل. إذا كنت تريد أن تكون البيانات الرقمية قابلة للبحث، فتأكد من أن نوع البيانات هو Edm.String. أنواع البيانات الأخرى مثل Edm.Int32 قابلة للتصفية وقابلة للفرز وقابلة للاسترداد وقابلة للاسترداد ولكنها غير قابلة للبحث في النص الكامل.
تحدد السمات الموجودة في الحقل الإجراءات المسموح بها. تسمح واجهات برمجة تطبيقات REST بالعديد من الإجراءات بشكل افتراضي. على سبيل المثال، جميع السلاسل قابلة للبحث والاسترداد بشكل افتراضي. بالنسبة لواجهات برمجة تطبيقات REST، قد يكون لديك سمات فقط إذا كنت بحاجة إلى إيقاف تشغيل سلوك.
{
"name": "hotels-quickstart",
"fields": [
{"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
{"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
{"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
{"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
{"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
{"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
{"name": "Address", "type": "Edm.ComplexType",
"fields": [
{"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
{"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
{"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
]
}
]
}
تحميل المستندات
يعد إنشاء الفهرس وتحميله خطوات منفصلة. في Azure الذكاء الاصطناعي Search، يحتوي الفهرس على جميع البيانات والاستعلامات القابلة للبحث التي يتم تشغيلها على خدمة البحث. بالنسبة لمكالمات REST، يتم توفير البيانات كمستندات JSON. استخدام Documents- Index REST API لهذه المهمة.
تم توسيع URI ليشمل docs المجموعات والعملية index .
الصق في المثال التالي لتحميل مستندات JSON إلى فهرس البحث.
### Upload documents POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Secret Point Motel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Twin Dome Motel", "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.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Triple Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] }حدد إرسال طلب. في بضع ثوان، يجب أن تشاهد استجابة HTTP 201 في الجزء المجاور.
إذا حصلت على 207، فقد فشل مستند واحد على الأقل في التحميل. إذا حصلت على 404، فلديك خطأ في بناء الجملة إما في رأس الطلب أو نصه. تحقق من تغيير نقطة النهاية لتضمين
/docs/index.
تفعيل الاستعلامات
الآن بعد تحميل المستندات، يمكنك إصدار استعلامات مقابلها باستخدام المستندات - نشر البحث (REST).
يتم توسيع URI لتضمين تعبير استعلام، والذي يتم تحديده باستخدام /docs/search عامل التشغيل .
الصق في المثال التالي للاستعلام عن فهرس البحث. ثم حدد إرسال الطلب. يتضمن طلب البحث النصي دائما معلمة
search. يتضمن هذا المثال معلمة اختياريةsearchFieldsتقيد البحث عن النص إلى حقول معينة.### Run a query POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}} { "search": "lake view", "select": "HotelId, HotelName, Tags, Description", "searchFields": "Description, Tags", "count": true }راجع الاستجابة في الجزء المجاور. يجب أن يكون لديك عدد يشير إلى عدد التطابقات الموجودة في الفهرس، ودرجة بحث تشير إلى الصلة، وقيم كل حقل مدرج في العبارة
select.{ "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)", "@odata.count": 1, "value": [ { "@search.score": 0.6189728, "HotelId": "4", "HotelName": "Sublime Cliff Hotel", "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
الحصول على خصائص الفهرس
يمكنك أيضا استخدام الحصول على إحصائيات للاستعلام عن عدد المستندات وحجم الفهرس.
الصق في المثال التالي للاستعلام عن فهرس البحث. ثم حدد إرسال الطلب.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01 HTTP/1.1 Content-Type: application/json api-key: {{apiKey}}راجع الاستجابة. هذه العملية هي طريقة سهلة للحصول على تفاصيل حول تخزين الفهرس.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
تنظيف الموارد
عندما تعمل على اشتراكك الخاص، من الأفضل أن تُحدد في نهاية المشروع ما إذا كنت لا تزال بحاجة إلى الموارد التي أنشأتها أو لا. الموارد المتبقية قيد التشغيل يمكن أن تكلفك المال. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لحذف تشكيلة الموارد بأكملها.
يمكنك العثور على الموارد وإدارتها في المدخل باستخدام الارتباط All resources أو Resource groups في الجزء الموجود في أقصى اليسار.
يمكنك أيضا تجربة هذا DELETE الأمر:
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
الخطوة التالية
الآن بعد أن أصبحت على دراية بعميل REST وإجراء مكالمات REST إلى Azure الذكاء الاصطناعي Search، جرب بداية سريعة أخرى توضح دعم المتجهات.