驗證對 Azure AI 服務的要求

發行項
10/16/2024

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

使用單一服務或多服務資源金鑰進行驗證
使用權杖進行驗證
使用 Microsoft Entra ID 進行驗證

必要條件

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

移至您在 Azure 入口網站中的資源。您可以在 [資源管理] 區段中找到 [金鑰和端點] 區段。複製您的端點和存取金鑰，因為您需要這兩者才能驗證 API 呼叫。您可以使用 KEY1 或 KEY2。隨時持有兩個金鑰可讓您安全地輪替和重新產生金鑰，而不會造成服務中斷。

驗證標頭

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

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

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

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

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

支援的區域

當使用 Azure AI 多服務資源金鑰對 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

範例要求

這是對 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 參考。

可以將單一服務和多服務資源金鑰交換為驗證權杖。驗證權杖的有效時間為 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 標頭。這是對 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 驗證。

在前幾節中，我們示範了如何使用單一服務或多服務訂用帳戶金鑰來向 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 Key Vault 等解決方案整合。

呼叫電腦視覺 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 服務應用程式。 Key Vault 可讓您將驗證認證儲存在雲端中，並減少祕密可能會意外洩漏的機會，因為您不會將安全性資訊儲存在應用程式中。

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

共用方式為

驗證對 Azure AI 服務的要求

必要條件

驗證標頭

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

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

支援的區域

範例要求

使用存取權杖進行驗證

範例要求

使用 Microsoft Entra 識別碼驗證

使用自訂子網域建立資源

將角色指派給服務主體

範例要求

授權存取受控身分識別

在 VM 上啟用受控識別

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

另請參閱

意見反應

其他資源