Проверка подлинности запросов к службам ИИ Azure

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

Проверка подлинности с помощью ключа ресурса для одной службы или многослужебного ресурса Foundry ИИ.
Проверка подлинности с помощью маркера.
Проверка подлинности с помощью идентификатора Microsoft Entra.

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

Перед выполнением запроса вам потребуется подписка Azure и ресурс Ai Foundry. Если вам нужен ресурс AI Foundry, ознакомьтесь с руководством по созданию ресурса Ai Foundry .

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

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

Верхний колонтитул	Описание
Ocp-Apim-Subscription-Key	Используйте этот заголовок для проверки подлинности с помощью ключа ресурса для определенной службы или ключа ресурса AI Foundry.
Ocp-Apim-Subscription-Region	Этот заголовок требуется только при использовании ключа доступа AI Foundry в службе Azure AI Translator. Используйте этот заголовок, чтобы указать регион ресурса.
Авторизация	Используйте этот заголовок, если вы применяете маркер доступа. В следующих разделах подробно описан процесс обмена маркерами. Значение предоставляется в следующем формате: `Bearer <TOKEN>`.

Проверка подлинности с помощью ключа ресурса с одним обслуживанием

Первым вариантом является проверка подлинности запроса с помощью ключа ресурса для конкретной службы, например Azure AI Translator. Ключи можно получить на портале Azure для каждого созданного ресурса. Перейдите к своему ресурсу на портале Azure. Раздел "Ключи и конечная точка " можно найти в разделе "Управление ресурсами". Скопируйте конечную точку и ключ доступа, так как они потребуются для проверки подлинности вызовов API. Вы можете использовать KEY1 или KEY2. Наличие двух ключей позволяет безопасно менять и повторно создавать ключи без прерывания работы службы.

Чтобы использовать ключ ресурса для проверки подлинности запроса, его необходимо передать в качестве заголовка Ocp-Apim-Subscription-Key . Это пример вызова службы Azure AI Translator:

Это пример вызова службы перевода текстов:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Проверка подлинности с помощью ключа ресурса Ai Foundry

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

Ключ ресурса предоставляется в каждом запросе в качестве заголовка Ocp-Apim-Subscription-Key .

Поддерживаемые регионы

При использовании ключа ресурса AI Foundry для выполнения запроса api.cognitive.microsoft.comнеобходимо включить регион в URL-адрес. Например: westus.api.cognitive.microsoft.com.

При использовании ключа ресурса Ai Foundry с Azure AI Translator необходимо указать регион ресурсов с заголовком Ocp-Apim-Subscription-Region .

Проверка подлинности ресурсов AI Foundry поддерживается в следующих регионах:

australiaeast
brazilsouth
canadacentral
centralindia
eastasia
eastus
japaneast
northeurope
southcentralus
southeastasia
uksouth
westcentralus
westeurope
westus
westus2
francecentral
koreacentral
northcentralus
southafricanorth
uaenorth
switzerlandnorth

Примеры запросов

Это пример вызова службы Azure AI Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Проверка подлинности с помощью маркера доступа

Некоторые службы ИИ Azure принимают и в некоторых случаях требуют маркера доступа. В настоящее время маркеры доступа поддерживаются в следующих службах:

API перевода текстов;
Службы речи: API преобразования речи в текст
Службы распознавания речи: API преобразования текста в речь

Предупреждение

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

Ключи ресурсов AI Foundry и служб ИИ можно обменять на токены аутентификации. Маркер проверки подлинности действует в течение 10 минут. Они хранятся в формате JSON Web Token (JWT) и могут запрашиваться программным способом с помощью библиотек JWT.

Маркеры доступа добавляются в запрос в заголовке Authorization. К значению маркера следует добавить префикс Bearer, например так: Bearer YOUR_AUTH_TOKEN.

Примеры запросов

Используйте этот URL-адрес для обмена ключом ресурса для маркера доступа: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Эти регионы поддерживают обмен маркерами для ресурсов AI Foundry:

australiaeast
brazilsouth
canadacentral
centralindia
eastasia
eastus
japaneast
northeurope
southcentralus
southeastasia
uksouth
westcentralus
westeurope
westus
westus2

Получив маркер доступа, его следует включать в каждый запрос в заголовке Authorization. Это пример вызова службы Azure AI Translator:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Проверка подлинности в Microsoft Entra ID

Внимание

Проверка подлинности Microsoft Entra всегда должна использоваться вместе с пользовательским именем поддомена ресурса Azure. Региональные конечные точки не поддерживают проверку подлинности Microsoft Entra.

В предыдущих разделах мы показали, как пройти проверку подлинности с помощью ключей API. Хотя эти ключи предоставляют быстрый и простой путь для начала разработки, они не хватает в сценариях, требующих управления доступом на основе ролей Azure (Azure RBAC). Давайте рассмотрим, что необходимо для более безопасной проверки подлинности с помощью идентификатора Microsoft Entra.

В следующих разделах вы будете использовать среду Azure Cloud Shell или Azure CLI для создания поддомена, назначения ролей и получения маркера носителя для вызова служб ИИ Azure. На всякий случай в каждом разделе приведены ссылки со всеми доступными параметрами для каждой команды в Azure Cloud Shell и Azure CLI.

Внимание

Если ваша организация выполняет проверку подлинности с помощью идентификатора Microsoft Entra, следует отключить локальную проверку подлинности (проверку подлинности с ключами), чтобы пользователи в организации всегда должны использовать идентификатор Microsoft Entra.

Создание ресурса с пользовательским поддоменом

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

Для начала откройте среду Azure Cloud Shell. Затем выберите подписку:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```
Затем создайте ресурс AI Foundry с пользовательским поддоменом. Имя поддомена должно быть глобально уникальным и не может содержать специальные символы, например ".", "!", ",".
```
$account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
```
В случае успеха Конечная точка должна показать имя поддомена, уникальное для вашего ресурса.

Назначение роли субъекту-службе.

Теперь, когда есть пользовательский поддомен, связанный с ресурсом, необходимо назначить роль субъекту-службе.

Примечание.

Имейте в виду, что назначение ролей Azure может занять до пяти минут.

Сначала зарегистрируйте приложение Microsoft Entra.

$SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force

$app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword

Идентификатор приложения ApplicationId потребуется на следующем шаге.

Затем необходимо создать субъект-службу для приложения Microsoft Entra.
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Примечание.

При регистрации приложения на портал Azure этот шаг выполняется порталом.
Последним шагом является назначение роли "Пользователь Cognitive Services" субъекту-службе (в области действия ресурса). Назначая роль, вы предоставляете субъекту-службе доступ к этому ресурсу. Одному субъекту-службе можно предоставить доступ к нескольким ресурсам в своей подписке.

Примечание.

Используется ObjectId субъекта-службы, а не ObjectId для приложения. ACCOUNT_ID будет идентификатором ресурса Azure для созданного вами ресурса AI Foundry. Идентификатор ресурса Azure можно найти на портале Azure из свойств ресурса.
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

Образец запроса

В этом примере для проверки подлинности субъекта-службы используется пароль. Затем предоставленный маркер используется для вызова API визуального распознавания Azure.

Получите свой идентификатор TenantId:
```
$context=Get-AzContext
$context.Tenant.Id
```

Получите маркер:

$tenantId = $context.Tenant.Id
$clientId = $app.ApplicationId
$clientSecret = "<YOUR_PASSWORD>"
$resourceUrl = "https://cognitiveservices.azure.com/"

$tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    resource      = $resourceUrl
}

$responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
$accessToken = $responseToken.access_token

Примечание.

В любой момент, когда вы используете пароли в скрипте, наиболее безопасным вариантом является использование модуля управления секретами PowerShell и интеграция с решением, таким как Azure Key Vault.

ВызовИТЕ API визуального распознавания Azure:

$url = $account.Endpoint+"vision/v1.0/models"
$result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
$result | ConvertTo-Json

Либо можно проверить подлинность субъекта-службы с помощью сертификата. Кроме субъекта-службы, субъект-пользователь также поддерживается путем делегирования разрешений через другое приложение Microsoft Entra. В этом случае вместо паролей или сертификатов пользователям будет предложено использовать двухфакторную проверку подлинности при получении маркера.

Авторизация доступа к управляемым удостоверениям

Службы искусственного интеллекта Azure поддерживают проверку подлинности Microsoft Entra с управляемыми удостоверениями для ресурсов Azure. Управляемые идентификаторы Azure позволяют авторизовать доступ к ресурсам AI Foundry, используя учетные данные Microsoft Entra из приложений, работающих на виртуальных машинах Azure, функциональных приложениях, масштабируемых наборах виртуальных машин и других службах. Используя управляемые удостоверения для ресурсов Azure вместе с проверкой подлинности Microsoft Entra, вы можете избежать хранения учетных данных с приложениями, работающими в облаке.

Включите управляемые удостоверения на виртуальной машине

Прежде чем использовать управляемые удостоверения для ресурсов Azure для авторизации доступа к ресурсам AI Foundry из виртуальной машины, необходимо включить управляемые удостоверения для ресурсов Azure на виртуальной машине. Чтобы узнать, как включить управляемые удостоверения для ресурсов Azure, прочитайте:

Дополнительные сведения об управляемых удостоверениях см. в статье Управляемые удостоверения для ресурсов Azure.

Использование Azure Key Vault для безопасного хранения учетных данных

Azure Key Vault можно использовать для безопасной разработки приложений Azure AI Foundry. Key Vault позволяет хранить учетные данные проверки подлинности в облаке и снижает вероятность случайной утечки секретов, так как вы не будете хранить сведения о безопасности в приложении.

Проверка подлинности выполняется с помощью идентификатора Microsoft Entra. Авторизацию можно выполнить с помощью управления доступом на основе ролей в Azure (Azure RBAC) или политики доступа Key Vault. Azure RBAC можно использовать как для управления хранилищами, так и для доступа к хранимым в них данным. При этом политика доступа к хранилищу ключей может использоваться только при попытке получить доступ к данным в хранилище.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-05-20

Поделиться через

Проверка подлинности запросов к службам ИИ Azure

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

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

Проверка подлинности с помощью ключа ресурса с одним обслуживанием

Проверка подлинности с помощью ключа ресурса Ai Foundry

Поддерживаемые регионы

Примеры запросов

Проверка подлинности с помощью маркера доступа

Примеры запросов

Проверка подлинности в Microsoft Entra ID

Создание ресурса с пользовательским поддоменом

Назначение роли субъекту-службе.

Образец запроса

Авторизация доступа к управляемым удостоверениям

Включите управляемые удостоверения на виртуальной машине

Использование Azure Key Vault для безопасного хранения учетных данных

Связанный контент

Обратная связь

Дополнительные ресурсы