ドキュメント翻訳は、 Azure Translator サービスのクラウドベースの機能です。 ドキュメント翻訳 API を使用すると、ソース ドキュメントの構造とテキストの書式設定を維持しながら、 サポートされている言語 およびさまざまな ファイル形式 でドキュメント全体を非同期的に翻訳できます。 このハウツー ガイドでは、選択したプログラミング言語と HTTP REST API でドキュメント翻訳 API を使用する方法について説明します。
前提条件
注
ドキュメント翻訳は、S1 Standard サービス プランと C2、C3、C4、D3 ボリューム割引プランでサポートされています。
開始するには、以下が必要です。
アクティブな Azure アカウント。 アカウントがない場合は、無料アカウントを作成できます
Azure Blob Storage アカウント。 Azure Blob Storage アカウント内に、ソースとターゲットの各ファイル用のコンテナーを作成する必要があります。
- ソースのコンテナー。 このコンテナーは、翻訳対象のファイルをアップロードする場所です (必須)。
- ターゲットコンテナー。 このコンテナーは、翻訳されたファイルを格納する場所です (必須)。
-
次のように、Translator プロジェクトとインスタンスの詳細フィールドを入力します。
[サブスクリプション]。 使用できる Azure サブスクリプションのいずれかを選択します。
[リソース グループ]。 新しいリソース グループを作成するか、同じライフサイクル、アクセス許可、ポリシーを共有する既存のリソース グループにリソースを追加することができます。
[リソース リージョン] . ご自身のビジネスまたはアプリケーションが特定のリージョンを必要としない限り、 [グローバル] を選択します。 認証にシステム割り当てマネージド ID を使用する場合は、米国西部などの地理的リージョンを選択します。
名前。 リソースに選んだ名前を入力します。 選択した名前は Azure 内で一意である必要があります。
注
ドキュメント変換には、カスタム ドメイン エンドポイントが必要です。 名前フィールドに入力する値は、エンドポイントのカスタム ドメイン名となります。
価格レベル。 Free レベルでは、ドキュメント翻訳はサポートされていません。 このサービスを試すには、Standard S1 を選択してください。
[確認および作成] を選択します。
サービス条件を確認し、 [作成] を選択してリソースをデプロイします。
リソースが正常にデプロイされたら、[リソースに移動] を選択してキーとエンドポイントを取得します。
キーとカスタム ドメイン エンドポイントを取得する
- Translator への要求では、アクセスを認証するために読み取り専用キーとカスタム エンドポイントが必要です。 カスタム ドメイン エンドポイントは、リソース名、ホスト名、Translator サブディレクトリを指定した形式の URL であり、Azure portal で使用できます。
新しいリソースを作成した場合は、そのデプロイ後に [リソースに移動] を選びます。 既存のドキュメント翻訳リソースがある場合は、リソース ページに直接移動します。
左側のレールの [リソース管理] で、 [キーとエンドポイント] を選択します。
自分の
keyとdocument translation endpointをコピーして、使いやすい場所 ("Microsoft メモ帳" など) に貼り付けます。 API 呼び出しを行うために必要なキーは 1 つだけです。要求をドキュメント翻訳サービスで認証するために、コードサンプルに
keyとdocument translation endpointを入力します。![Azure portal の [キーの取得] フィールドを示すスクリーンショット。](../media/document-translation-key-endpoint.png)
キーを取得する
Translator への要求には、アクセスを認証するための読み取り専用キーが必要です。
- 新しいリソースを作成した場合は、そのデプロイ後に [リソースに移動] を選びます。 既存のドキュメント翻訳リソースがある場合は、リソース ページに直接移動します。
- 左側のレールの [リソース管理] で、 [キーとエンドポイント] を選択します。
- 自分のキーをコピーして、使いやすい場所 ("Microsoft メモ帳" など) に貼り付けます。
- これをコード サンプルに貼り付けて、ドキュメント翻訳サービスに対する要求を認証します。
Azure Blob Storage コンテナーを作成する
Azure Blob Storage アカウント内に、ソースおよびターゲットの各ファイル用のコンテナーを作成する必要があります。
- ソースのコンテナー。 このコンテナーは、翻訳対象のファイルをアップロードする場所です (必須)。
- ターゲットコンテナー。 このコンテナーは、翻訳されたファイルを格納する場所です (必須)。
注
ドキュメント翻訳では、用語集がターゲット コンテナー内の BLOB としてサポートされます (個別の用語集コンテナーではありません)。 カスタム用語集を含める場合は、それをターゲット コンテナーに追加し、要求に glossaryUrl を含める必要があります。 翻訳言語のペアが用語集に存在しない場合は、用語集は適用されません。 「カスタム用語集を使用してドキュメントを翻訳する」を "参照してください"
ドキュメント変換用の SAS アクセス トークンを作成する
sourceUrl、targetUrl、省略可能な glossaryUrl には Shared Access Signature (SAS) トークンを含める必要があり、クエリ文字列として追加します。 トークンは、コンテナーまたは特定の BLOB に割り当てることができます。
ドキュメント変換プロセスの SAS トークンの作成を参照してください。
- ソースのコンテナーまたは BLOB には、読み取りと一覧表示のアクセス権が指定されている必要があります。
- ターゲットのコンテナーまたは BLOB には、書き込みと一覧表示のアクセス権が指定されている必要があります。
- 用語集の BLOB には、読み取りと一覧表示のアクセス権が指定されている必要があります。
ヒント
- 操作で複数のファイル (BLOB) を翻訳する場合は、コンテナー レベルで SAS アクセス権を委任します。
- 操作で 1 つ のファイル (BLOB) を翻訳する場合は、BLOB レベルで SAS アクセス権を委任します。
- SAS トークンの代わりに、システム割り当てマネージド ID を認証に使用することができます。
HTTP 要求
非同期バッチ翻訳要求は、POST 要求を介して Translator エンドポイントに送信されます。 成功した場合、POST メソッドから 202 Accepted 応答コードが返され、サービスによってバッチ要求が作成されます。 翻訳されたドキュメントがターゲット コンテナーに一覧表示されます。
Azure Translator 要求の制限の詳細については、「ドキュメント翻訳要求の制限」を参照してください。
HTTP ヘッダー
各ドキュメント翻訳 API 要求には、次のヘッダーが含まれています。
| HTTP ヘッダー | 説明 |
|---|---|
| Ocp-Apim-Subscription-Key | 必須: 値は、Translator または Microsoft Foundry リソースの Azure キーです。 |
| コンテンツタイプ | 必須: ペイロードのコンテンツ タイプを指定します。 許容される値は、application/json または charset=UTF-8 です。 |
POST 要求本文のプロパティ
- Post 要求の URL は POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batchesです。 - POST 要求本文は、
inputsという名前の JSON オブジェクトです。 -
inputsオブジェクトには、ソースとターゲットの言語ペア用のsourceURLとtargetURLのコンテナー アドレスが両方とも含まれています。 -
prefixとsuffixは、翻訳対象のソース パス内のドキュメントをフィルター処理するための、大文字と小文字を区別する文字列です。prefixフィールドは、翻訳用のサブフォルダーを表現するためによく使われます。suffixフィールドは、ファイルの拡張子に最もよく使われます。 -
glossariesフィールド (省略可能) の値は、ドキュメントが翻訳されるときに適用されます。 - 各ターゲット言語の
targetUrlは一意でなければなりません。
注
同じ名前のファイルが宛先に既に存在する場合、ジョブは失敗します。
コンテナー内のすべてのドキュメントを翻訳する
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
BLOB ストレージ コンテナー内の特定のドキュメントを翻訳する
-
"storageType": "File"を指定します。 - システム割り当てマネージド ID を認証に使っていない場合は、(コンテナーではなく) 特定の BLOB またはドキュメントに対して、ソース URL と SAS トークンが作成されていることを確認してください。
- ターゲット URL の一部としてターゲット ファイル名が指定されていることを確認してください (ただし、SAS トークンはコンテナー用のままです)。
- サンプル要求では、1 つのドキュメントが 2 つのターゲット言語に翻訳されたものが返されます。
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Word ドキュメント (.docx) およびPowerPoint ファイル (.pptx) 内の画像を翻訳する
ドキュメント翻訳では、Word ドキュメントおよびPowerPoint ファイル内の画像内のテキスト翻訳がサポートされます。 この機能は、 .docx および .pptx ファイル形式のバッチ ドキュメント変換 API で使用できます。
要求の構成
translateTextWithinImageフィールドで省略可能なoptionsパラメーターを使用する- データ型: ブール値 (
trueまたはfalse) - 既定のブール値設定は
falseです。 このオプションをtrueに設定して、画像テキストの翻訳を有効にします。
- データ型: ブール値 (
JSON 要求の例を次に示します。
{ "inputs": [ { "source": { "sourceUrl": "<SAS-URL>", "language": "en" }, "targets": [ { "targetUrl": "<SAS-URL>", "language": "ta" } ] } ], "options": { "translateTextWithinImage": true } }応答の詳細。 この機能を有効にすると、追加された画像処理情報が応答に含まれます。
totalImageScansSucceeded。 正常に翻訳された画像スキャンの数。totalImageScansFailed。 処理に失敗した画像スキャンの数。
JSON 応答の例を次に示します。
{ "id": "1a2b0c23-45d6-789-a123-a456fdaf7890", "createdDateTimeUtc": "2024-11-13T22:06:58.2789197Z", "lastActionDateTimeUtc": "2024-11-13T22:07:14.1608283Z", "status": "Running", "summary": { "total": 1, "failed": 0, "success": 0, "inProgress": 1, "notYetStarted": 0, "cancelled": 0, "totalCharacterCharged": 1355, "totalImageScansSucceeded": 2, "totalImageScansFailed": 0 } }
カスタム用語集を使用してドキュメントを翻訳する
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
コードを使用してドキュメント翻訳要求を送信する
コーディング プラットフォームを設定する
- 新しいプロジェクトを作成します。
- Program.cs を C# コード サンプルで置き換えます。
- エンドポイント、キー、コンテナー URL の値を Program.cs に設定します。
- JSON データを処理するために、.NET CLI を使用して Newtonsoft.Json パッケージを追加します。
- プロジェクト ディレクトリからプログラムを実行します。
重要
コード サンプルでは、示されている場所に Shared Access Signature (SAS) URL をハードコーディングします。 終了したら、コードから SAS の URL を削除し、決して公開しないようにしてください。 本番環境では、Azure マネージド ID のような、資格情報を安全に保存してアクセスできる方法を使用してください。 詳細については、「Azure Storage のセキュリティ」を参照してください。
操作によっては、次のフィールドの更新が必要になる場合があります。
endpointbasePathkeysourceURLtargetURLglossaryURL-
id(ジョブ ID)
id 値の検索
- ジョブ
idは、POSTstart-batch-translationメソッドの応答ヘッダーOperation-Locationの URL 値で確認します。/document/パラメーターの後に続く英数字の文字列は、操作のジョブidです。
| 応答ヘッダー | 応答 URL |
|---|---|
| Operation-Location | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- また、get-translations-status 要求を使用して、翻訳 ジョブ とその
idの一覧を取得することもできます。
非同期バッチ翻訳を開始する
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"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(basePath + 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 basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + 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);
}
}
翻訳ジョブの状態を取得する
1 つのジョブの現在の状態と、ドキュメント変換要求内のすべてのジョブの概要を取得します。 成功した場合、このメソッドから 200 OK 応答コードが返されます。
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + 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 basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + 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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + 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);
}
}
一般的な HTTP 状態コード
| HTTP 状態コード | 説明 | 考えられる理由 |
|---|---|---|
| 200 | [OK] | 要求は成功しました。 |
| 400 | 正しくない要求 | 必須パラメーターが指定されていない、空、または null です。 または、必須またはオプションのパラメーターに渡された値が無効です。 一般的な問題は、ヘッダーが長すぎる場合です。 |
| 401 | 権限がありません | 要求は承認されません。 キーまたはトークンが有効であり、正しいリージョンにあることを確認してください。 |
| 429 | 要求が多すぎます | 使用中のサブスクリプションで許可されている要求のクォータまたは速度を超えています。 |
| 502 | 無効なゲートウェイ | ネットワークまたはサーバー側の問題です。 無効なヘッダーを示す場合もあります。 |