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

Translator 3.0 版Translator v3.0

新增功能What's new?

Translator 的版本 3 提供了基于 JSON 的新型 Web API。Version 3 of the Translator 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 look up 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. 目前它们位于 10 个 Azure 地理区域Currently they are located in 10 Azure geographies:

  • 美洲: 美国东部、美国中南部、美国西部和美国西部2Americas: East US, South Central US, West Central US, and West US 2
  • 亚太: 韩国南部、日本东部、东南亚和澳大利亚东部Asia Pacific: Korea South, Japan East, Southeast Asia, and Australia East
  • 欧洲: 北欧和西欧Europe: North Europe and West Europe

在大多数情况下,对 Microsoft Translator 的请求由距离请求来源最近的数据中心处理。Requests to the Microsoft Translator are in most cases handled by the datacenter that is closest to where the request originated. 如果数据中心出现故障,请求可能会路由到 Azure 地理区域之外。In case of a datacenter failure, the request may be routed outside of the Azure geography.

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

说明Description Azure 地理区域Azure geography 基 URLBase URL
AzureAzure 全局 (非区域) Global (non-regional) api.cognitive.microsofttranslator.comapi.cognitive.microsofttranslator.com
AzureAzure 美国United States 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

身份验证Authentication

订阅 Azure 认知服务中的 Translator 或认知服务多服务,并使用订阅密钥(在 Azure 门户中提供)进行身份验证。Subscribe to Translator or Cognitive Services multi-service in Azure 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 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.
该值是用于 Translator 订阅的 Azure 密钥。The value is the Azure secret key for your subscription to Translator.
授权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 and regional translator resource.
该值是多服务或区域翻译器资源的区域。The value is the region of the multi-service or regional translator resource. 当使用全球翻译器资源时,该值是可选的。This value is optional when using a global translator resource.

密钥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> 标头添加到请求。Add the Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> header to your request.

使用全球资源进行身份验证Authenticating with a global resource

当使用全球翻译器资源时,需要包含一个标头来调用 Translator。When you use a global translator resource, you need to include one header to call the Translator.

标头Headers 说明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 该值是用于 Translator 订阅的 Azure 密钥。The value is the Azure secret key for your subscription to Translator.

下面是使用全球翻译器资源调用 Translator 的示例请求Here's an example request to call the Translator using the global translator resource

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

使用区域资源进行身份验证Authenticating with a regional resource

当使用区域翻译器资源时。When you use a regional translator resource. 调用 Translator 时所需的标头有 2 个。There are 2 headers that you need to call the Translator.

标头Headers 说明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 该值是用于 Translator 订阅的 Azure 密钥。The value is the Azure secret key for your subscription to Translator.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region 该值是翻译器资源的区域。The value is the region of the translator resource.

下面是使用区域翻译器资源调用 Translator 的示例请求Here's an example request to call the Translator using the regional translator resource

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/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?'}]"

使用多服务资源进行身份验证Authenticating with a Multi-service resource

使用认知服务的多服务资源时。When you use a Cognitive Service’s multi-service resource. 这样便可以使用一个密钥对多个服务的请求进行身份验证。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. 调用 Translator 时所需的标头有 2 个。There are 2 headers that you need to call the Translator.

标头Headers 说明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 该值是用于多服务资源的 Azure 密钥。The value is the Azure secret key for your multi-service resource.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region 该值是多服务资源的区域。The value is the region of the multi-service resource.

区域对于多服务文本 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.

可用区域包括、、、、、、、、、、、、、、、、、、、、、 australiaeast brazilsouth canadacentral centralindia centralus centraluseuap eastasia eastus eastus2 francecentral japaneast japanwest koreacentral northcentralus northeurope southcentralus southeastasia uksouth westcentralus westeurope westus westus2southafricanorthAvailable regions are australiaeast, brazilsouth, canadacentral, centralindia, centralus, centraluseuap, eastasia, eastus, eastus2, francecentral, japaneast, japanwest, koreacentral, northcentralus, northeurope, southcentralus, southeastasia, uksouth, westcentralus, westeurope, westus, westus2, and southafricanorth.

如果使用参数 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.

使用访问令牌进行身份验证Authenticating with an access 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:

资源类型Resource type 身份验证服务 URLAuthentication service URL
GlobalGlobal https://api.cognitive.microsoft.com/sts/v1.0/issueToken
区域或多服务Regional or Multi-Service https://<your-region>.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. 有效的令牌在授权中作为持有者令牌传递给 Translator 服务。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. 对转换器进行多次调用时,应重新使用该令牌。The token should be reused when making multiple calls to the Translator. 但是,如果程序在很长一段时间内向转换器发出请求,则程序必须定期请求新的访问令牌 (例如,每8分钟) 。However, if your program makes requests to the Translator over an extended period of time, then your program must request a new access token at regular intervals (for example, every 8 minutes).

虚拟网络支持Virtual Network support

转换器服务现在可在 Azure 公有云的所有区域中提供虚拟网络 (VNET) 功能。The Translator service is now available with Virtual Network (VNET) capabilities in all regions of the Azure public cloud. 若要启用虚拟网络,请参阅 配置 Azure 认知服务虚拟网络To enable Virtual Network, please see Configuring Azure Cognitive Services Virtual Networks.

启用此功能后,必须使用自定义终结点来调用转换器。Once you turn on this capability, you must use the custom endpoint to call the Translator. 不能使用 "api.cognitive.microsofttranslator.com" ) ( 全局转换器终结点,并且不能使用访问令牌进行身份验证。You cannot use the global translator endpoint ("api.cognitive.microsofttranslator.com") and you cannot authenticate with an access token.

你可以在创建 转换器资源 后找到自定义终结点,并允许从所选网络和专用终结点进行访问。You can find the custom endpoint after you create a translator resource and allow access from selected networks and private endpoints.

标头Headers 说明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 该值是用于 Translator 订阅的 Azure 密钥。The value is the Azure secret key for your subscription to Translator.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region 该值是翻译器资源的区域。The value is the region of the translator resource. 如果资源为,则此值是可选的 globalThis value is optional if the resource is global

下面是使用自定义终结点调用转换器的示例请求Here's an example request to call the Translator using the custom endpoint

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/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?'}]"

错误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 languages 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. 查看请求限制View request limits.
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. 查看请求限制View request limits.
400079400079 请求用于在源语言与目标语言之间进行翻译的自定义系统不存在。The custom system requested for translation between from and to language does not exist.
400080400080 语言或脚本不支持音译。Transliteration is not supported for the language or script.
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. 请使用 Translator 的订阅。”Use a subscription to Translator."
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 translation system requested is being prepared. 请在几分钟内重试。Please retry in a few minutes.
408002408002 等待传入流时请求超时。Request timed out waiting on incoming stream. 客户端没有在服务器准备等待的时间内生成请求。The client did not produce a request within the time that the server was prepared to wait. 客户端可以在以后的任何时间重复该请求,而不做任何修改。The client may repeat the request without modifications at any later time.
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.

指标Metrics

利用指标,可以在 Azure 门户中的指标部分下查看翻译器的使用情况和可用性信息,如以下屏幕截图所示。Metrics allow you to view the translator usage and availability information in Azure portal, under metrics section as shown in the below screenshot. 有关详细信息,请参阅数据和平台指标For more information, see Data and platform metrics.

Translator 指标

此表列出了可用的指标,以及有关如何使用它们来监视翻译 API 调用的说明。This table lists available metrics with description of how they are used to monitor translation API calls.

指标Metrics 说明Description
TotalCallsTotalCalls API 调用总数。Total number of API calls.
TotalTokenCallsTotalTokenCalls 使用身份验证令牌通过令牌服务进行的 API 调用的总数。Total number of API calls via token service using authentication token.
SuccessfulCallsSuccessfulCalls 成功调用数。Number of successful calls.
TotalErrorsTotalErrors 产生了错误响应的调用数。Number of calls with error response.
BlockedCallsBlockedCalls 超过速率或配额限制的调用数。Number of calls that exceeded rate or quota limit.
ServerErrorsServerErrors 产生了服务器内部错误 (5XX) 的调用数。Number of calls with server internal error(5XX).
ClientErrorsClientErrors 产生了客户端错误 (4xx) 的调用数。Number of calls with client side error(4XX).
延迟Latency 完成请求的持续时间(毫秒)。Duration to complete request in milliseconds.
CharactersTranslatedCharactersTranslated 传入的文本请求中的字符总数。Total number of characters in incoming text request.