开始翻译

项目
03/17/2024

参考
服务：Azure AI 文档翻译
API 版本：v1.1

使用此 API，通过文档翻译服务发起翻译请求。每个请求可包含多个文档，必须包含每个文档的源和目标容器。

前缀和后缀筛选器（如有提供）用于筛选文件夹。前缀位于子路径中的容器名称后。

术语表/翻译记忆库可以包含在请求中，并由该服务应用于文档的翻译中。

如果术语表无效或在翻译过程中无法查看，则文档状态中将显示错误。如果目标中已存在同名的文件，作业将失败。每个目标语言的 targetUrl 必须唯一。

请求 URL

将 POST 请求发送到：

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.1/batches

了解如何查找自定义域名。

重要

向文档翻译服务发出的所有 API 请求都需要一个自定义域终结点。
不能使用 Azure 门户资源的“密钥和终结点”页上的终结点或者全局翻译器终结点 (api.translator.azure.cn) 来向文档翻译发出 HTTP 请求。

请求标头

请求标头为：

头文件	说明
Ocp-Apim-Subscription-Key	必需的请求标头

BatchRequest（正文）

输入批量翻译请求的定义。每个请求可包含多个文档，并且必须包含每个文档的源和目标容器。源媒体类型：application/json、text/json、application/*+json。


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

输入

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

关键参数	类型	必须	请求参数	说明
输入	`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.chinacloudapi.cn/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

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

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.chinacloudapi.cn/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.chinacloudapi.cn/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

翻译容器中的特定文件夹

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

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.chinacloudapi.cn/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

翻译容器中的特定文档

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

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

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.chinacloudapi.cn/source-en/source-english.docx?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.chinacloudapi.cn/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

响应状态代码

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

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

错误响应

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

示例

成功响应示例

成功的响应中会返回以下信息。

可以在 POST 方法的响应头 Operation-Location URL 值中找到作业 ID。 URL 的最后一个参数是操作的作业 ID，即“/operation/”之后的字符串。

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

错误响应示例

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

后续步骤

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

文档翻译入门