翻译器版本 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 分钟一次)。
v3.0 翻译器支持Microsoft Entra 身份验证,Microsoft基于云的标识和访问管理解决方案。 授权标头使 Translator 服务能够验证请求客户端是否有权使用资源并完成请求。
简要了解如何 授权访问托管标识。
标题 | 价值 |
---|---|
授权 | 该值是 Azure AD 生成的访问 持有者令牌。
|
Ocp-Apim-Subscription-Region | 该值是 翻译器资源的区域。 |
Ocp-Apim-ResourceId | 该值是翻译器资源实例的资源 ID。
|
重要
将 认知服务用户 角色分配给服务主体。 通过分配此角色,你将向服务主体授予对 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”),并且无法使用访问令牌进行身份验证。
创建 翻译器资源 并允许从所选网络和专用终结点进行访问后,可以找到自定义终结点。
在 Azure 门户中导航到你的翻译工具资源。
从“资源管理”部分选择“网络”。
在“防火墙和虚拟网络”选项卡上,选择“选定的网络和专用终结点”。
选择保存以应用更改。
从 资源管理 部分选择 密钥和终结点。
选择 虚拟网络 选项卡。
列出了文本翻译和文档翻译的终结点。
标头 | 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 | 传入的文本请求中的字符总数。 |