Управление служба ИИ Azure с помощью REST API
Из этой статьи вы узнаете, как создать и настроить azure AI служба с помощью 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.
Откройте командную оболочку для Azure CLI.
Вход в вашу подписку Azure.
az login
Получите идентификатор клиента и идентификатор подписки. Если у вас несколько клиентов или подписок, убедитесь, что вы используете правильный.
az account show
Получение маркера доступа.
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"
}
}
Создание службы S3HD
Чтобы создать службу S3HD , используйте сочетание sku
и hostingMode
свойства. Для параметра "hostingMode" задано sku
значение standard3
HighDensity
"hostingMode".
@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"
}
}
}
Отключение семантического ранга
Хотя семантический рангировщик не включен по умолчанию, вы можете заблокировать функцию на уровне службы для более точного ее использования.
### 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.