Azure Cognitive Services ドキュメント翻訳APIを試す

2021/5/25にAzure Cognitive Servicesの [ドキュメント翻訳](https://docs.microsoft.com/ja-jp/azure/cognitive-services/translator/document-translation/overview) がGAされたので試してみました。

# 構成
* 前提として翻訳したいドキュメントはBlobストレージに配置する必要があります。
* 構成は以下のようになります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/20645eac-342f-6f8a-5a30-b8d82e7349b0.png)

# Translatorサービスリソース作成
* Azure Portalより[リソースの作成]を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/4e81e153-8cc6-fe92-90f1-5611268ef163.png)

* リソース検索バーで[Translator]と入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/058984a3-6087-a16e-f1e1-33fd28c02d01.png)

* Translatorが表示されたら[作成]を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/e12d7f33-e117-4c59-79d4-f8454144281b.png)

* リージョンは[東日本]を選択、名前は任意、価格レベルはStandard以上を選択します。ドキュメント翻訳はStandard以上が必要です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/1de3f6d5-f12f-a9d4-bd6d-75c2cc15cea3.png)

* マネージドIDはオフのまま作成します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/0f060e98-0830-126c-11fb-67e2916682db.png)

# Storage Explorerダウンロード
* SAS取得時に[Storage Explorer](https://azure.microsoft.com/ja-jp/features/storage-explorer/) からでないと動かなかったためダウンロード、インストールしておきます。

# 翻訳(日本語→英語)
## Blob Container作成
* ストレージアカウントを準備し、Blob Containerを作成します。ソース用とターゲット用の2つ準備します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/72087973-f156-6c4f-a2c3-ff7d28c48643.png)

* source containerに翻訳したいドキュメントを配置します。今回はこんなパワーポイントを準備しました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/d6d55e9f-f8b3-404b-1a0a-23fc8d5fa38c.png)


## ソースBLOBのSAS取得
* Storage Explorerを開き、先ほど配置したPPTXファイルを右クリックし、[Shared Access Signatureの取得]を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/dd4931c2-7549-f78c-fca5-b88e800a02e4.png)

* [読み取り]と[リスト]にチェックを入れSAS取得します。有効期限は任意で。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/ec7f5023-0526-ad7b-7d18-4ad2bc461c71.png)

* 出力されたURLをメモっておきます。

## ターゲットコンテナーのSAS取得
* 同じようにtargetコンテナーのSAS取得します。こっちはコンテナーに対してSASを取得します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/af2f9dc4-007e-29e3-ff1a-051666a8be8f.png)

* [書き込み]と[リスト]にチェックを入れSAS取得します。有効期限は任意で。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/b148f9bc-4f14-bd49-3afe-05feb33f53fd.png)

* 出力されたURLをメモっておきます。

## ドキュメント翻訳要求をPOST
* HTTPヘッダーに指定する[Ocp-Apim-Subscription-Key]を取得します。Azure PortalのTranslatorから[キーとエンドポイント]を選択し、コピーしておきます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/c40ce96e-e4d9-268d-12e5-cb5fd5da3d54.png)

* API要求方法はcurlとかなんでもよいのですが、今回はPostmanで説明します。
* POSTメソッドとして、宛先は ```https://[Translatorサービスリソース名].cognitiveservices.azure.com/translator/text/batch/v1.0-preview.1/batches``` と指定します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/c358b7af-32fb-cab7-0d1b-5a304d466a02.png)

* HTTPヘッダーには以下2つを追加します。[Ocp-Apim-Subscription-Key]には事前にメモしたキーを入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/db6e5a79-b83b-d04e-b83e-16a63b794c0b.png)

* 要求本文には以下のように入力します。

```
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "[ソースBLOBのSAS URL]"
            },
            "targets": [
                {
                    "targetUrl": "[ターゲットコンテナーのSAS URL]",
                    "language": "en"
                }
            ]
        }
    ]
}
```

* これらを指定してPOST要求を発行し、[202 Accepted]が返ってくればOKです。

# ジョブ実行状態確認
* ドキュメント翻訳処理は非同期で実行されます。そのため処理がうまく動いているのかエラーになっているのかを確認することができます。
* 先ほどの要求POSTの応答ヘッダー[Operation-Location]に以下のように返ってくるためメモっておきます。

```
https://[Translatorサービスリソース名].cognitiveservices.azure.com/translator/text/batch/v1.0-preview.1/batches/[ジョブID]
```

* 新たにGET要求を発行します。宛先URLは先ほどメモしたURLになります。

```
https://[Translatorサービスリソース名].cognitiveservices.azure.com/translator/text/batch/v1.0-preview.1/batches/[ジョブID]
```

* HTTPヘッダーには以下2つを追加します。[Ocp-Apim-Subscription-Key]には事前にメモしたキーを入力します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/db6e5a79-b83b-d04e-b83e-16a63b794c0b.png)

* GET要求を発行すると結果がJSONで返ってきます。問題なければstatusがSucceededとなります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/dda9eb71-4ad4-e7a5-860b-38690dd78f90.png)

* targetコンテナーを見てみると、翻訳されたファイルが格納されています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/7620ce64-a7e4-fabe-39a6-8207f3d10c75.png)

# 用語集を使ってみる
* 特殊な用語などうまく翻訳できない場合に用語集として定義することができます。
* 試しに以下のテキストをドキュメント翻訳してみます。

```sample.txt
こんにちは！
Azure Cognitive Services ドキュメント翻訳機能がリリースされたので紹介します。
```

* 翻訳結果です。（CognitiveがNativeになってる。。）

```sample.txt
Hello!
Introducing the Azure Native Services document translation feature, which has been released.
```

* この翻訳結果を用語集を使って変更してみます。
* まずは用語集csvの格納先Blobコンテナーを作成します。今回はglossaryという名前のコンテナーを作成します。
* 以下のように用語集csvファイルを作成します。

```glossary.csv
ja,en
こんにちは,Hi
Azure Cognitive Services,Azure Cognitive Services
```

* glossary.csvをglossaryコンテナーに配置します。
* glossary.csvのSASを取得します。読み取りのみにチェックを入れます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/180335/6c7e8d01-b602-8b18-9270-996935a614c5.png)

* POST要求を発行します。要求本文のみ以下のように変更します。

```
{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "[ソースBLOBのSAS URL]",
                "language":"ja"
            },
            "targets": [
                {
                    "targetUrl": "[ターゲットコンテナーのSAS URL]",
                    "language": "en",
                    "glossaries": [
                        {
                            "glossaryUrl": "[glossaryBLOBのSAS URL]",
                            "format": "CSV"
                        }
                    ]
                }
            ]
        }
    ]
}
```

* POST要求を発行すると以下のように翻訳されました。用語集の内容は反映されているようですね。

```
Hi!
Azure Cognitive Services document translation feature has been released.
```

* TextやHtmlファイルであれば用語集反映されましたが、PPTXで試すとうまく読み取れないことがありました。

以上