您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

文本翻译 API v3.0Translator Text API v3.0

新增功能What's new?

文本翻译 API 版本 3 提供了基于 JSON 的新型 Web API。Version 3 of the Translator Text API provides a modern JSON-based Web API. 它通过将现有功能合并到更少的操作中来提高可用性和性能,并提供新功能。It improves usability and performance by consolidating existing features into fewer operations and it provides new features.

  • 音译可将一种语言的文本从一个脚本转换为另一个脚本。Transliteration to convert text in one language from one script to another script.
  • 在一个请求中翻译成多种语言。Translation to multiple languages in one request.
  • 在一个请求中进行语言检测、翻译和音译。Language detection, translation, and transliteration in one request.
  • 字典可查找术语的替代翻译,可查找反向翻译以及显示上下文中使用的术语的示例。Dictionary to lookup alternative translations of a term, to find back-translations and examples showing terms used in context.
  • 更详细的语言检测结果。More informative language detection results.

基 URLBase URLs

Microsoft Translator 位于多个数据中心位置之外。Microsoft Translator is served out of multiple datacenter locations. 目前位于 6 个 Azure 区域中:Currently they are located in 6 Azure regions:

  • 美洲: 美国西部 2 和美国中西部Americas: West US 2 and West Central US
  • 亚太区: 亚洲东南部和韩国南部Asia Pacific: Southeast Asia and Korea South
  • 欧洲: 欧洲北部和欧洲西部Europe: North Europe and West Europe

在大多数情况下,对 Microsoft 文本翻译 API 的请求由距离请求的来源位置最近的数据中心处理。Requests to the Microsoft Translator Text API are in most cases handled by the datacenter that is closest to where the request originated. 如果数据中心发生故障,则可能会在该区域之外路由请求。In case of a datacenter failure, the request may be routed outside of the region.

若要强制特定数据中心处理该请求,请将 API 请求中的全球终结点更改为所需的区域终结点:To force the request to be handled by a specific datacenter, change the Global endpoint in the API request to the desired regional endpoint:

描述Description 区域Region 基 URLBase URL
AzureAzure 全局Global api.cognitive.microsofttranslator.comapi.cognitive.microsofttranslator.com
AzureAzure 北美North America api-nam.cognitive.microsofttranslator.comapi-nam.cognitive.microsofttranslator.com
AzureAzure 欧洲Europe api-eur.cognitive.microsofttranslator.comapi-eur.cognitive.microsofttranslator.com
AzureAzure 亚太区Asia Pacific api-apc.cognitive.microsofttranslator.comapi-apc.cognitive.microsofttranslator.com

AuthenticationAuthentication

文本翻译 API 订阅或认知服务多服务在 Microsoft 认知服务,并使用你的订阅密钥 (可在 Azure 门户中) 进行身份验证。Subscribe to Translator Text API or Cognitive Services multi-service in Microsoft Cognitive Services, and use your subscription key (available in the Azure portal) to authenticate.

有三个标头可用于对你的订阅进行身份验证。There are three headers that you can use to authenticate your subscription. 下表介绍了每个标头的使用方式:This table provides describes how each is used:

标头Headers 说明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 如果要传递密钥,请与认知服务订阅一起使用。Use with Cognitive Services subscription if you are passing your secret key.
该值是文本翻译 API 订阅的 Azure 密钥。The value is the Azure secret key for your subscription to Translator Text API.
授权Authorization 如果要传递身份验证令牌,请与认知服务订阅一起使用。Use with Cognitive Services subscription if you are passing an authentication token.
该值是持有者令牌:Bearer <token>The value is the Bearer token: Bearer <token>.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region 使用认知服务多服务订阅,如果要传递多服务的机密密钥。Use with Cognitive Services multi-service subscription if you are passing an multi-service secret key.
值是多服务订阅的区域。The value is the region of the multi-service subscription. 不使用多服务订阅时,此值是可选的。This value is optional when not using an multi-service subscription.

密钥Secret key

第一个选项是使用 Ocp-Apim-Subscription-Key 标头进行身份验证。The first option is to authenticate using the Ocp-Apim-Subscription-Key header. 只需将 Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> 标头添加到你的请求。Simply add the Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> header to your request.

授权令牌Authorization token

或者,可以交换访问令牌的密钥。Alternatively, you can exchange your secret key for an access token. 此令牌作为 Authorization 标头包含在每个请求中。This token is included with each request as the Authorization header. 若要获取授权令牌,请向以下 URL 发出 POST 请求:To obtain an authorization token, make a POST request to the following URL:

环境Environment 身份验证服务 URLAuthentication service URL
AzureAzure https://api.cognitive.microsoft.com/sts/v1.0/issueToken

以下是根据给定密钥获取令牌的示例请求:Here are example requests to obtain a token given a secret key:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

成功的请求会在响应正文中将编码的访问令牌作为纯文本返回。A successful request returns the encoded access token as plain text in the response body. 有效的令牌在授权中作为持有者令牌传递给翻译服务。The valid token is passed to the Translator service as a bearer token in the Authorization.

Authorization: Bearer <Base64-access_token>

身份验证令牌的有效期为 10 分钟。An authentication token is valid for 10 minutes. 在对翻译 API 进行多次调用时,应重新使用该令牌。The token should be re-used when making multiple calls to the Translator APIs. 但是,如果程序在很长一段时间内向翻译 API 发出请求,则程序必须定期(例如每 8 分钟)请求一个新的访问令牌。However, if your program makes requests to the Translator API over an extended period of time, then your program must request a new access token at regular intervals (e.g. every 8 minutes).

多服务订阅Multi-service subscription

最后一个身份验证选项是使用认知服务的多服务订阅。The last authentication option is to use a Cognitive Service’s multi-service subscription. 这样便可以使用一个密钥对多个服务的请求进行身份验证。This allows you to use a single secret key to authenticate requests for multiple services.

当使用多服务的机密密钥时,必须在您的请求包含两个身份验证标头。When you use a multi-service secret key, you must include two authentication headers with your request. 第一个标头可传递密钥,第二个标头可指定与你的订阅关联的区域。The first passes the secret key, the second specifies the region associated with your subscription.

  • Ocp-Apim-Subscription-Key
  • Ocp-Apim-Subscription-Region

区域是必需的多服务的文本 API 订阅。Region is required for the multi-service Text API subscription. 所选的区域是使用多服务的订阅密钥,可以使用文本翻译的唯一区域,并且必须通过 Azure 门户在多服务订阅注册时选择的相同区域。The region you select is the only region that you can use for text translation when using the multi-service subscription key, and must be the same region you selected when you signed up for your multi-service subscription through the Azure portal.

可用区域包括 australiaeastbrazilsouthcanadacentralcentralindiacentraluseuapeastasiaeastuseastus2japaneastnortheuropesouthcentralussoutheastasiauksouthwestcentraluswesteuropewestuswestus2Available regions are australiaeast, brazilsouth, canadacentral, centralindia, centraluseuap, eastasia, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westcentralus, westeurope, westus, and westus2.

如果使用参数 Subscription-Key 传递查询字符串中的密钥,则必须使用查询参数 Subscription-Region 指定区域。If you pass the secret key in the query string with the parameter Subscription-Key, then you must specify the region with query parameter Subscription-Region.

如果使用持有者令牌,则必须从区域终结点中获取令牌:https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueTokenIf you use a bearer token, you must obtain the token from the region endpoint: https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken.

错误Errors

标准错误响应是具有名为 error 的名称/值对的 JSON 对象。A standard error response is a JSON object with name/value pair named error. 该值也是具有以下属性的 JSON 对象:The value is also a JSON object with properties:

  • code:服务器定义的错误代码。code: A server-defined error code.

  • message:一个提供人类可读的错误表示形式的字符串。message: A string giving a human-readable representation of the error.

例如,拥有免费试用版订阅的客户会在免费配额用尽后收到以下错误:For example, a customer with a free trial subscription would receive the following error once the free quota is exhausted:

{
  "error": {
    "code":403001,
    "message":"The operation is not allowed because the subscription has exceeded its free quota."
    }
}

错误代码是一个 6 位数字,包括 3 位数的 HTTP 状态代码,后接用于进一步将错误分类的 3 位数。The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. 常见错误代码包括:Common error codes are:

代码Code 描述Description
400000400000 某个请求输入无效。One of the request inputs is not valid.
400001400001 “scope”参数无效。The "scope" parameter is invalid.
400002400002 “category”参数无效。The "category" parameter is invalid.
400003400003 语言说明符缺失或无效。A language specifier is missing or invalid.
400004400004 目标脚本说明符(“To script”)缺失或无效。A target script specifier ("To script") is missing or invalid.
400005400005 输入文本缺失或无效。An input text is missing or invalid.
400006400006 语言和脚本的组合无效。The combination of language and script is not valid.
400018400018 源脚本说明符(“From script”)缺失或无效。A source script specifier ("From script") is missing or invalid.
400019400019 指定的某个语言不受支持。One of the specified language is not supported.
400020400020 输入文本数组中的某个元素无效。One of the elements in the array of input text is not valid.
400021400021 API 版本参数缺失或无效。The API version parameter is missing or invalid.
400023400023 指定的某个语言对无效。One of the specified language pair is not valid.
400035400035 源语言(“From”字段)无效。The source language ("From" field) is not valid.
400036400036 目标语言(“To”字段)缺失或无效。The target language ("To" field) is missing or invalid.
400042400042 指定的某个选项(“Options”字段)无效。One of the options specified ("Options" field) is not valid.
400043400043 客户端跟踪 ID(ClientTraceId 字段或 X-ClientTranceId 标头)缺失或无效。The client trace ID (ClientTraceId field or X-ClientTranceId header) is missing or invalid.
400050400050 输入文本过长。The input text is too long.
400064400064 “translation”参数缺失或无效。The "translation" parameter is missing or invalid.
400070400070 目标脚本(ToScript 参数)的数目与目标语言(To 参数)的数目不匹配。The number of target scripts (ToScript parameter) does not match the number of target languages (To parameter).
400071400071 TextType 的值无效。The value is not valid for TextType.
400072400072 输入文本的数组包含过多的元素。The array of input text has too many elements.
400073400073 脚本参数无效。The script parameter is not valid.
400074400074 请求正文是无效的 JSON。The body of the request is not valid JSON.
400075400075 语言对和类别组合无效。The language pair and category combination is not valid.
400077400077 超过了最大请求大小。The maximum request size has been exceeded.
400079400079 请求用于在源语言与目标语言之间进行翻译的自定义系统不存在。The custom system requested for translation between from and to language does not exist.
401000401000 由于凭据缺失或无效,请求未授权。The request is not authorized because credentials are missing or invalid.
401015401015 “提供的凭据适用于语音 API。"The credentials provided are for the Speech API. 此请求需要文本 API 的凭据。This request requires credentials for the Text API. 请使用文本翻译 API 的订阅。”Please use a subscription to Translator Text API."
403000403000 不允许该操作。The operation is not allowed.
403001403001 由于订阅已超过其免费配额,因此不允许该操作。The operation is not allowed because the subscription has exceeded its free quota.
405000405000 请求的资源不支持该请求方法。The request method is not supported for the requested resource.
408001408001 请求的自定义翻译系统尚不可用。The custom translation system requested is not yet available. 请在几分钟后重试。Please retry in a few minutes.
415000415000 Content-Type 标头缺失或无效。The Content-Type header is missing or invalid.
429000、429001、429002429000, 429001, 429002 服务器拒绝了请求,因为客户端已超出请求限制。The server rejected the request because the client has exceeded request limits.
500000500000 发生了意外错误。An unexpected error occurred. 如果该错误持续出现,请报告发生错误的日期/时间、响应标头 X-RequestId 中的请求标识符,以及请求标头 X-ClientTraceId 中的客户端标识符。If the error persists, report it with date/time of error, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503000503000 服务暂时不可用。Service is temporarily unavailable. 请重试。Please retry. 如果该错误持续出现,请报告发生错误的日期/时间、响应标头 X-RequestId 中的请求标识符,以及请求标头 X-ClientTraceId 中的客户端标识符。If the error persists, report it with date/time of error, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.