有什么新鲜事吗?
翻译器版本 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 生成的访问 持有者令牌。
|
Ocp-Apim-Subscription-Region | 该值是 翻译器资源的区域。 |
Ocp-Apim-ResourceId | 该值是翻译器资源实例的资源 ID。
|
Translator 属性页 - 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”),并且无法使用访问令牌进行身份验证。
创建 翻译器资源 并允许从所选网络和专用终结点进行访问后,可以找到自定义终结点。
在 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?'}]"
指标
指标允许在 Azure 门户中查看翻译器使用情况和可用性信息。 有关详细信息,请参阅 数据和平台指标。
此表列出了可用指标,其中介绍了它们如何用于监视翻译 API 调用。
指标 | DESCRIPTION |
---|---|
TotalCalls | API 调用总数。 |
TotalTokenCalls | 使用身份验证令牌通过令牌服务调用的 API 调用总数。 |
SuccessfulCalls | 成功呼叫的数量。 |
TotalErrors | 具有错误响应的调用数。 |
BlockedCalls | 超过速率或配额限制的电话呼叫次数。 |
ServerErrors | 服务器内部错误(5XX)的调用数。 |
ClientErrors | 客户端错误(4XX)的调用数。 |
延迟 | 完成请求的持续时间(以毫秒为单位)。 |
CharactersTranslated | 传入的文本请求中的字符总数。 |