驗證 Azure 認知服務要求Authenticate requests to Azure Cognitive Services

Azure 認知服務的每個要求必須包含驗證標頭。Each request to an Azure Cognitive Service must include an authentication header. 此標頭會與訂用帳戶金鑰或存取權杖一起傳遞,用來驗證您的服務或服務群組訂閱。This header passes along a subscription key or access token, which is used to validate your subscription for a service or group of services. 在本文中,您將了解驗證要求的三種方式及各自的需求。In this article, you'll learn about three ways to authenticate a request and the requirements for each.

必要條件Prerequisites

提出要求之前,您需要 Azure 帳戶和 Azure 認知服務訂用帳戶。Before you make a request, you need an Azure account and an Azure Cognitive Services subscription. 如果您已經有帳戶,請繼續進行並跳至下一節。If you already have an account, go ahead and skip to the next section. 如果您還沒有帳戶,我們會引導您在數分鐘內完成設定:針對 Azure 建立認知服務帳戶If you don't have an account, we have a guide to get you set up in minutes: Create a Cognitive Services account for Azure.

您可以取得您的訂用帳戶金鑰Azure 入口網站建立您的帳戶,或啟動之後免費試用You can get your subscription key from the Azure portal after creating your account, or activating a free trial.

驗證標頭Authentication headers

讓我們快速檢閱適用於 Azure 認知服務的驗證標頭。Let's quickly review the authentication headers available for use with Azure Cognitive Services.

頁首Header 描述Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 使用此標頭以特定服務的訂用帳戶金鑰或多服務訂用帳戶金鑰進行驗證。Use this header to authenticate with a subscription key for a specific service or a multi-service subscription key.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region 只有在搭配翻譯工具文字 API 使用多服務訂用帳戶金鑰時才需要此標頭。This header is only required when using a multi-service subscription key with the Translator Text API. 使用此標頭指定訂用帳戶區域。Use this header to specify the subscription region.
AuthorizationAuthorization 如果您使用驗證權杖,請使用此標頭。Use this header if you are using an authentication token. 下列各節會詳細說明執行權杖交換的步驟。The steps to perform a token exchange are detailed in the following sections. 提供的值遵循下列格式:Bearer <TOKEN>The value provided follows this format: Bearer <TOKEN>.

使用單一服務訂用帳戶金鑰進行驗證Authenticate with a single-service subscription key

第一個選項是使用特定服務 (例如翻譯工具文字) 的訂用帳戶金鑰來驗證要求。The first option is to authenticate a request with a subscription key for a specific service, like Translator Text. 金鑰適用於 Azure 入口網站中您建立的每個資源。The keys are available in the Azure portal for each resource that you've created. 若要使用訂用帳戶金鑰來驗證要求,它必須傳遞以作為 Ocp-Apim-Subscription-Key 標頭。To use a subscription key to authenticate a request, it must be passed along as the Ocp-Apim-Subscription-Key header.

這些範例要求示範如何使用 Ocp-Apim-Subscription-Key 標頭。These sample requests demonstrates how to use the Ocp-Apim-Subscription-Key header. 請記住,當使用此範例時,您必須包含有效的訂用帳戶金鑰。Keep in mind, when using this sample you'll need to include a valid subscription key.

這是 Bing Web 搜尋 API 的範例呼叫:This is a sample call to the Bing Web Search 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

這是翻譯工具文字 API 的範例呼叫:This is a sample call to the Translator Text API:

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

以下影片將示範如何使用認知服務金鑰。The following video demonstrates using a Cognitive Services key.

使用多服務訂用帳戶金鑰進行驗證Authenticate with a multi-service subscription key

警告

目前,以下服務支援多服務金鑰:QnA Maker、語音服務及自訂視覺。At this time, these services don't support multi-service keys: QnA Maker, Speech Services, and Custom Vision.

此選項也會使用訂用帳戶金鑰來驗證要求。This option also uses a subscription key to authenticate requests. 主要差異在於,訂用帳戶金鑰未繫結至特定服務,而是單一金鑰可用來驗證多個認知服務的要求。The main difference is that a subscription key is not tied to a specific service, rather, a single key can be used to authenticate requests for multiple Cognitive Services. 如需區域可用性、支援功能和定價的詳細資訊,請參閱認知服務定價See Cognitive Services pricing for information about regional availability, supported features, and pricing.

在每個要求中,訂用帳戶金鑰提供作為 Ocp-Apim-Subscription-Key 標頭。The subscription key is provided in each request as the Ocp-Apim-Subscription-Key header.

認知服務的多服務訂用帳戶金鑰示範Multi-service subscription key demonstration for Cognitive Services

支援區域Supported regions

當使用多服務訂用帳戶金鑰對 api.cognitive.microsoft.com 提出要求時,您必須在 URL 中包含區域。When using the multi-service subscription key to make a request to api.cognitive.microsoft.com, you must include the region in the URL. 例如: westus.api.cognitive.microsoft.comFor example: westus.api.cognitive.microsoft.com.

當搭配翻譯工具文字 API 使用多服務訂用帳戶金鑰時,您必須指定訂用帳戶區域與 Ocp-Apim-Subscription-Region 標頭。When using multi-service subscription key with the Translator Text API, you must specify the subscription region with the Ocp-Apim-Subscription-Region header.

在以下區域中支援多服務驗證:Multi-service authentication is supported in these regions:

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

範例要求Sample requests

這是 Bing Web 搜尋 API 的範例呼叫:This is a sample call to the Bing Web Search 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

這是翻譯工具文字 API 的範例呼叫:This is a sample call to the Translator Text API:

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

使用驗證權杖進行驗證Authenticate with an authentication token

某些 Azure 認知服務接受驗證權杖,而在某些情況下更是需要驗證權杖。Some Azure Cognitive Services accept, and in some cases require, an authentication token. 目前,以下服務支援驗證權杖:Currently, these services support authentication tokens:

  • 文字翻譯 APIText Translation API
  • 語音服務:語音轉換文字 REST APISpeech Services: Speech-to-text REST API
  • 語音服務:文字轉換語音 REST APISpeech Services: Text-to-speech REST API

注意

QnA Maker 也會使用授權標頭,但需要端點金鑰。QnA Maker also uses the Authorization header, but requires an endpoint key. 如需詳細資訊,請參閱 QnA Maker:從知識庫中獲得答案For more information, see QnA Maker: Get answer from knowledge base.

警告

支援驗證權杖的服務可能會隨著時間變更,請在使用此驗證方法之前,檢查服務的 API 參考。The services that support authentication tokens may change over time, please check the API reference for a service before using this authentication method.

單一服務和多服務訂用帳戶金鑰都可以交換驗證權杖。Both single service and multi-service subscription keys can be exchanged for authentication tokens. 驗證權杖的有效時間為 10 分鐘。Authentication tokens are valid for 10 minutes.

驗證權杖會包含在要求中作為 Authorization 標頭。Authentication tokens are included in a request as the Authorization header. 提供的權杖值前面必須加上 Bearer,例如:Bearer YOUR_AUTH_TOKENThe token value provided must be preceded by Bearer, for example: Bearer YOUR_AUTH_TOKEN.

範例要求Sample requests

使用此 URL 來交換驗證權杖的訂用帳戶金鑰:https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueTokenUse this URL to exchange a subscription key for an authentication token: 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"

以下多服務區域支援權杖交換:These multi-service regions support token exchange:

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

取得驗證權杖之後,您必須在每個要求中加以傳遞作為 Authorization 標頭。After you get an authentication token, you'll need to pass it in each request as the Authorization header. 這是翻譯工具文字 API 的範例呼叫:This is a sample call to the Translator Text API:

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

請參閱See also