你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

翻译器 3.0 版

项目
09/01/2024

新增功能

翻译器的版本 3.0 提供了基于 JSON 的新型 Web API。它通过将现有功能合并到更少的操作中来提高可用性和性能，并提供新功能。

音译可将一种语言的文本从一个脚本转换为另一个脚本。
在一个请求中翻译成多种语言。
在一个请求中进行语言检测、翻译和音译。
字典可用于查阅词条的替代翻译，查找反向翻译以及词条在上下文中使用时的示例。
更详细的语言检测结果。

基 URL

在大多数情况下，对翻译器的请求由距离请求的来源位置最近的数据中心处理。如果使用全局终结点时发生数据中心故障，则请求可能会路由到该地域之外。

若要强制请求在特定的地域内处理，请使用所需的地理终结点。所有请求均在该地域内的数据中心之间进行处理。

✔️ 功能：文本翻译

服务终结点	请求处理数据中心
全球（推荐）： `api.cognitive.microsofttranslator.com`	最近的可用数据中心。
美洲： `api-nam.cognitive.microsofttranslator.com`	美国东部 2 • 美国西部 2
亚太： `api-apc.cognitive.microsofttranslator.com`	日本东部 • 东南亚
欧洲（瑞士除外）： `api-eur.cognitive.microsofttranslator.com`	法国中部 • 西欧
瑞士：有关详细信息，请参阅瑞士服务终结点。	瑞士北部 • 瑞士西部

瑞士服务终结点

资源位于瑞士北部或瑞士西部的客户可以确保其文本 API 请求在瑞士境内得到处理。为了确保请求在瑞士得到处理，请在 Resource regionSwitzerland North 或 Switzerland West 创建翻译器资源，然后在 API 请求中使用该资源的自定义终结点。

例如：如果在 Azure 门户中 Resource region 为 Switzerland North 的情况下创建翻译器资源，并且资源名称为 my-swiss-n，则自定义终结点为 https://my-swiss-n.cognitiveservices.azure.com。要转换的示例请求如下：

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

自定义翻译工具目前在瑞士不可用。

身份验证

订阅 AI 服务中的翻译器或多服务，并使用你的密钥（在 Azure 门户中提供）进行身份验证。

有三个标头可用于对你的订阅进行身份验证。下表介绍了每个标头的使用方式：

标头	说明
Ocp-Apim-Subscription-Key	如果要传递密钥，请与 Azure AI 服务订阅一起使用。该值是用于翻译器订阅的 Azure 密钥。
授权	如果要传递身份验证令牌，请与 Azure AI 服务订阅一起使用。该值是持有者令牌：`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 密钥对多个服务的请求进行身份验证。

在使用多服务密钥时，请求中必须包含两个身份验证标头。调用翻译器需要 2 个标头。

标头	说明
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 分钟。在对翻译器进行多次调用时，应重复使用该令牌。但是，如果程序向 Translator 发出请求时持续的时间段很长，则该程序必须定期请求新的访问令牌（例如，每隔 8 分钟请求一次）。

使用 Microsoft Entra ID 进行身份验证

Translator v3.0 支持 Microsoft Entra 身份验证，即 Microsoft 的基于云的标识和访问管理解决方案。使用授权标头，翻译器服务可以验证请求客户端是否有权使用资源并完成请求。

先决条件

简要了解如何使用 Microsoft Entra ID 进行身份验证。
简要了解如何授权访问托管标识。

标头

标头	值
授权	此值是由 Azure AD 生成的访问持有者令牌。持有者令牌提供身份验证证明，并验证客户端是否有权使用资源。身份验证令牌的有效期为 10 分钟，应在对翻译器进行多次调用时重复使用。请参阅示例请求：2.获取令牌
Ocp-Apim-Subscription-Region	此值是翻译工具资源的区域。如果资源为全局资源，则此值是可选项。
Ocp-Apim-ResourceId	此值是翻译工具资源实例的资源 ID。可在 Azure 门户的“翻译器资源”→“属性”中找到资源 ID。资源 ID 格式： /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Translator 属性页 - Azure 门户

屏幕截图：Azure 门户中的 Translator 属性页。

重要

将认知服务用户角色分配给服务主体。通过分配此角色，你将向服务主体授予对 Translator 资源的访问权限。

示例

使用全局终结点

 // 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.'}]"

使用托管标识的示例

翻译器 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.'}]"

虚拟网络支持

翻译器服务现在随虚拟网络 (VNET) 功能在 Azure 公有云的所有区域中提供。若要启用虚拟网络，请参阅配置 Azure AI 服务虚拟网络。

启用此功能后，必须使用自定义终结点来调用 Translator。你不能使用全球翻译工具终结点（“api.cognitive.microsofttranslator.com”），也不能使用访问令牌进行身份验证。

你可以在创建翻译器资源后找到自定义终结点，并允许从所选网络和专用终结点进行访问。

在 Azure 门户中导航到“翻译器资源”。
从“资源管理”部分选择“网络”。
在“防火墙和虚拟网络”选项卡下，选择“选定的网络和专用终结点”。
单击“保存”应用所做的更改。
从“资源管理”部分选择“密钥和终结点”。
选择“虚拟网络”选项卡。
其中列出了文本翻译和文档翻译的终结点。

头文件	说明
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?'}]"

错误

标准错误响应是具有名为 error 的名称/值对的 JSON 对象。该值也是具有以下属性的 JSON 对象：

code：服务器定义的错误代码。
message：一个提供人类可读的错误表示形式的字符串。

例如，拥有免费试用版订阅的客户会在免费配额用尽后收到以下错误：

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

错误代码是一个 6 位数字，包括 3 位数的 HTTP 状态代码，后接用于进一步将错误分类的 3 位数。常见错误代码包括：

代码	说明
400000	某个请求输入无效。
400001	“scope”参数无效。
400002	“category”参数无效。
400003	语言说明符缺失或无效。
400004	目标脚本说明符（“To script”）缺失或无效。
400005	输入文本缺失或无效。
400006	语言和脚本的组合无效。
400018	源脚本说明符（“From script”）缺失或无效。
400019	指定的某个语言不受支持。
400020	输入文本数组中的某个元素无效。
400021	API 版本参数缺失或无效。
400023	指定的某个语言对无效。
400035	源语言（“From”字段）无效。
400036	目标语言（“To”字段）缺失或无效。
400042	指定的某个选项（“Options”字段）无效。
400043	客户端跟踪 ID（ClientTraceId 字段或 X-ClientTraceId 标头）缺失或无效。
400050	输入文本过长。查看请求限制。
400064	“translation”参数缺失或无效。
400070	目标脚本（ToScript 参数）的数目与目标语言（To 参数）的数目不匹配。
400071	TextType 的值无效。
400072	输入文本的数组包含过多的元素。
400073	脚本参数无效。
400074	请求正文是无效的 JSON。
400075	语言对和类别组合无效。
400077	超过了最大请求大小。查看请求限制。
400079	请求用于在源语言与目标语言之间进行翻译的自定义系统不存在。
400080	语言或脚本不支持音译。
401000	由于凭据缺失或无效，请求未授权。
401015	“提供的凭据适用于语音 API。此请求需要文本 API 的凭据。请使用翻译器订阅。”
403000	不允许执行该操作。
403001	由于订阅已超过其免费配额，因此不允许该操作。
405000	请求的资源不支持该请求方法。
408001	正在准备所请求的翻译系统。请在几分钟后重试。
408002	等待传入流时请求超时。客户端没有在服务器准备等待的时间内生成请求。客户端可以在以后的任何时间重复该请求，而不做任何修改。
415000	Content-Type 标头缺失或无效。
429000、429001、429002	由于客户端已超出请求限制，服务器拒绝了请求。
500000	发生了意外错误。如果该错误持续出现，请报告发生错误的日期/时间、响应标头 X-RequestId 中的请求标识符，以及请求标头 X-ClientTraceId 中的客户端标识符。
503000	服务暂时不可用。请重试。如果该错误持续出现，请报告发生错误的日期/时间、响应标头 X-RequestId 中的请求标识符，以及请求标头 X-ClientTraceId 中的客户端标识符。

指标

利用指标，可以在 Azure 门户中的指标部分下查看翻译器的使用情况和可用性信息，如以下屏幕截图所示。有关详细信息，请参阅数据和平台指标。

Translator 指标

此表列出了可用的指标，以及有关如何使用它们来监视翻译 API 调用的说明。

指标	说明
TotalCalls	API 调用总数。
TotalTokenCalls	使用身份验证令牌通过令牌服务进行的 API 调用的总数。
SuccessfulCalls	成功调用数。
TotalErrors	产生了错误响应的调用数。
BlockedCalls	超过速率或配额限制的调用数。
ServerErrors	产生了服务器内部错误 (5XX) 的调用数。
ClientErrors	引发客户端错误 (4XX) 的调用数。
延迟	完成请求的持续时间（毫秒）。
CharactersTranslated	传入的文本请求中的字符总数。

通过

翻译器 3.0 版

新增功能

基 URL

瑞士服务终结点

身份验证

密钥

使用全球资源进行身份验证

使用区域资源进行身份验证

使用多服务资源进行身份验证

使用访问令牌进行身份验证

使用 Microsoft Entra ID 进行身份验证

先决条件

标头

Translator 属性页 - Azure 门户

示例

使用全局终结点

使用自定义终结点

使用托管标识的示例

使用全局终结点

使用自定义终结点

虚拟网络支持

错误

指标

反馈

其他资源