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

Статья
2025-04-19

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

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

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

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

Предварительные условия

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Visual Studio Code с клиентом REST.
Azure CLI для получения токена доступа, как описано в приведённых ниже шагах. Вы должны быть владельцем или администратором в подписке Azure.

Вызовы REST API управления проходят проверку подлинности с помощью идентификатора Microsoft Entra. Необходимо предоставить маркер доступа в запросе и разрешениях для создания и настройки ресурса. Помимо 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, в этом разделе описана настройка, чтобы выполнить задачи, описанные в этой статье.

Запустите Visual Studio Code и выберите плитку Extensions .
Найдите клиент REST и нажмите кнопку "Установить".
Откройте или создайте файл с именем или расширением .rest.http .

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

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

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

 ### List search services
 GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

Щелкните Отправить запрос. Ответ должен отображаться в соседней области. Если у вас есть службы поиска, они перечислены. В противном случае список пуст, но до тех пор, пока код 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 = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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 = my-rg
@search-service-name = my-search
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/upgrade?api-version=2025-02-01-preview  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

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

### Change pricing tiers
@resource-group = my-rg
@search-service-name = my-search
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-02-01-preview HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

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

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

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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.

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

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

Применение политики клиентского управления ключами

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

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

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

Отключить семантический ранжировщик

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

### Disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

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

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

### Disable external access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

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

### Delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

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

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

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

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

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