驗證對 Azure AI 服務的要求

發行項
01/10/2024

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

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

必要條件

提出要求之前，您需要 Azure 帳戶和 Azure AI 服務訂用帳戶。如果您已經有帳戶，請繼續進行並跳至下一節。如果沒有帳戶，我們有可在幾分鐘內引導您完成設定的指南：建立多服務資源 (部分機器翻譯)。

驗證標頭

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

標頭	描述
Ocp-Apim-Subscription-Key	使用此標頭搭配資源金鑰來為特定服務或多服務資源金鑰進行驗證。
Ocp-Apim-Subscription-Region	只有在搭配翻譯工具服務使用多服務資源金鑰時，才需要此標頭。使用此標頭以指定資源區域。
授權	如果您使用存取令牌，請使用此標頭。執行令牌交換的步驟詳述於下列各節。所提供的值會遵循下列格式： `Bearer <TOKEN>`。

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

第一個選項是使用資源金鑰來為特定服務 (例如翻譯工具) 驗證要求。您建立的每個資源都可以在 Azure 入口網站中取得金鑰。若要使用資源金鑰來驗證要求，它必須作為 Ocp-Apim-Subscription-Key 標頭一起傳遞。

這些範例要求示範如何使用 Ocp-Apim-Subscription-Key 標頭。請記住，當使用此範例時，您必須包含有效的資源金鑰。

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

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

以下影片示範如何使用 Azure AI 服務金鑰。

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

您可以使用多服務資源金鑰來驗證要求。主要差異在於多服務資源金鑰並未繫結至特定服務，而是可以使用單一金鑰來驗證多個 Azure AI 服務的要求。如需區域可用性、支援功能和定價的詳細資訊，請參閱 Azure AI 服務定價。

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

支援的區域

當使用多服務資源金鑰對 api.cognitive.microsoft.com 提出要求時，您必須在 URL 中包含區域。例如： westus.api.cognitive.microsoft.com 。

當搭配 Azure AI 翻譯工具使用多服務資源金鑰時，您必須指定具有 Ocp-Apim-Subscription-Region 標頭的資源區域。

這些區域支援多重服務驗證：

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

範例要求

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

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

注意

QnA Maker 也會使用授權標頭，但需要端點密鑰。如需詳細資訊，請參閱 QnA Maker：從知識庫取得答案。

警告

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

可以將單一服務和多服務資源金鑰交換為驗證權杖。驗證令牌的有效期限為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"

這些多服務區域支援令牌交換：

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

取得存取令牌之後，您必須將它傳入每個要求作為 Authorization 標頭。這是對翻譯工具服務的範例呼叫：

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 驗證。

在前幾節中，我們示範了如何使用單一服務或多服務訂用帳戶金鑰來向 Azure AI 服務進行驗證。雖然這些密鑰提供快速且簡單的開始開發路徑，但在需要 Azure 角色型存取控制（Azure RBAC）的較複雜案例中，它們會不足。讓我們看看使用 Microsoft Entra ID 進行驗證所需的專案。

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

重要

如果您的組織透過 Microsoft Entra ID 執行驗證，您應該停用本機驗證（使用密鑰進行驗證），讓組織中的使用者一律使用 Microsoft Entra ID。

使用自訂子域建立資源

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

從開啟 Azure Cloud Shell 開始。然後選取訂用帳戶：
```
Set-AzContext -SubscriptionName <SubscriptionName>
```

接下來，使用自訂子網域建立 Azure AI 服務資源。子域名稱必須是全域唯一的，而且不能包含特殊字元，例如：“.”、“！”、“，”。

$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 將會是您所建立之 Azure AI 服務帳戶的 Azure 資源識別碼。您可以在 Azure 入口網站中找到資源「屬性」中的 Azure 資源識別碼。
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

範例要求

在此範例中，會使用密碼來驗證服務主體。接著會使用提供的令牌來呼叫電腦視覺 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 KeyVault 等解決方案整合。

呼叫電腦視覺 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 資源的受控識別可以使用 Azure 虛擬機（VM）、函式應用程式、虛擬機擴展集和其他服務中執行的應用程式，使用 Microsoft Entra 認證來授權存取 Azure AI 服務資源。藉由使用 Azure 資源的受控識別與 Microsoft Entra 驗證，您可以避免將認證與在雲端中執行的應用程式一起儲存。

在 VM 上啟用受控識別

在您可以使用 Azure 資源受控識別對來自 VM 的 Azure AI 服務資源驗證存取權之前，必須先在該 VM 上啟用 Azure 資源受控識別。若要瞭解如何啟用 Azure 資源的受控識別，請參閱：

如需受控識別的詳細資訊，請參閱 Azure 資源的受控識別。

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

您可以使用 Azure Key Vault 安全地開發 Azure AI 服務應用程式。金鑰保存庫可讓您將驗證認證儲存在雲端中，並減少秘密可能會意外外泄的機會，因為您不會將安全性資訊儲存在應用程式中。

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

驗證對 Azure AI 服務的要求

必要條件

驗證標頭

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

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

支援的區域

範例要求

使用存取令牌進行驗證

範例要求

使用 Microsoft Entra 識別碼驗證

使用自訂子域建立資源

將角色指派給服務主體

範例要求

授權存取受控識別

在 VM 上啟用受控識別

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

另請參閱

其他資源