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

Краткое руководство. Поиск ключевых слов с помощью REST

  • Статья

ИНТЕРФЕЙСы REST API в службе "Поиск ИИ Azure" предоставляют программный доступ ко всем возможностям, включая предварительные версии функций, и это простой способ узнать, как работают функции. В этом кратком руководстве вы узнаете, как вызвать ИНТЕРФЕЙСы REST API поиска для создания, загрузки и запроса индекса поиска в службе "Поиск ИИ Azure".

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

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

Загрузка файлов

Скачайте пример REST из GitHub, чтобы отправить запросы в этом кратком руководстве. Инструкции можно найти при скачивании файлов из GitHub.

Вы также можете запустить новый файл в локальной системе и вручную создать запросы, выполнив инструкции в этой статье.

Получение конечной точки службы поиска

Конечную точку службы поиска можно найти в портал Azure.

  1. Войдите в портал Azure и найдите службу поиска.

  2. На домашней странице обзора найдите URL-адрес. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.

    Снимок экрана: свойство URL-адреса на странице обзора.

Вы вставите эту конечную точку в .rest файл или .http файл на следующем шаге.

Настройка доступа

Запросы к конечной точке поиска должны проходить проверку подлинности и авторизованы. Для этой задачи можно использовать ключи ИЛИ роли API. Ключи проще начать с, но роли более безопасны.

Для подключения на основе ролей следующие инструкции позволяют подключаться к службе "Поиск ИИ Azure" под удостоверением, а не к идентификатору клиентского приложения.

Вариант 1. Использование ключей

Выберите "Ключи параметров"> и скопируйте ключ администратора. Ключи администратора используются для добавления, изменения и удаления объектов. Существует два взаимозаменяемых ключа администратора. Скопируйте любой из них. Дополнительные сведения см. в статье "Подключение к поиску ИИ Azure" с помощью проверки подлинности ключей.

Снимок экрана: ключи API в портал Azure.

Вы вставите этот ключ в .rest файл или .http файл на следующем шаге.

Вариант 2. Использование ролей

Убедитесь, что служба поиска настроена для доступа на основе ролей. Необходимо иметь предварительно настроенные назначения ролей для доступа разработчика. Назначения ролей должны предоставить разрешение на создание, загрузку и запрос индекса поиска.

В этом разделе вы получите маркер личных удостоверений с помощью Azure CLI, Azure PowerShell или портал Azure.

  1. Войдите в Azure CLI.

    az login

  2. Получите маркер личных удостоверений.

    az account get-access-token --scope https://search.azure.com/.default

Вы вставите маркер личных удостоверений в .rest файл или .http файл на следующем шаге.

Примечание.

В этом разделе предполагается, что вы используете локальный клиент, который подключается к службе поиска ИИ Azure от вашего имени. Альтернативный подход — получение маркера для клиентского приложения, если приложение зарегистрировано с идентификатором Microsoft Entra.

Настройка Visual Studio Code

Если вы не знакомы с клиентом REST для Visual Studio Code, в этом разделе описана настройка, чтобы выполнить задачи в этом кратком руководстве.

  1. Запустите Visual Studio Code и выберите плитку Extensions .

  2. Найдите клиент REST и нажмите кнопку "Установить".

    Снимок экрана: кнопка установки клиента REST.

  3. Откройте или создайте файл с именем или расширением .rest .http .

  4. Вставьте следующий пример, если вы используете ключи API. Замените @baseUrl @apiKey заполнители значениями, скопированными ранее.

    @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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. Или вставьте в этом примере, если используются роли. Замените @baseUrl @token заполнители значениями, скопированными ранее.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  6. Щелкните Отправить запрос. Ответ должен отображаться в соседней области. Если у вас есть индексы, они перечислены. В противном случае список пуст. Если http-код имеет значение 200 OK, вы готовы к следующим шагам.

    Снимок экрана: клиент REST, настроенный для запроса службы поиска.

    Основные моменты:

    • Параметры задаются с помощью @ префикса.
    • ### задает вызов REST. Следующая строка содержит запрос, который должен включать HTTP/1.1.
    • Send request должен появиться над запросом.

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

Добавьте второй запрос в .rest файл. Создание индекса (REST) создает индекс поиска и настраивает структуры физических данных в службе поиска.

  1. Вставьте следующий пример, чтобы создать hotels-quickstart индекс в службе поиска.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

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

  2. Щелкните Отправить запрос. Должен быть HTTP/1.1 201 Created ответ, а текст ответа должен содержать представление JSON схемы индекса.

    Если вы получите ошибку Header name must be a valid HTTP token ["{"] , убедитесь, что между текстом запроса есть пустая строка api-key . Если вы получите HTTP 504, убедитесь, что URL-адрес указывает HTTPS. Если возникают сообщения об ответных кодах 400 или 404 протокола HTTP, следует удостовериться в отсутствии ошибок при копировании. Http 403 обычно указывает на проблему с ключом API. Это либо недопустимый ключ, либо проблема синтаксиса с указанием ключа API.

    Теперь в файле есть несколько запросов. Помните, что ### запускает новый запрос и каждый запрос выполняется независимо.

    Снимок экрана: клиент REST с несколькими запросами.

О определении индекса

В схеме индекса коллекция полей определяет структуру документа. Каждый документ, который вы отправляете, должен иметь эти поля. Каждое поле должно быть назначено типу данных модели данных сущности (EDM). Строковые поля используются в полнотекстовом поиске. Если требуется, чтобы числовые данные были доступны для поиска, убедитесь, что тип данных имеет значение Edm.String. Другие типы данных, такие как Edm.Int32 фильтруемые, сортируемые, фасетные и извлекаемые, но не доступные для полнотекстового поиска.

Атрибуты в поле определяют разрешенные действия. ИНТЕРФЕЙСы REST API позволяют выполнять по умолчанию множество действий. Например, все строки доступны для поиска и извлекаются по умолчанию. Для ИНТЕРФЕЙСов REST API могут быть только атрибуты, если необходимо отключить поведение.

{
    "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 индекс содержит все данные, доступные для поиска, и запросы, выполняемые в службе поиска. Для вызовов REST данные предоставляются в виде документов JSON. Используйте REST API индексов для этой задачи.

Универсальный код ресурса (URI) расширен для включения коллекций и index операцийdocs.

  1. Вставьте следующий пример, чтобы отправить документы JSON в индекс поиска.

    ### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

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

  2. Щелкните Отправить запрос. Через несколько секунд вы увидите ответ HTTP 201 на соседней панели.

    Код 207 говорит об ошибке загрузки хотя бы одного из документов. Код 404 говорит о синтаксической ошибке в заголовке или в теле запроса. Убедитесь, что вы изменили конечную точку, чтобы включить /docs/index.

Выполнение запросов

Теперь, когда документы загружены, вы можете выдавать запросы к ним с помощью документов — post (REST).

Универсальный код ресурса (URI) расширен для включения выражения запроса, указанного /docs/search с помощью оператора.

  1. Вставьте в следующий пример запрос к индексу поиска. Затем нажмите кнопку "Отправить запрос". Запрос на поиск текста всегда содержит search параметр. В этом примере включается необязательный searchFields параметр, который ограничивает поиск текста определенными полями.

    ### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "search": "lake view",
      "select": "HotelId, HotelName, Tags, Description",
      "searchFields": "Description, Tags",
      "count": true
  }

  2. Просмотрите ответ на соседней панели. Должно быть число, указывающее количество совпадений, найденных в индексе, оценку поиска, указывающую релевантность и значения для каждого поля, указанного в инструкции 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 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.",
      "Tags": [
        "concierge",
        "view",
        "24-hour front desk service"
      ]
    }
  ]
}

Запрос свойств индекса

Вы также можете использовать получение статистики для запроса количества документов и размера индекса.

  1. Вставьте в следующий пример запрос к индексу поиска. Затем нажмите кнопку "Отправить запрос".

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  2. Проверьте ответ. Эта операция — это простой способ получить сведения о хранилище индексов.

    {
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

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

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

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

Вы также можете попробовать следующую DELETE команду:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

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

Теперь, когда вы знакомы с клиентом REST и выполняете вызовы REST к поиску ИИ Azure, попробуйте еще одно краткое руководство, демонстрирующее поддержку векторов.

Краткое руководство. Поиск вектора с помощью REST