Управление службой Поиск с использованием ИИ Azure с помощью REST API

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

REST API управления доступен в стабильных и предварительных версиях. Если вы обращаетесь к функциям предварительной версии API, обязательно установите предварительную версию API.

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

Необходимые условия

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно.

• Visual Studio Code с клиентом REST.

• Azure CLI для получения токена доступа, описанного в следующих шагах. Вы должны быть владельцем или администратором в подписке Azure.

  Вызовы REST API управления проходят проверку подлинности через Microsoft Entra ID. Необходимо предоставить маркер доступа в запросе и разрешениях для создания и настройки ресурса. Помимо Azure CLI можно использовать Azure PowerShell для создания маркера доступа.

  1. Откройте командную оболочку для Azure CLI.

  2. Войдите в подписку Azure. Если у вас несколько арендаторов или подписок, убедитесь, что вы выбрали правильный.

     az login
     

  3. Получите идентификатор клиента и идентификатор подписки.

     az account show
     

  4. Получение токена доступа.

     az account get-access-token --query accessToken --output tsv
     

     У вас должен быть идентификатор арендатора, идентификатор подписки и токен. Эти значения будут вставлены в файл .rest или файл .http, который будет создан на следующем шаге.

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

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

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

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

   

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

4. Укажите переменные для значений, полученных на предыдущем шаге.

   @tenant-id = PUT-YOUR-TENANT-ID-HERE
   @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
   @token = PUT-YOUR-TOKEN-HERE
   

5. Убедитесь, что сеанс работает, перечисляя службы поиска в подписке.

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
         Content-type: application/json
         Authorization: Bearer {{token}}
   

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

   HTTP/1.1 200 OK
   Cache-Control: no-cache
   Pragma: no-cache
   Content-Length: 22068
   Content-Type: application/json; charset=utf-8
   Expires: -1
   x-ms-ratelimit-remaining-subscription-reads: 11999
   x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
   x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
   x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
   Strict-Transport-Security: max-age=31536000; includeSubDomains
   X-Content-Type-Options: nosniff
   X-Cache: CONFIG_NOCACHE
   X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
   Date: Thu, 14 Mar 2024 01:20:52 GMT
   Connection: close
   
   {
     "value": [ . . . ]
   }
   

Создание или обновление службы

Создает или обновляет службу поиска в текущей подписке. В этом примере используются переменные для имени службы поиска и региона, которые еще не определены. Укажите имена напрямую или добавьте в коллекцию новые переменные.

### Create a search service (provide an existing resource group)
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

Обновление службы

Некоторые возможности Поиск с использованием ИИ Azure доступны только для новых служб. Чтобы избежать воссоздания службы и добавить эти возможности к существующей службе, вы можете обновить службу.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Изменение ценовых категорий

Если требуется больше или меньше емкости, вы можете перейти на другую ценовую категорию. В настоящее время можно переключаться только между уровнями "Базовый" и "Стандартный" (S1, S2 и S3). sku Используйте свойство, чтобы указать новый уровень.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Создание службы S3HD

Чтобы создать службу S3HD , используйте сочетание sku и hostingMode свойства. Установите sku на standard3, а "hostingMode" — на HighDensity.

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Настройка ролевого доступа для уровня данных

Применимо к: Участник данных индекса поиска, читатель индексов поиска, участник службы поиска

Настройте службу поиска для распознавания заголовка авторизации в запросах данных, которые предоставляют маркер доступа OAuth2.

Чтобы использовать управление доступом на основе ролей для операций плоскости данных, установите authOptions на aadOrApiKey и затем отправьте запрос.

Чтобы использовать исключительно управление доступом на основе ролей, отключите проверку подлинности ключа API, выполнив второй запрос, на этот раз установив параметр disableLocalAuth в true.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Настройка конфиденциальных вычислений

Конфиденциальные вычисления — это необязательный тип вычислений для защиты от использования данных. При настройке служба поиска развертывается на конфиденциальных виртуальных машинах (DCasv5 или DCesv5) вместо стандартных виртуальных машин. Этот тип вычислений также влечет за собой 10%-ную дополнительную наценку для оплачиваемых уровней. Дополнительные сведения см. на странице цен.

Для ежедневного использования конфиденциальные вычисления не нужны. Этот тип вычислений рекомендуется только для строгих нормативных требований, соответствия или безопасности. Дополнительные сведения см. в вариантах использования конфиденциальных вычислений.

Тип вычислений неизменен на протяжении всего срока службы вашего поискового сервиса. Чтобы постоянно настроить конфиденциальные вычисления, задайте свойство computeType на confidential для новой службы.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

Осуществление политики ключей, управляемой клиентом

Если вы используете управляемое клиентом шифрование, вы можете включить "encryptionWithCMK" с параметром "Принудительное применение", если требуется, чтобы служба поиска сообщала о своем состоянии соответствия.

При включении этой политики все вызовы REST, создающие объекты, содержащие конфиденциальные данные, такие как строка подключения в источнике данных, завершаются ошибкой, если ключ шифрования не указан: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Отключение нагрузок, которые передают данные во внешние ресурсы

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Удаление службы поиска

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Список ключей API администратора

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Повторное создание ключей API администратора

Одновременно можно создать только один ключ API администратора.

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Создание ключей API запросов

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Список подключений к частной конечной точке

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Список операций поиска

### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups?api-version=2021-04-01  HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Дальнейшие действия

После настройки службы поиска выполните следующие действия: создание индекса или querying index с помощью портала Azure, REST API или Azure SDK.

• Создайте индекс Поиск с использованием ИИ Azure в портале Azure
• Настройка индексатора для загрузки данных из других служб
• Запросите индекс Поиск с использованием ИИ Azure с помощью обзора поиска в портале Azure
• Как использовать Поиск с использованием ИИ Azure в .NET