Skip to main content

使用Postman练习使用Azure Translator的文档翻译

分类:  Azure翻译服务 ◆ 标签:  #Azure #翻译 #Translator ◆ 发布于: 2023-06-15 21:09:48

在正式使用文档翻译rest api之前有几个地方需要注意：

  1. 文档翻译的API是必须创建一个单独的Translator服务，而不能和Azure认知服务共用。
  2. 文档翻译的功能只在定价层S1(pay-as-you-go)和Azure Global的D3 Variable cost plus Fixed plus overage定价层支持。
  3. 文档翻译API有自己单独的请求Endpoint，既不是文本翻译的endPoint也不是认知服务的endpoint
  4. 文档翻译除了要创建Translator资源之外，还需要一个Azure Storage的资源，并在该存储账号中创建两个blob，一个用于存储需要翻译的文档，另外一个用于输出翻译之后的文档。

创建资源

开始测试之前先创建两类资源，一个是Azure Translator，如何创建请参考之前的文章。
然后创建一个Azure Storage, 并创建两个Blob。
如下图：


请注意1, 2, 3的箭头，2， 3分别是用于存放源文档和翻译之后的文档的。

另外需要注意的是我们需要两个Blob容器的SAS Key, 关于如何生成这两个Key, 请按照如下图所示生成：


分别生成并保存下来，要注意要生成两个容器的SAS Key。

注意
在生成容器的SAS Key的时候，注意选择一下权限，作为源的容器，存储的是需要翻译的文档，这些文档要给予read和list权限，目前容器存储的是翻译之后的文档，要注意给予write权限，如果不清楚，就全给好了。

Postman的设定

上面说过文档翻译的API有自己单独的Endpoint地址，形式如下：

  • Azure Global: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0
  • Azure China: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0

文档翻译的接口是：

/batches

API的请求头里也是需要包含如下的信息：

  • Ocp-Apim-Subscription-Key: 您的Key
  • Content-Type: application/json; charset=UTF-8

请求的方法是POST。

请求的正文内容：

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "<指定刚刚我们提前预备好的blob的SAS url>"
            },
            "targets": [
                {
                    "targetUrl": "<指定刚刚我们提前预备好的blob的SAS url>",
                    "language": "fr"
                }
            ]
        }{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/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.windows.net/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.windows.net/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"
                }
            ]
        }
    ]
}
    ]
}

像这样是翻译这个目录下的所有文档，如果只想翻译特定的文档，那么可以用文件的SAS 连接字符串就可以了。

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/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.windows.net/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.windows.net/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"
                }
            ]
        }
    ]
}

而且sourceURL和Target Url都可以指定多个。

使用postman演示

我们接着来使用postman来演示一下。

主要是请求体设置一下就好了。

我需要翻译的文档如下是四个：


都是英文的HTML文档。

我提交的Request Body是：

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "<我的源blob的SAS连接字符串>"
            },
            "targets": [
                {
                    "targetUrl": "<我的目的Blob的SAS连接字符串>",
                    "language": "zh-hans"
                }
            ]
        }
       
    ]
}

使用postman发送成功后要从返回的header里找出提交的job的id:

就是header里的这个Operation-Location


格式是这样的：
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.0/batches/{这个部分就是jobid}>

返回Job的状态

还是使用postman

请求的接口是:

/batches/{Job Id}

方法是GET

如下是我返回的结果：

{
    "id": "89661315-0077-485a-ac8e-78903b3ece51",
    "createdDateTimeUtc": "2022-06-02T15:13:37.9965704Z",
    "lastActionDateTimeUtc": "2022-06-02T15:14:13.8780391Z",
    "status": "Succeeded",
    "summary": {
        "total": 4,
        "failed": 0,
        "success": 4,
        "inProgress": 0,
        "notYetStarted": 0,
        "cancelled": 0,
        "totalCharacterCharged": 36136
    }
}

需要注意的是，如果有错误，也是通过这个接口可以看到，最为常见的错误是在Azure Storage的时候没有设对权限: Source要有read和List, 但是target要有write, list, read, 嫌麻烦就赋全部权限也可以。

可以从图中看到翻译的结果，原文档的结构保存完好：


另外还有两个方法：

就是一个文档一个文档的提交，你可以查看每个文档翻译的进度和状态：通过接口：/{id}/document/{documentId}, 请求方法用GET
删除一个正在运行的Job, 请求的接口是: /batches/{id}, 请求方法用Delete。

文档翻译的所有功能也就到这里结束了。