翻译器 3.0 版

有什么新鲜事吗？

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

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

身份验证

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

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

密钥

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

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

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

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

// 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。

多服务文本 API 订阅需要区域。 选择的区域是使用多服务密钥时可用于文本翻译的唯一区域。 它必须是通过 Azure 门户注册多服务订阅时选择的同一区域。

如果使用参数 Subscription-Key在查询字符串中传递密钥，则必须使用查询参数 Subscription-Region指定区域。

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

或者，可以交换密钥以获取访问令牌。 此令牌作为 Authorization 标头包含在每个请求中。 若要获取授权令牌，请向以下 URL 发出 POST 请求：

下面是为位于中国北部 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 服务能够验证请求客户端是否有权使用资源并完成请求。

先决条件

• 简要了解如何使用 Microsoft Entra ID进行身份验证。

• 简要了解如何 授权访问托管标识。

标题

Translator 属性页 - Azure 门户

示例

使用全局终结点

 // 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. 在“防火墙和虚拟网络”选项卡上，选择“选定的网络和专用终结点”。

   

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

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

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

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

   

下面是使用自定义终结点调用 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 位数。 常见错误代码包括：

指标

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

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