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

  • Статья

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

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

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

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

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

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

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

Вызовы REST требуют конечной точки службы поиска и ключа API для каждого запроса. Эти значения можно получить из портал Azure.

  1. Войдите на портал Azure. Затем перейдите на страницу обзора службы поиска и скопируйте URL-адрес. Пример конечной точки может выглядеть так: https://mydemo.search.windows.net.

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

    Снимок экрана: url-адрес и ключи API в портал Azure.

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

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

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

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

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

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

  4. Вставьте следующий пример. Замените базовый 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}}

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

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

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

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

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

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

  1. Вставьте следующий пример, чтобы создать 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}
                ]
            }
        ]
    }

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

  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=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
    }

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

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

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

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

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

  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=2023-11-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

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

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

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