التشغيل السريع: إنشاء فهرس بحث في PowerShell باستخدام واجهات برمجة تطبيقات REST

مقالة
03/27/2024

في التشغيل السريع ل Azure الذكاء الاصطناعي Search، تعرف على كيفية إنشاء فهرس بحث وتحميله والاستعلام عن ذلك باستخدام PowerShell وAzure الذكاء الاصطناعي Search REST APIs. توضح هذه المقالة كيفية تشغيل أوامر PowerShell بصورة تفاعلية. بدلاً من ذلك، يمكنك تحميل برنامج نصي ما لـ PowerShell وتشغيله الذي يؤدي نفس العمليات.

في حال لم يكن لديك اشتراك Azure، فأنشئ حساباً مجانيّاً قبل البدء.

المتطلبات الأساسية

الخدمات والأدوات التالية مطلوبة لهذا التشغيل السريع:

PowerShell 7.3 أو أحدث، باستخدام Invoke-RestMethod للخطوات المتسلسلة والتفاعلية.
قم بإنشاء الذكاء الاصطناعي خدمة البحث Azure أو ابحث عن خدمة موجودة ضمن اشتراكك الحالي. يمكنك استخدام خدمة مجانية لهذه البداية السريعة.

نسخ مفتاح خدمة البحث وعنوان URL

في هذا التشغيل السريع، تتضمن استدعاءات REST عنوان URL للخدمة ومفتاح وصول على كل طلب. يتم إنشاء خدمة بحث مع كليهما، لذلك إذا قمت بإضافة Azure الذكاء الاصطناعي Search إلى اشتراكك، فاتبع هذه الخطوات للحصول على المعلومات الضرورية.

قم بتسجيل الدخول إلى بوابة Azure. في صفحة نظرة عامة على خدمة البحث، احصل على عنوان URL. قد يبدو مثال نقطة النهاية بالشكل https://mydemo.search.windows.net.
حدد الإعدادات> Keys ثم احصل على مفتاح مسؤول للحصول على الحقوق الكاملة على الخدمة. يتم توفير مفتاحي إدارة قابلين للتبديل لاستمرارية الأعمال إذا كنت بحاجة إلى تمرير واحد. يمكنك استخدام المفتاح الأساسي أو الثانوي عند طلبات إضافة الكائنات وتعديلها وحذفها.

تتطلب جميع الطلبات مفتاح API على كل طلب يتم إرساله إلى خدمتك. وجود مفتاح صالح يؤسس الثقة، على أساس كل طلب، بين التطبيق الذي يرسل الطلب والخدمة التي تتعامل معه.

الاتصال إلى Azure الذكاء الاصطناعي Search

في PowerShell، قم بإنشاء كائن $headers لتخزين نوع المحتوى ومفتاح API. استبدل مفتاح API المسؤول (YOUR-ADMIN-API-KEY) بمفتاح صالح لخدمة البحث. يجب عليك فقط تعيين هذا العنوان مرة واحدة طوال مدة جلسة العمل، ولكن يمكنك إضافته إلى كل طلب.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
إنشاء كائن $url يحدد مجموعة فهارس الخدمة. استبدل اسم الخدمة (YOUR-SEARCH-SERVICE-NAME) بخدمة بحث صالحة.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
قم بتشغيل Invoke-RestMethod لإرسال طلب GET إلى الخدمة والتحقق من الاتصال. أضف ConvertTo-Json بحيث يمكنك عرض الاستجابات المرسلة من الخدمة.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
إذا كانت الخدمة فارغة ولا تحتوي على أي فهارس، تكون النتائج مشابهة للمثال التالي. وإلا، فسترى تمثيل JSON لتعريفات الفهرس.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

إنشاء فهرس

ما لم تكن تستخدم المدخل، يجب أن يكون الفهرس موجودا على الخدمة قبل أن تتمكن من تحميل البيانات. تعرف هذه الخطوة الفهرس وتدفعه إلى الخدمة. يُستخدم "Create Index REST API" لهذه الخطوة.

تتضمن العناصر المطلوبة من الفهرس الاسم ومجموعة المجالات. تُعرّف مجموعة مجالات بنية المستند. يحتوي كل حقل على اسم ونوع وسمات تحدد كيفية استخدامه (على سبيل المثال، ما إذا كان النص الكامل قابلا للبحث أو التصفية أو الاسترداد في نتائج البحث). ولا بد من تعيين أحد مجالات النوع Edm.Stringبوصفهمفتاح لهوية المستند.

يسمى hotels-quickstart هذا الفهرس ويحتوي على تعريفات الحقول التي تراها في التعليمات البرمجية التالية. إنها مجموعة فرعية من فهرس فنادق أكبر يستخدم في مقالات معاينة أخرى. يتم اقتطاع تعريفات الحقول في هذا التشغيل السريع للإيجاز.

الصق هذا المثال في PowerShell لإنشاء كائن $body يحتوي على مخطط الفهرس.

$body = @"
{
    "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}
        ]
     }
  ]
}
"@

تعيين URI إلى مجموعة الفهارس على الخدمة والفهرس hotels-quickstart .

$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"

قم بتشغيل الأمر باستخدام $urlو $headersو $body لإنشاء الفهرس على الخدمة.

Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json

يجب أن تبدو النتائج مشابهة لهذا المثال، الذي يعرض الحقلين الأولين فقط للإيجاز:

{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag":  "\"0x8D6EDE28CFEABDA\"",
    "name":  "hotels-quickstart",
    "defaultScoringProfile":  null,
    "fields":  [
                {
                    "name":  "HotelId",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  true,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  true,
                    "key":  true,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                {
                    "name":  "HotelName",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  false,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  false,
                    "key":  false,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                . . .
    ]
}

تلميح

للتحقق، يمكنك أيضا التحقق من قائمة الفهارس في المدخل.

تحميل المستندات

لدفع المستندات، استخدم طلب HTTP POST إلى نقطة نهاية عنوان URL للفهرس. تعد REST API لهذه المهمة هي إضافة مستندات أو تحديثها أو حذفها.

الصق هذا المثال في PowerShell لإنشاء كائن $body يحتوي على المستندات التي تريد تحميلها.

يتضمن هذا الطلب سجلين كاملين وسجلا جزئيا واحدا. يوضح السجل الجزئي أنه يمكنك تحميل مستندات غير مكتملة. @search.actionيحدد المعيار كيفية إجراء الفهرسة. تتضمن القيم الصالحة upload، وmerge، وmergeOrUpload، وdelete. يقوم mergeOrUpload السلوك إما بإنشاء مستند جديد للمحتويات hotelId = 3 أو تحديثها إذا كان موجودا بالفعل.

$body = @"
{
    "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"
        }
    }
]
}
"@

تعيين نقطة النهاية إلى hotels-quickstart مجموعة المستندات وتضمين عملية الفهرس (indexes/hotels-quickstart/docs/index).
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

قم بتشغيل الأمر باستخدام $urlو $headersو $body لتحميل المستندات في الفهرس hotels-quickstart .

Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json

ينبغي أن تتشابه النتائج مع المثال التالي. وينبغي أن تشاهد رمز حالة 201.

{
    "@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)",
    "value":  [
                {
                    "key":  "1",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "2",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "3",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "4",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                }
            ]
}

البحث في فهرس

توضح لك هذه الخطوة كيفية الاستعلام عن فهرس باستخدام واجهة برمجة تطبيقات البحث في المستندات.

تأكد من استخدام علامات اقتباس مفردة عند البحث $urls. تتضمن $ سلاسل الاستعلام أحرفا، ويمكنك حذف الاضطرار إلى إلغاءها إذا كانت السلسلة بأكملها محاطة بعلامات اقتباس مفردة.

قم بتعيين نقطة النهاية إلى hotels-quickstart مجموعة المستندات وأضف معلمة search لتمريرها في سلسلة استعلام.

تقوم هذه السلسلة بتنفيذ بحث فارغ (search=*)، مع إرجاع قائمة غير مجزية (درجة البحث = 1.0) من المستندات العشوائية. بشكل افتراضي، يقوم Azure الذكاء الاصطناعي Search بإرجاع 50 تطابقا في كل مرة. كما هو منظم، يقوم هذا الاستعلام بإرجاع بنية المستند بأكمله وقيمه. أضف $count=true للحصول على عدد جميع المستندات في النتائج.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

قم بتشغيل الأمر لإرسال $url إلى الخدمة.

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

يجب أن تبدو النتائج مشابهة للإخراج التالي:

{
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "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.6,
                  "Address":  "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}"
              },
              {
                  "@search.score":  0.009068266,
                  "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\u0027s restaurant services.",
                  "Category":  "Resort and Spa",
                  "Tags":  "air conditioning bar continental breakfast",
                  "ParkingIncluded":  true,
                  "LastRenovationDate":  "2015-09-20T00:00:00Z",
                  "Rating":  4.8,
                  "Address":  "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}"
              },
            . . .
    ]
}

جرّب بعض الأمثلة الأخرى للاستعلام للتعرّف على الصيغة. يمكنك إجراء بحث سلسلة واستعلامات حرفية $filter وتحديد مجموعة النتائج ونطاق البحث إلى حقول معينة والمزيد.

# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'

# Query example 2 
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'

# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=boutique&$top=2&$select=HotelName,Category'

# Query example 4
# Sort by a specific field (Address/City) in ascending order

$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

تنظيف الموارد

عندما تعمل على اشتراكك الخاص، من الأفضل أن تُحدد في نهاية المشروع ما إذا كنت لا تزال بحاجة إلى الموارد التي أنشأتها أو لا. الموارد المتبقية قيد التشغيل يمكن أن تكلفك المال. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لحذف تشكيلة الموارد بأكملها.

يمكنك العثور على الموارد وإدارتها في المدخل باستخدام الارتباط All resources أو Resource groups في الجزء الموجود في أقصى اليسار.

إذا كنت تستخدم خدمة مجانية، فتذكر أنك تقتصر على ثلاثة فهارس ومفهرسات ومصادر بيانات. يمكنك حذف العناصر الفردية في المدخل لعدم تجاوز الحد المسموح به.

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

في هذا التشغيل السريع، استخدمت PowerShell للتنقل عبر سير العمل الأساسي لإنشاء المحتوى والوصول إليه في Azure الذكاء الاصطناعي Search. مع مراعاة المفاهيم، نوصي بالانتقال إلى سيناريوهات أكثر تقدما، مثل الفهرسة من مصادر بيانات Azure:

البرنامج التعليمي REST: فهرسة البيانات شبه المنظمة والبحث فيها (JSON blobs) في Azure الذكاء الاصطناعي Search

Share via