文档翻译入门

本文介绍如何通过 HTTP REST API 方法使用文档翻译。 文档翻译是 Azure 翻译器服务的一个基于云的功能。 使用文档翻译 API 可以翻译整个文档,同时保留源文档结构和文本格式。

先决条件

注意

  • 一般情况下,当你在 Azure 门户中创建认知服务资源时,可以选择创建多服务密钥或单服务密钥。 但是,文档翻译目前仅在翻译器(单服务)资源中受支持,而包含在认知服务(多服务)资源中。

  • 文档翻译功能目前仅在 S1 标准服务计划(即用即付)或 D3 批量折扣计划中受支持。 请参阅认知服务定价 - 翻译器

若要开始,需要:

  • 一个有效的 Azure 帐户。 如果没有,可以创建一个试用帐户

  • 一个 Azure Blob 存储帐户。 你需创建一个容器,用于存储和整理存储帐户中的 blob 数据。

  • 单服务翻译器资源(并非多服务认知服务资源):

    按如下所示填写翻译器项目和实例详细信息字段:

    1. 订阅。 选择一个可用的 Azure 订阅。

    2. 资源组。 可以创建新资源组,或将资源添加到共享相同生命周期、权限和策略的预先存在的资源组。

  1. 资源区域。 如果你打算使用系统分配的托管标识来进行身份验证,请选择非全球区域。

  2. 名称。 输入为资源选择的名称。 所选名称在 Azure 中必须唯一。

    注意

    文档翻译需要自定义域终结点。 在“名称”字段中输入的值将会是终结点的自定义域名参数。

  3. 定价层。 免费层不支持文档翻译。 请选择标准 S1 来试用该服务。

  4. 选择“查看 + 创建” 。

  5. 查看服务条款,然后选择“创建”以部署资源。

  6. 成功部署资源后,选择“转到资源”。

你的自定义域名和密钥

重要

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

什么是自定义域终结点?

自定义域终结点是格式中包含资源名称、主机名和翻译器子目录的 URL:

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

查找自定义域名

NAME-OF-YOUR-RESOURCE(也称为自定义域名)参数是创建翻译器资源时在“名称”字段中输入的值。

Image of the Azure portal, create resource, instant details, name field.

获取你的密钥

向翻译器服务发出的请求需要一个在对访问进行身份验证时使用的只读密钥。

  1. 如果已创建新资源,请在部署该资源后选择“转到资源”。 如果有现有的文档翻译资源,请直接导航到资源页。
  2. 在左侧导航栏中的“资源管理”下,选择“密钥和终结点”。
  3. 将你的密钥复制并粘贴到方便的位置(例如 Microsoft 记事本)。
  4. 稍后需将此密钥粘贴到以下代码中,以便对发往文档翻译服务的请求进行身份验证。

Image of the get your key field in Azure portal.

创建 Azure Blob 存储容器

需要在 Azure Blob 存储帐户中为源文件和目标文件创建容器

  • 源容器。 将在此容器中上传要翻译的文件(必需)。
  • 目标容器。 将在此容器中存储已翻译的文件(必需)。

注意

文档翻译支持词汇表作为目标容器中的 blob(不是单独的词汇表容器)。 如果要包含自定义词汇表,请将其添加到目标容器,并包含 glossaryUrl 和请求。 如果词汇表中没有翻译语言对,则不会应用该词汇表。 请参阅使用自定义词汇表来翻译文档

为文档翻译创建 SAS 访问令牌

sourceUrltargetUrl 和可选的 glossaryUrl 必须包含作为查询字符串追加的共享访问签名 (SAS) 令牌。 可将该令牌分配到容器或特定的 Blob。 参阅为文档翻译处理创建 SAS 令牌

  • 源容器或 Blob 必须已指定读取和列出访问权限。
  • 目标容器或 Blob 必须已指定写入和列出访问权限。
  • 词汇表 Blob 必须已指定的读取和列出访问权限。

提示

  • 如果在某个操作中翻译多个文件 (Blob),请在容器级别委托 SAS 访问权限。
  • 如果在某个操作中翻译单个文件 (Blob),请在 Blob 级别委托 SAS 访问权限
  • 作为 SAS 令牌的替代方法,可以使用系统分配的托管标识来进行身份验证。

HTTP 请求

批处理文档翻译请求将通过 POST 请求提交到翻译器服务终结点。 如果成功,POST 方法将返回 202 Accepted 响应代码,服务将创建批处理请求。 经过翻译的文档将会在目标容器中列出。

HTTP 头

每个文档翻译器 API 请求包含以下请求头:

HTTP 标头 说明
Ocp-Apim-Subscription-Key 必需:该值是翻译器或认知服务资源的 Azure 密钥。
Content-Type 必需:指定有效负载的内容类型。 接受的值为 application/json 或 charset=UTF-8。

POST 请求正文属性

  • POST 请求 URL 是 POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0/batches
  • POST 请求正文是名为 inputs 的 JSON 对象。
  • inputs 对象包含源语言和目标语言对的 sourceURLtargetURL 容器地址
  • prefixsuffix 字段(可选)用于筛选容器中的文档(包括文件夹)。
  • 翻译文档时将应用 glossaries 字段(可选)的值。
  • 每个目标语言的 targetUrl 必须唯一。

注意

如果目标中已存在同名的文件,作业将失败。

翻译容器中的所有文档

{
    "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"
                }
            ]
        }
    ]
}

翻译容器中的特定文档

  • 指定 "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"
                }
            ]
        }
    ]
}

使用自定义词汇表来翻译文档

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://myblob.blob.core.chinacloudapi.cn/source",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://myblob.blob.core.chinacloudapi.cn/target",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https:// myblob.blob.core.chinacloudapi.cn/glossary/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

使用代码来提交文档翻译请求

设置编程平台

  • 创建新项目。
  • 将 Program.cs 替换为下面所示的 C# 代码。
  • 在 Program.cs 中设置终结点、密钥和容器 URL 的值。
  • 若要处理 JSON 数据,请使用 .NET CLI 添加 Newtonsoft.Json 包
  • 从项目目录运行程序。

重要

对于下面的代码示例,你将根据指示对密钥和终结点进行硬编码;请记得在完成操作后从代码中删除密钥,切勿将其公开发布。 有关安全地存储和访问凭据的方式,请参阅 Azure 认知服务安全性

可能需要根据操作更新以下字段:

  • endpoint
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id(作业 ID)

查找 id

  • 在 POST 方法响应头 Operation-Location URL 值中找到作业 id。 该 URL 的最后一个参数是操作的作业 id
响应头 结果 URL
Operation-Location https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec
  • 还可以使用 GET 作业请求来检索文档翻译作业 id

翻译文档


    using System;
    using System.Net.Http;
    using System.Threading.Tasks;
    using System.Text;


    class Program
    {

        static readonly string route = "/batches";

        private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0";

        private static readonly string key = "<YOUR-KEY>";

        static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\",\"filter\":{\"prefix\": \"Demo_1/\"} }, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");

        static async Task Main(string[] args)
        {
            using HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {

                StringContent content = new StringContent(json, Encoding.UTF8, "application/json");

                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);
                request.Content = content;

                HttpResponseMessage  response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;
                if (response.IsSuccessStatusCode)
                {
                    Console.WriteLine($"Status code: {response.StatusCode}");
                    Console.WriteLine();
                    Console.WriteLine($"Response Headers:");
                    Console.WriteLine(response.Headers);
                }
                else
                    Console.Write("Error");

            }

        }

    }

获取文件格式

检索受支持文件格式的列表。 如果成功,此方法将返回 200 OK 响应代码。


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0";

    static readonly string route = "/documents/formats";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

获取作业状态

在文档翻译请求中获取单个作业的当前状态以及所有作业的摘要。 如果成功,此方法将返回 200 OK 响应代码。


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

获取文档状态

简要概述

在文档翻译请求中检索特定文档的状态。 如果成功,此方法将返回 200 OK 响应代码。


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0";

    static readonly string route = "/{id}/document/{documentId}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

删除作业

简要概述

取消当前正在处理或已排队的作业。 只会取消尚未开始翻译的文档。


using System;
using System.Net.Http;
using System.Threading.Tasks;


class Program
{


    private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0";

    static readonly string route = "/batches/{id}";

    private static readonly string key = "<YOUR-KEY>";

    static async Task Main(string[] args)
    {

        HttpClient client = new HttpClient();
            using HttpRequestMessage request = new HttpRequestMessage();
            {
                request.Method = HttpMethod.Delete;
                request.RequestUri = new Uri(endpoint + route);
                request.Headers.Add("Ocp-Apim-Subscription-Key", key);


                HttpResponseMessage response = await client.SendAsync(request);
                string result = response.Content.ReadAsStringAsync().Result;

                Console.WriteLine($"Status code: {response.StatusCode}");
                Console.WriteLine($"Response Headers: {response.Headers}");
                Console.WriteLine();
                Console.WriteLine(result);
            }
}

内容限制

下表列出了发送到文档翻译的数据的限制。

属性 限制
文档大小 ≤ 40 MB
文件总数。 ≤ 1000
一个批中的内容总大小 ≤ 250 MB
一个批中的目标语言数 ≤ 10
翻译内存文件的大小 ≤ 10 MB

文档翻译不能用于翻译受保护的文档,例如那些使用加密密码的或复制内容的访问权限受限的文档。

疑难解答

常见的 HTTP 状态代码

HTTP 状态代码 说明 可能的原因
200 OK 请求已成功。
400 错误的请求 必需参数缺失、为空或为 null。 或者,传递给必需参数或可选参数的值无效。 常见问题是标头太长。
401 未授权 请求未授权。 检查确保你的密钥或令牌有效并且在正确的区域中。 在 Azure 门户上管理订阅时,请确保使用的是翻译器单服务资源,而非认知服务多服务资源。
429 请求过多 已经超过了订阅允许的配额或请求速率。
502 错误的网关 网络或服务器端问题。 也可能表示标头无效。

了解更多