翻译器 3.0 版

  • 项目

新增功能

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

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

基 URL

Microsoft Translator 位于多个数据中心位置之外。 目前它们位于 4 个 Azure 地理区域：

  • 中国北部、中国北部 2、中国北部 3 和中国东部 2

身份验证

订阅 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 密钥。
Ocp-Apim-Subscription-Region 该值是翻译器资源的区域。

下面是使用区域翻译器资源调用翻译器的示例请求：

// Pass secret key and region using headers
curl -X POST "https://api.translator.azure.cn/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://<your-region>.api.cognitive.azure.cn/sts/v1.0/issueToken

以下是根据给定密钥获取令牌的示例请求：

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

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

下面是根据位于中国北部的区域资源的密钥获取令牌的示例请求：

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

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

成功的请求会在响应正文中将编码的访问令牌作为纯文本返回。 有效的令牌在授权中作为持有者令牌传递给翻译器服务。

Authorization: Bearer <Base64-access_token>

身份验证令牌的有效期为 10 分钟。 在对翻译器进行多次调用时，应重复使用该令牌。 但是，如果程序向 Translator 发出请求时持续的时间段很长，则该程序必须定期请求新的访问令牌（例如，每隔 8 分钟请求一次）。

虚拟网络支持

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

启用此功能后，必须使用自定义终结点来调用 Translator。 不能使用访问令牌进行身份验证。

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

  1. 在 Azure 门户中导航到“翻译器资源”。

  2. 从“资源管理”部分选择“网络”。

  3. 在“防火墙和虚拟网络”选项卡上，选择“选定的网络和专用终结点”。

    Screenshot of the virtual network setting in the Azure portal.

  4. 单击“保存”应用所做的更改。

  5. 从“资源管理”部分选择“密钥和终结点”。

  6. 选择“虚拟网络”选项卡。

  7. 其中列出了文本翻译和文档翻译的终结点。

    Screenshot of the virtual network endpoint.

头文件 说明
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.cn/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-ClientTranceId 标头）缺失或无效。
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 Metrics

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

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