翻译器 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。 不能使用访问令牌进行身份验证。
你可以在创建翻译器资源后找到自定义终结点,并允许从所选网络和专用终结点进行访问。
在 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.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 门户中的指标部分下查看翻译器的使用情况和可用性信息,如以下屏幕截图所示。 有关详细信息,请参阅数据和平台指标。
此表列出了可用的指标,以及有关如何使用它们来监视翻译 API 调用的说明。
指标 | 说明 |
---|---|
TotalCalls | API 调用总数。 |
TotalTokenCalls | 使用身份验证令牌通过令牌服务进行的 API 调用的总数。 |
SuccessfulCalls | 成功调用数。 |
TotalErrors | 产生了错误响应的调用数。 |
BlockedCalls | 超过速率或配额限制的调用数。 |
ServerErrors | 产生了服务器内部错误 (5XX) 的调用数。 |
ClientErrors | 引发客户端错误 (4XX) 的调用数。 |
延迟 | 完成请求的持续时间(毫秒)。 |
CharactersTranslated | 传入的文本请求中的字符总数。 |