驗證對 Azure AI 服務的要求

2025-05-20

對 Azure AI 服務的每個要求都必須包含驗證標頭。此標頭會與資源金鑰或驗證權杖一起傳遞，用來驗證您服務或服務群組的訂用帳戶。在本文中，您將了解驗證要求的三種方式及各自的需求。

使用單一服務或 AI Foundry 多重服務資源金鑰進行驗證。
使用令牌進行驗證。
使用 Microsoft Entra 識別碼進行驗證。

必要條件

提出要求之前，您需要 Azure 訂用帳戶和 AI Foundry 資源。如果您需要 AI Foundry 資源，請參閱建立 AI Foundry 資源指南。

驗證標頭

讓我們快速檢閱適用於 Azure AI 服務的驗證標頭。

標頭	描述
Ocp-Apim-Subscription-Key	使用此標頭以資源金鑰驗證特定服務或 AI Foundry 資源金鑰。
Ocp-Apim-Subscription-Region	只有在搭配 Azure AI Translator 服務使用 AI Foundry 資源密鑰時，才需要此標頭。使用此標頭以指定資源區域。
授權	如果您使用存取權杖，請使用此標頭。下列各節會詳細說明執行權杖交換的步驟。提供的值遵循下列格式：`Bearer <TOKEN>`。

使用單一服務資源金鑰進行驗證

第一個選項是使用資源金鑰來為特定服務 (例如 Azure AI 翻譯工具) 驗證要求。金鑰適用於 Azure 入口網站中您建立的每個資源。移至您在 Azure 入口網站中的資源。您可以在 [資源管理] 區段中找到 [金鑰和端點] 區段。複製您的端點和存取金鑰，因為您需要這兩者才能驗證 API 呼叫。您可以使用 KEY1 或 KEY2。隨時持有兩個金鑰可讓您安全地輪替和重新產生金鑰，而不會造成服務中斷。

若要使用資源金鑰來驗證要求，它必須作為 Ocp-Apim-Subscription-Key 標頭一起傳遞。這是對 Azure AI 翻譯工具服務的範例呼叫：

這是翻譯工具服務的範例呼叫：

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 AI 服務的要求。驗證認證不會系結至特定服務。如需區域可用性、支援功能和定價的詳細資訊，請參閱 Azure AI 服務定價。

在每個要求中會提供資源金鑰以作為 Ocp-Apim-Subscription-Key 標頭。

支援的區域

使用 AI Foundry 資源金鑰向 api.cognitive.microsoft.com 提出請求時，您必須在 URL 中包含區域。例如： westus.api.cognitive.microsoft.com 。

搭配 Azure AI Translator 使用 AI Foundry 資源密鑰時，您必須使用 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 翻譯工具服務的範例呼叫：

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 AI 服務接受存取權杖，而在某些情況下還會需要存取權杖。目前，以下服務支援存取權杖：

文字翻譯 API
語音服務：語音轉換文字 API
語音服務：文字轉換語音 API

警告

支援存取令牌的服務可能會隨著時間而變更，因此請先檢查服務的 API 參考，再使用此驗證方法。

AI Foundry 和 AI 服務資源金鑰可以交換為驗證令牌。驗證權杖的有效時間為 10 分鐘。它們會以 JSON Web 權杖 (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 翻譯工具服務的範例呼叫：

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 識別碼驗證

重要

Microsoft Entra 驗證一律需要搭配 Azure 資源的自訂子網域名稱使用。區域端點不支援 Microsoft Entra 驗證。

在前幾節中，我們示範如何使用 API 金鑰進行驗證。雖然這些密鑰提供快速且簡單的開發路徑，但在需要 Azure 角色型存取控制（Azure RBAC）的案例中，它們會不足。讓我們來看看使用 Microsoft Entra 識別碼進行更安全驗證所需的條件。

在下列各節中，您將使用 Azure Cloud Shell 環境或 Azure CLI 建立子網域、指派角色，並取得持有人權杖以呼叫 Azure AI 服務。如果遇到困難，每一節都會提供連結，其中包含 Azure Cloud Shell/Azure CLI 中每個命令的所有可用選項。

重要

如果您的組織透過 Microsoft Entra ID 執行驗證，您應該停用本機驗證 (使用金鑰進行驗證)，讓組織中的使用者一律必須使用 Microsoft Entra ID。

使用自訂子網域建立資源

第一個步驟是建立自訂子網域。如果您想要使用沒有自定義子域名稱的現有 AI Foundry 資源，請遵循 Azure AI 服務自定義子域中的指示，為您的資源啟用自定義子域。

從開啟 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 入口網站中註冊應用程式，就會為您完成此步驟。
最後一個步驟是指派「認知服務使用者」角色給服務主體 (範圍設定為資源)。藉由指派角色，您會將服務主體存取權授與此資源。您可以將相同的服務主體存取權授與訂用帳戶中的多個資源。

注意

系統使用的是服務主體的 ObjectId，而不是應用程式的 ObjectId。 ACCOUNT_ID將是您所建立 AI Foundry 資源的 Azure 資源識別碼。您可以從 Azure 入口網站中資源的「屬性」找到 Azure 資源識別碼。
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

範例要求

此範例會使用密碼來驗證服務主體。接著會使用提供的令牌來呼叫 Azure AI 視覺 API。

取得您的 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 等解決方案整合。

呼叫 Azure AI 視覺 API：

$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 AI 服務支援使用 Azure 資源的受控識別進行 Microsoft Entra 驗證。 Azure 資源的受控識別可以使用 Microsoft Entra 認證來授權存取 AI Foundry 資源，這些認證可以從執行於 Azure 虛擬機（VM）、函式應用程式、虛擬機擴展集及其他服務中的應用程式中獲取。藉由使用適用於 Azure 資源的受控識別搭配 Microsoft Entra 驗證，您可以避免使用在雲端執行的應用程式儲存認證。

在虛擬機器上啟用受控識別（VM）

您必須先為 VM 上的 Azure 資源啟用受控識別，才能使用 Azure 資源的受控識別來授權從 VM 存取 AI Foundry 資源。若要瞭解如何為 Azure 資源啟用受控識別，請參閱：

如需有關受控識別的詳細資訊，請參閱適用於 Azure 資源的受控識別。

使用 Azure 金鑰保存庫安全地存取認證

您可以使用 Azure Key Vault 安全地開發 Azure AI Foundry 應用程式。 Key Vault 可讓您將驗證認證儲存在雲端中，並減少祕密可能會意外洩漏的機會，因為您不會將安全性資訊儲存在應用程式中。

驗證會透過 Microsoft Entra ID 來完成。授權可透過 Azure 角色型存取控制 (Azure RBAC) 或 Key Vault 存取原則來完成。 Azure RBAC 可用於管理保存庫及存取儲存在保存庫中的資料，而金鑰保存庫存取原則只能在嘗試存取儲存在保存庫中的資料時使用。

共用方式為

驗證對 Azure AI 服務的要求

必要條件

驗證標頭

使用單一服務資源金鑰進行驗證

使用 AI Foundry 資源金鑰進行驗證

支援的區域

範例要求

使用存取權杖進行驗證

範例要求

使用 Microsoft Entra 識別碼驗證

使用自訂子網域建立資源

將角色指派給服務主體

範例要求

授權存取受控身分識別

在虛擬機器上啟用受控識別 （VM）

使用 Azure 金鑰保存庫安全地存取認證

相關內容

意見反應

其他資源

在虛擬機器上啟用受控識別（VM）