共用方式為

身份驗證與授權

每個對 Foundry 工具的請求都必須包含認證標頭。 此標頭會與資源金鑰或驗證權杖一起傳遞，用來驗證您服務或服務群組的訂用帳戶。 在本文中，您可以探索驗證要求的方式，以及每個要求的需求。

標題

訂閱 Translator 或 Foundry Tools 的 多元服務 ，並使用你的金鑰（可在 Azure 入口網站取得）來認證。

有三個標頭可用來驗證訂用帳戶。 下表描述如何使用每個專案：

標題 說明
Ocp-Apim-Subscription-Key 如果你要傳遞你的秘密金鑰，請使用 Foundry Tools 訂閱。
此值是翻譯工具訂用帳戶的 Azure 秘密金鑰。
授權 如果你要傳遞認證令牌，請使用 Foundry Tools 訂閱。
值為持有人令牌： Bearer <token>。
Ocp-Apim-Subscription-Region 搭配多服務和區域翻譯工具資源使用。
此值是多服務或區域翻譯工具資源的區域。 使用全域翻譯工具資源時，這個值是選擇性的。

秘密金鑰

第一個選項是使用 Ocp-Apim-Subscription-Key 標頭進行驗證。 將 Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> 標頭新增至您的要求。

使用全域資源進行驗證

當您使用 全域翻譯工具資源時，您需要包含一個標頭來呼叫翻譯工具。

標題 說明
Ocp-Apim-Subscription-Key 此值是翻譯工具訂用帳戶的 Azure 秘密金鑰。

以下是使用全域翻譯工具資源呼叫翻譯工具的範例要求

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

使用區域資源進行驗證

當您使用 區域翻譯工具資源時，您需要呼叫翻譯工具兩個標頭。

標題 說明
Ocp-Apim-Subscription-Key 此值是翻譯工具訂用帳戶的 Azure 秘密金鑰。
Ocp-Apim-Subscription-Region 此值是翻譯工具資源的區域。

以下是使用區域翻譯工具資源呼叫翻譯工具的範例要求

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"

使用多服務資源進行驗證

多服務資源可讓您使用單一 API 金鑰來驗證多個服務的要求。

當您使用多服務秘密金鑰時，您必須在要求中包含兩個驗證標頭。 您需要呼叫翻譯工具兩個標頭。

標題 說明
Ocp-Apim-Subscription-Key 此值是多服務資源的 Azure 秘密金鑰。
Ocp-Apim-Subscription-Region 此值是多服務資源的區域。

多服務文字 API 訂用帳戶需要區域。 您選取的區域是唯一可在使用多重服務金鑰時用於文字翻譯的區域。 當您透過 Azure 入口網站註冊多服務訂用帳戶時，它必須是您選取的相同區域。

如果您使用 參數 Subscription-Key在查詢字串中傳遞秘密金鑰，則必須使用查詢參數 Subscription-Region來指定區域。

使用存取令牌進行驗證

或者，您可以交換秘密金鑰以取得存取令牌。 此令牌隨附於每個要求作為 Authorization 標頭。 若要取得授權令牌，請向下列URL提出 POST 要求：

資源類型 驗證服務 URL
全球 https://api.cognitive.microsoft.com/sts/v1.0/issueToken
區域或多服務 https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

以下是針對全域資源取得指定秘密密鑰之令牌的範例要求：

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

以下是針對位於美國中部的區域資源取得令牌的範例要求：

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

成功的要求會將編碼存取令牌當做回應本文中的純文本傳回。 有效的令牌會作為授權時的持有人令牌傳遞給轉譯器。

Authorization: Bearer <Base64-access_token>

驗證令牌的有效期限為10分鐘。 對翻譯工具進行多次呼叫時，應該重複使用令牌。 不過，如果您的程式在較長時間內對翻譯工具提出要求，則您的程式必須定期要求新的存取令牌（例如每 8 分鐘）。

使用 Microsoft Entra ID驗證

翻譯工具 v3.0 支援Microsoft Entra 驗證，Microsoft的雲端式身分識別和存取管理解決方案。 授權標頭讓轉譯器驗證請求的客戶端是否有權使用該資源並完成請求。

先決條件

Microsoft Entra ID 標頭

頁首 價值觀
授權 值是Microsoft Entra ID 所產生的存取 持有人令牌 。
  • 持有人令牌提供驗證證明，並驗證用戶端使用資源的授權。
  • 驗證令牌的有效期限為10分鐘，且在對Translator進行多次呼叫時應該重複使用。
    • 請參閱範例要求：2。取得令牌
Ocp-Apim-Subscription-Region 此值是 翻譯工具資源的區域。
  • 如果資源是全域的，這個值是選擇性的。
Ocp-Apim-ResourceId 此值是翻譯工具資源實例的資源標識碼。
  • 您可以在 Azure 入口網站的 [ 翻譯工具資源] → [屬性] 中找到資源識別碼。
  • 資源標識符格式：
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
翻譯工具屬性頁 — Azure 入口網站

螢幕快照：Azure 入口網站中的翻譯工具屬性頁面。

這很重要

將 認知服務使用者 角色指派給服務主體。 藉由指派此角色，您會將翻譯工具資源的存取權授與服務主體。

範例

使用全域端點

// Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

使用您的自定義端點

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

使用受控識別的範例

Translator v3.0 也支持授權存取受控識別。 如果已啟用翻譯工具資源的受控識別，您可以在要求標頭中傳遞受控識別所產生的持有人令牌。

使用全域端點

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Ocp-Apim-ResourceId: <Resource ID>" \
    -H "Ocp-Apim-Subscription-Region: <your-region>" \
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

使用您的自定義端點

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
    -H "Authorization: Bearer <Base64-access_token>"\
    -H "Content-Type: application/json" \
    -data-raw "[{'Text':'Hello, friend.'}]"

虛擬網路支援

Translator 現已在 Azure 公共雲的所有區域提供虛擬網路（Virtual Network）VNET功能。 要啟用虛擬網路， 請參見配置 Foundry 工具虛擬網路。

開啟這項功能之後，您必須使用自定義端點來呼叫翻譯工具。 您無法使用全域翻譯工具端點 （“api.cognitive.microsofttranslator.com”），且無法使用存取令牌進行驗證。

您可以在建立 翻譯工具資源 並允許從選取的網路和私人端點存取之後，找到自定義端點。

  1. 在 Azure 入口網站中瀏覽至您的翻譯工具資源。

  2. 從 [資源管理] 區段中選取 [網路]。

  3. 在 [防火牆與虛擬網路] 索引標籤下，選擇 [選取的網路與私人端點]。

    Azure 入口網站中虛擬網路設定的螢幕快照。

  4. 選取 [儲存] 以套用變更。

  5. 從 [資源管理] 區段選取 [金鑰和端點]。

  6. 選取 [虛擬網络] 索引標籤 。

  7. 列出文字翻譯和文件翻譯的端點。

    虛擬網路端點的螢幕快照。

標題 說明
Ocp-Apim-Subscription-Key 此值是翻譯工具訂用帳戶的 Azure 秘密金鑰。
Ocp-Apim-Subscription-Region 此值是翻譯工具資源的區域。 如果資源為 ，這個值是選擇性的 global

以下是使用自定義端點呼叫翻譯工具的範例要求

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
    -H "Ocp-Apim-Subscription-Key:<your-key>" \
    -H "Ocp-Apim-Subscription-Region:<your-region>" \
    -H "Content-Type: application/json" \
    -d "[{'Text':'Hello, what is your name?'}]"
  • Last updated on