Краткое руководство. Создание индекса поиска в PowerShell с помощью REST API

Статья
10/31/2024

В этом кратком руководстве по поиску ИИ Azure вы узнаете, как создавать, загружать и запрашивать индекс поиска с помощью PowerShell и REST API службы поиска ИИ Azure. Здесь содержатся сведения о выполнении команд PowerShell в интерактивном режиме. Вы также можете скачать и запустить скрипт PowerShell, выполняющий те же операции.

Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.

Необходимые компоненты

Для этого краткого руководства требуются следующие службы и средства.

PowerShell 7.3 или более поздней версии с помощью Invoke-RestMethod для последовательных и интерактивных шагов.
Создайте служба ИИ Azure или найдите существующую службу в текущей подписке. Вы можете использовать бесплатную службу для выполнения инструкций, описанных в этом кратком руководстве.

Копирование ключа службы поиска и URL-адреса

В этом кратком руководстве вызовы REST включают URL-адрес службы и ключ доступа для каждого запроса. Служба поиска создается вместе с этими службами, поэтому если вы добавили в подписку поиск ИИ Azure, выполните следующие действия, чтобы получить необходимые сведения.

Войдите на портал Azure. На странице обзора службы поиска получите URL-адрес. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.
Выберите "Ключи>параметров", а затем получите ключ администратора для полного доступа к службе. Два взаимозаменяемых ключа администратора предоставляются для обеспечения непрерывности бизнес-процессов, если необходимо выполнить перекат. Вы можете использовать первичный или вторичный ключ для выполнения запросов на добавление, изменение и удаление объектов.

Все запросы требуют ключа API для каждого запроса, отправленного в службу. Наличие допустимого ключа устанавливает доверие на основе каждого запроса между приложением, отправляющим запрос, и службой, обрабатывающей ее.

Подключение к поиску по искусственному интеллекту Azure

В 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=2024-07-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":  [

            ]
}
```

Создание индекса

Если вы не используете портал, индекс должен существовать в службе, прежде чем загружать данные. Этот шаг определяет индекс и передает его в службу. Для этого используется 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=2024-07-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": "Stay-Kay City Hotel",
    "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": "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.",
    "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": "Gastronomic 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 Palace Hotel",
    "Description": "Sublime Palace 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 Palace 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=2024-07-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
                }
            ]
}

Поиск в индексе

На этом шаге показано, как запросить индекс с помощью API документов поиска.

Не забудьте использовать одинарные кавычки для поиска $urls. Строки запроса включают $ символы, и вы можете опустить их, если вся строка заключена в одинарные кавычки.

Задайте конечную точку hotels-quickstart коллекции документов и добавьте search параметр для передачи в строку запроса.

Эта строка выполняет пустой поиск (search=*), возвращая неподделанный список (оценка поиска = 1.0) произвольных документов. По умолчанию поиск ВИ Azure возвращает 50 совпадений за раз. Как структурированный этот запрос возвращает структуру и значения документа. Добавьте $count=true , чтобы получить количество всех документов в результатах.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-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":  "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.",
                  "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":  "Gastronomic 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=2024-07-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=2024-07-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=2024-07-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=2024-07-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

Очистка ресурсов

Если вы работаете в собственной подписке, в конце проекта следует решить, нужны ли вам созданные ресурсы. Ресурсы, которые продолжат работать, могут быть платными. Вы можете удалить ресурсы по отдельности либо удалить всю группу ресурсов.

Вы можете найти ресурсы на портале и управлять ими, используя ссылку "Все ресурсы" или "Группы ресурсов" в левой области.

Если вы используете бесплатную службу, помните, что вы ограничены тремя индексами, индексаторами и источниками данных. Вы можете удалить отдельные элементы на портале, чтобы не превысить лимит.

Следующие шаги

В этом кратком руководстве вы использовали PowerShell для пошагового выполнения базового рабочего процесса для создания и доступа к содержимому в службе "Поиск ИИ Azure". Учитывая основные понятия, рекомендуется перейти к более сложным сценариям, таким как индексирование из источников данных Azure:

Руководство по REST. Индексирование и поиск полуструктурированных данных (BLOB-объектов JSON) в службе "Поиск ИИ Azure"

Поделиться через