驗證 Azure 認知服務要求

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

必要條件

提出要求之前,您需要 Azure 帳戶和 Azure 認知服務訂用帳戶。 如果您已經有帳戶,請繼續進行並跳至下一節。 如果您沒有帳戶,我們會引導您在幾分鐘內完成設定:針對 Azure 建立認知服務帳戶

您可以在建立帳戶後,從 Azure 入口網站取得訂用帳戶金鑰。

驗證標頭

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

標頭 描述
Ocp-Apim-Subscription-Key 使用此標頭以特定服務的訂用帳戶金鑰或多服務訂用帳戶金鑰進行驗證。
Ocp-Apim-Subscription-Region 只有在搭配翻譯工具服務使用多重服務訂用帳戶金鑰時,才需要此標頭。 使用此標頭指定訂用帳戶區域。
授權 如果您使用存取權杖,請使用此標頭。 下列各節會詳細說明執行權杖交換的步驟。 提供的值遵循下列格式:Bearer <TOKEN>

使用單一服務訂用帳戶金鑰進行驗證

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

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

這是 Bing Web 搜尋 API 的範例呼叫:

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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

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

以下影片將示範如何使用認知服務金鑰。

使用多服務訂用帳戶金鑰進行驗證

警告

目前不支援多重服務金鑰:QnA Maker、沈浸式閱讀程式、個人化工具和異常偵測器。

此選項也會使用訂用帳戶金鑰來驗證要求。 主要差異在於,訂用帳戶金鑰未繫結至特定服務,而是單一金鑰可用來驗證多個認知服務的要求。 如需區域可用性、支援功能和定價的詳細資訊,請參閱認知服務定價

在每個要求中,訂用帳戶金鑰提供作為 Ocp-Apim-Subscription-Key 標頭。

認知服務的多服務訂用帳戶金鑰示範

支援區域

當使用多服務訂用帳戶金鑰對 api.cognitive.microsoft.com 提出要求時,您必須在 URL 中包含區域。 例如:westus.api.cognitive.microsoft.com

當搭配翻譯工具服務使用多重服務訂用帳戶金鑰時,您必須指定訂用帳戶區域與 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

範例要求

這是 Bing Web 搜尋 API 的範例呼叫:

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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

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

注意

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

向 Azure Active Directory 進行驗證

重要

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

在前幾節中,我們示範了如何使用單一服務或多重服務訂用帳戶金鑰,對 Azure 認知服務進行驗證。 雖然這些金鑰提供開始開發快速簡單的途徑,但在需要 Azure 角色型存取控制 (Azure RBAC)、較複雜的案例中就不盡理想。 接著我們要了解使用 Azure Active Directory (Azure AD) 驗證的必要條件。

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

使用自訂子網域建立資源

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

  1. 從開啟 Azure Cloud Shell 開始。 接著,選取訂用帳戶

    Set-AzContext -SubscriptionName <SubscriptionName>
    
  2. 接下來,使用自訂子網域建立認知服務資源。 子網域名稱必須是全域唯一的,且不得包含特殊字元,例如:"."、"!"、","。

    $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
    
  3. 如果成功,端點應該會顯示您資源的唯一子網域名稱。

將角色指派給服務主體

既然您已經有與資源相關聯的自訂子網域,您必須將角色指派給服務主體。

注意

請記住,Azure 角色指派最多可能需要五分鐘的時間傳播。

  1. 首先,我們要註冊 Azure AD 應用程式

    $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
    
    $app = New-AzADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -Password $SecureStringPassword
    

    在下一個步驟中,您將需要 ApplicationId

  2. 接著,您需要為 Azure AD 應用程式建立服務主體

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    注意

    如果您在 Azure 入口網站中註冊應用程式,就會為您完成此步驟。

  3. 最後一個步驟是指派「認知服務使用者」角色給服務主體 (範圍設定為資源)。 藉由指派角色,您會將服務主體存取權授與此資源。 您可以將相同的服務主體存取權授與訂用帳戶中的多個資源。

    注意

    系統使用的是服務主體的 ObjectId,而不是應用程式的 ObjectId。 ACCOUNT_ID 將會是您所建立之認知服務帳戶的 Azure 資源識別碼。 您可以從 Azure 入口網站中資源的「屬性」尋找 Azure 資源識別碼。

    New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
    

範例要求

此範例會使用密碼來驗證服務主體。 接著會使用提供的權杖來呼叫電腦視覺 API。

  1. 取得您的 TenantId

    $context=Get-AzContext
    $context.Tenant.Id
    
  2. 取得權杖:

    注意

    如果您使用 Azure Cloud Shell,就無法使用 SecureClientSecret 類別。

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
    $secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
    $clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
    $token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
    $token
    

  1. 呼叫電腦視覺 API:
    $url = $account.Endpoint+"vision/v1.0/models"
    $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -Verbose
    $result | ConvertTo-Json
    

或者,您可以使用憑證來驗證服務主體。 除了服務主體,您也可以透過另一個 Azure AD 應用程式,委派權限支援使用者主體。 在此情況下,取得權杖時,系統會提示使用者進行雙因素驗證,而不是提供密碼或憑證。

授權存取受控身分識別

認知服務支援使用適用於 Azure 資源的受控識別進行 Azure Active Directory (Azure AD) 驗證。 適用於 Azure 資源的受控識別可以從在 Azure 虛擬機器 (VM)、函式應用程式、虛擬機器擴展集及其他服務中執行的應用程式中,使用 Azure AD 認證來授權對認知服務資源的存取權。 藉由使用適用於 Azure 資源的受控識別搭配 Azure AD 驗證,您可以避免使用在雲端執行的應用程式儲存認證。

在 VM 上啟用受控識別

在您可以使用適用於 Azure 資源的受控識別授權從 VM 存取認知服務資源之前,您必須先在該 VM 上啟用適用於 Azure 資源的受控識別。 若要了解如何啟用適用於 Azure 資源的受控識別,請參閱:

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

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

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

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

另請參閱