翻译器 3.0 版

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

• 音译可将一种语言的文本从一个脚本转换为另一个脚本。
• 在一个请求中翻译成多种语言。
• 在一个请求中进行语言检测、翻译和音译。
• 字典可用于查阅词条的替代翻译，查找反向翻译以及词条在上下文中使用时的示例。
• 更详细的语言检测结果。

Microsoft Translator 位于多个数据中心位置之外。 目前它们位于 4 个 Azure 地理区域：

• 中国北部、中国北部 2、中国北部 3 和中国东部 2

订阅 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 密钥对多个服务的请求进行身份验证。

在使用多服务密钥时，请求中必须包含两个身份验证标头。 调用翻译器需要 2 个标头。

区域对于多服务文本 API 订阅是必需的。 使用多服务密钥时，你所选的区域是唯一可以用于文本翻译的区域。 它必须与你在 Azure 门户上注册多服务订阅时所选的区域相同。

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

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

以下是根据给定密钥获取令牌的示例请求：

// 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。 不能使用访问令牌进行身份验证。

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

1. 在 Azure 门户中导航到“翻译器资源”。

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

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

   

4. 单击“保存”应用所做的更改。

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

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

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

   

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

// 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 调用的说明。