翻译器 3.0 版

有什么新鲜事吗?

翻译器版本 3.0 提供基于 JSON 的新式 Web API。 它通过将现有功能合并为更少的作来提高可用性和性能,并提供新功能。

  • 音译可将一种语言的文本从一个脚本转换为另一个脚本。
  • 在一个请求中翻译到多种语言。
  • 一个请求中的语言检测、翻译和音译。
  • 用于查找字词的替代翻译的字典,以查找反向翻译和示例,其中显示了上下文中使用的术语。
  • 更丰富的语言检测结果。

身份验证

在 Azure AI 服务中订阅翻译或 多服务,并使用密钥(在 Azure 门户中提供)进行身份验证。

可以使用三个标头对订阅进行身份验证。 下表介绍了如何使用每个项:

标头 DESCRIPTION
Ocp-Apim-Subscription-Key 如果传递密钥 与 Azure AI 服务订阅一起使用。
该值是订阅 Translator 的 Azure 密钥。
授权 如果传递身份验证令牌,与 Azure AI 服务订阅一起使用。
值为持有者令牌:Bearer <token>
Ocp-Apim-Subscription-Region 与多服务和区域翻译资源一起使用。
该值是多服务或区域翻译资源的区域。

密钥

第一个选项是使用 Ocp-Apim-Subscription-Key 标头进行身份验证。 将 Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> 标头添加到请求。

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

使用 区域翻译资源时,需要调用翻译器两个标头。

标头 DESCRIPTION
Ocp-Apim-Subscription-Key 该值是订阅 Translator 的 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 密钥对多个服务的请求进行身份验证。

使用多服务密钥时,必须向请求包含两个身份验证标头。 有两个标头需要调用 Translator。

标头 DESCRIPTION
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

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

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

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

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

Authorization: Bearer <Base64-access_token>

身份验证令牌有效期为 10 分钟。 对 Translator 进行多次调用时,应重复使用令牌。 但是,如果程序在较长时间内向 Translator 发出请求,则程序必须定期请求新的访问令牌(例如,每 8 分钟一次)。

使用 Microsoft Entra ID 进行身份验证

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

先决条件

标题

标题 价值
授权 该值是 Azure AD 生成的访问 持有者令牌
  • 持有者令牌提供身份验证证明,并验证客户端使用资源的授权。
  • 身份验证令牌有效期为 10 分钟,应在多次调用 Translator 时重复使用。
  • 请参阅示例请求:2。获取令牌
Ocp-Apim-Subscription-Region 该值是 翻译器资源的区域。
Ocp-Apim-ResourceId 该值是翻译器资源实例的资源 ID。
  • 可以在 Azure 门户中的 Translator 资源→属性中找到资源 ID。
  • 资源 ID 格式:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
Translator 属性页 - Azure 门户

屏幕截图:Azure 门户中的“翻译器属性”页。

重要

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

示例

使用全局终结点

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

curl -X POST "https://api.translator.azure.cn/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.cn/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.translator.azure.cn/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.cn/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.'}]"

虚拟网络支持

若要启用虚拟网络,请参阅配置 Azure AI 服务虚拟网络

启用此功能后,必须使用自定义终结点调用 Translator。 无法使用全局翻译器终结点(“api.translator.azure.cn”),并且无法使用访问令牌进行身份验证。

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

  1. 在 Azure 门户中导航到你的翻译工具资源。

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

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

    Azure 门户中虚拟网络设置的屏幕截图。

  4. 选择保存以应用更改。

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

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

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

    虚拟网络终结点的屏幕截图。

标头 DESCRIPTION
Ocp-Apim-Subscription-Key 该值是订阅 Translator 的 Azure 密钥。
Ocp-Apim-Subscription-Region 该值是翻译器资源的区域。

下面是使用自定义终结点调用 Translator 的示例请求

// 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 位数。 常见错误代码包括:

代码 DESCRIPTION
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 的凭据。 使用 Translator 的订阅。
403000 不允许此作。
403001 不允许此作,因为订阅超出了其免费配额。
405000 请求的资源不支持请求方法。
408001 正在准备所请求的翻译系统。 请在几分钟后重试。
408002 等待传入流时请求超时。 客户端没有在服务器准备等待的时间内生成请求。 客户端可以在以后的任何时间重复该请求,而不做任何修改。
415000 Content-Type 标头缺失或无效。
429000, 429001, 429002 由于客户端已超出请求限制,因此服务器拒绝了请求。
500000 发生意外错误。 如果错误仍然存在,请报告错误日期/时间、响应标头 X-RequestId 的请求标识符和请求标头 X-ClientTraceId 中的客户端标识符。
503000 服务暂时不可用。 再重试。 如果错误仍然存在,请报告错误日期/时间、响应标头 X-RequestId 的请求标识符和请求标头 X-ClientTraceId 中的客户端标识符。

指标

指标允许在 Azure 门户中查看翻译器使用情况和可用性信息。 有关详细信息,请参阅 数据和平台指标

翻译器指标

此表列出了可用指标,其中介绍了它们如何用于监视翻译 API 调用。

指标 DESCRIPTION
TotalCalls API 调用总数。
TotalTokenCalls 使用身份验证令牌通过令牌服务调用的 API 调用总数。
SuccessfulCalls 成功呼叫的数量。
TotalErrors 具有错误响应的调用数。
BlockedCalls 超过速率或配额限制的电话呼叫次数。
ServerErrors 服务器内部错误(5XX)的调用数。
ClientErrors 客户端错误(4XX)的调用数。
延迟 完成请求的持续时间(以毫秒为单位)。
CharactersTranslated 传入的文本请求中的字符总数。