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

• Портал
• PowerShell
• Azure CLI
• 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.

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

2. Вход в вашу подписку Azure.

   az login
   

3. Получите идентификатор клиента и идентификатор подписки. Если у вас несколько клиентов или подписок, убедитесь, что вы используете правильный.

   az account show
   

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

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

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

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

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

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

   

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

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

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

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

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

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 = 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 значение standard3HighDensity"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": "Disabled",
            "encryptionComplianceStatus": "Compliant"
            },
        }
    }

Отключение семантического ранжирования

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

### disable semantic ranking
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 

Создание ключей 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}}

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

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

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