你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

开始批量翻译

项目
09/26/2024

参考
功能：Azure AI 翻译→文档翻译
API 版本：2024-05-01
HTTP 方法：POST

使用 Start Translation 方法执行异步批量翻译请求。
该方法需要一个 Azure Blob 存储帐户，其中包含用于源文档和已翻译文档的存储容器。

请求 URL

重要

对文档翻译功能的所有 API 请求都需要有位于 Azure 门户资源概述页上的自定义域终结点。

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

请求标头

请求标头为：

头文件	说明	条件
Ocp-Apim-Subscription-Key	来自 Azure 门户的 Translator 服务 API 密钥。	必需
Ocp-Apim-Subscription-Region	创建资源的区域。	使用区域（地理）资源（如美国西部）时是必需的。 &项目符号。
Content-Type	有效负载的内容类型。接受的值为 application/json 或 charset=UTF-8。	必需

BatchRequest（正文）

每个请求可包含多个文档，并且必须包含每个文档的源和目标容器。源媒体类型：application/json、text/json、application/*+json。
前缀和后缀筛选器（如有提供）用于筛选文件夹。前缀位于子路径中的容器名称后。
请求中可以包含术语表。如果术语表无效或在翻译过程中无法查看，则文档状态中将显示错误。
如果目标中已存在同名的文件，则作业将失败。
每个目标语言的 targetUrl 必须唯一。


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

输入

输入批量翻译请求的定义。

关键参数	类型	必须	请求参数	说明
输入	`array`	True	• source（对象） • targets（数组） • storageType（字符串）	输入源数据。

inputs.source

源数据的定义。

关键参数	类型	必须	请求参数	说明
inputs.source	`object`	True	• sourceUrl（字符串） • filter（对象） • language（字符串） • storageSource（字符串）	输入文档的源数据。
inputs.source.sourceUrl	`string`	True	• 字符串	源文件或文件夹的容器位置。
inputs.source.filter	`object`	False	• prefix（字符串） • suffix（字符串）	区分大小写的字符串，用于筛选源路径中的文档。
inputs.source.filter.prefix	`string`	False	• 字符串	区分大小写的前缀字符串，用于筛选源路径中的文档以进行翻译。通常用于指定子文件夹进行翻译。示例：“FolderA”。
inputs.source.filter.suffix	`string`	False	• 字符串	区分大小写的后缀字符串，用于筛选源路径中的文档以进行翻译。最常用于文件扩展名。示例：“.txt”
inputs.source.language	`string`	False	• 字符串	源文档的语言代码。如果未指定，则实施自动检测。
inputs.source.storageSource	`string`	False	• 字符串	输入的存储源。默认为 `AzureBlob`。

inputs.targets

目标和术语表数据的定义。

关键参数	类型	必须	请求参数	说明
inputs.targets	`array`	True	• targetUrl（字符串） • category（字符串） • language（字符串） • glossaries（数组） • storageSource（字符串）	已翻译文档的目标和术语表数据。
inputs.targets.targetUrl	`string`	True	• 字符串	已翻译文档的容器位置的位置。
inputs.targets.category	`string`	False	• 字符串	翻译请求的分类或类别。示例：常规。
inputs.targets.language	`string`	True	• 字符串	目标语言代码。示例：“fr”。
inputs.targets.glossaries	`array`	False	• glossaryUrl（字符串） • format（字符串） • version（字符串） • storageSource（字符串）	请参阅创建和使用术语表
inputs.targets.glossaries.glossaryUrl	`string`	True（如果使用术语表）	• 字符串	术语表的位置。如果未提供格式参数，则将使用文件扩展名来提取格式设置。如果术语表中没有翻译语言对，则不会应用该术语表。
inputs.targets.glossaries.format	`string`	False	• 字符串	术语表的指定文件格式。若要检查文件格式是否受支持，请参阅获取支持的术语表格式。
inputs.targets.glossaries.version	`string`	False	• 字符串	版本指示器。示例：“2.0”。
inputs.targets.glossaries.storageSource	`string`	False	• 字符串	术语表的存储源。默认为 `_AzureBlob_`。
inputs.targets.storageSource	`string`	False	• 字符串	目标的存储源。默认值为 `_AzureBlob_`。

inputs.storageType

输入文档的存储实体的定义。

关键参数	类型	必须	请求参数	说明
inputs.storageType	`string`	False	•`Folder` • `File`	输入文档源字符串的存储类型。只有“Folder”或“File”是有效值。

选项

输入批量翻译请求的定义。

关键参数	类型	必须	请求参数	说明
options	`object`	False	输入文档的源信息。
options.experimental	`boolean`	False	•`true` • `false`	指示请求是否包含实验性功能（如果适用）。只有布尔 `true` 值或 `false` 是有效值。

示例请求

下面是批处理请求的示例。

备注

在以下示例中，已使用共享访问签名 (SAS) 令牌授予对 Azure 存储容器内容的有限访问权限。

翻译容器中的所有文档

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

翻译应用术语表的容器中的所有文档

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

翻译容器中的特定文件夹

确保将文件夹名称（区分大小写）指定为筛选器中的前缀。

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

翻译容器中的特定文档

指定“storageType“：File。
为特定 blob/文档创建源 URL 和 SAS 令牌。
将目标文件名指定为目标 URL 的一部分，但是 SAS 令牌仍适用于容器。

此示例请求显示翻译成两种目标语言的单个文档。

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

提示

此方法会返回 get-translation-status、get-documents-status、get-document-status 和 cancel-translation 请求查询字符串的作业 id 参数。

可以在 POST start-batch-translation方法响应头 Operation-Location URL 值中查找作业 id。 /document/ 参数后面的字母数字字符串是操作的作业 id：

响应头 响应 URL

Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
还可以使用 get-translations-status 请求来检索翻译作业及其 id 的列表。

响应头	响应 URL
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

响应状态代码

下面是请求可能返回的 HTTP 状态代码。

状态代码	说明
202	已接受。成功的请求和批处理请求已创建。标头 Operation-Location 将指示带有 operation ID.HeadersOperation-Location: 字符串的状态 URL
400	错误的请求。请求无效。检查输入参数。
401	未授权。检查凭据。
429	请求速率过高。
500	内部服务器错误。
503	服务当前不可用。请稍后再试。
其他状态代码	• 请求过多。服务器暂时不可用

错误响应

关键参数	类型	说明
code	`string`	包含错误代码概要的枚举。可能的值：</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Unauthorized
message	`string`	获取概要错误消息。
innerError	InnerTranslationError	符合 Azure AI 服务 API 准则的新的内部错误格式。此错误消息包含必需的属性：ErrorCode、消息和可选属性目标、详细信息（键值对）、内部错误（可以嵌套）。
inner.Errorcode	`string`	获取代码错误字符串。
innerError.message	`string`	获取概要错误消息。
innerError.target	`string`	获取错误的源。例如，如果文档无效，它为 `documents` 或 `document id`。

错误响应示例

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

后续步骤

遵循快速入门，详细了解如何使用文档翻译和客户端库。

文档翻译入门

通过