バッチ翻訳を開始する
リファレンス
機能: Azure AI 翻訳 → ドキュメント翻訳
API バージョン: 2024-05-01
HTTP メソッド: POST
- 非同期バッチ変換要求を実行するには、
Start Translation
メソッドを使用します。 - この方法では、ソースドキュメントと翻訳済みドキュメントのストレージ コンテナーを含む Azure BLOB ストレージ アカウントが必要です。
要求 URL
重要
ドキュメント翻訳機能に対するすべての API 要求に、Azure portal のリソース概要ページにあるカスタム ドメイン エンドポイントが必要です。
curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"
要求ヘッダー
要求ヘッダーを次に示します。
ヘッダー | 説明 | 条件 |
---|---|---|
Ocp-Apim-Subscription-Key | Azure portal からの Translator サービス API キー。 | 必須 |
Ocp-Apim-Subscription-Region | リソースが作成されたリージョン。 | 必須 米国. などのリージョン (地理的) リソースを使用する場合> 行頭文字。 |
Content-Type | ペイロードのコンテンツ タイプ。 許容される値は application/json または charset=UTF-8 です。 | 必須 |
BatchRequest (本文)
各要求には複数のドキュメントを含めることができ、各ドキュメントのソースとターゲットのコンテナーが含まれている必要があります。 ソース メディアの種類:
application/json
、text/json
、application/*+json
。フォルダーをフィルター処理するには、プレフィックスとサフィックスのフィルター (指定された場合) を使用します。 プレフィックスは、コンテナー名の後のサブパスに適用されます。
用語集は要求に含めることができます。 翻訳中に用語集が無効であったり、到達できなかったりした場合は、ドキュメントの状態にエラーが表示されます。
ターゲットの宛先に同じ名前のファイルが既に存在する場合、ジョブは失敗します。
各ターゲット言語の targetUrl は一意でなければなりません。
{
"inputs": [
{
"source": {
"sourceUrl": "https://myblob.blob.core.windows.net/Container/",
"filter": {
"prefix": "FolderA",
"suffix": ".txt"
},
"language": "en",
"storageSource": "AzureBlob"
},
"targets": [
{
"targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
"category": "general",
"language": "fr",
"glossaries": [
{
"glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.tsv",
"format": "XLIFF",
"version": "2.0",
"storageSource": "AzureBlob"
}
],
"storageSource": "AzureBlob"
}
],
"storageType": "Folder"
}
],
"options": {
"experimental": true
}
}
入力
入力バッチの翻訳要求に関する定義。
主なパラメーター | Type | 必須 | 要求パラメーター | 説明 |
---|---|---|---|---|
入力 | array |
True | • source (オブジェクト) • targets (配列) • storageType (文字列) |
入力ソース データ。 |
inputs.source
ソース データの定義。
主なパラメーター | Type | 必須 | 要求パラメーター | 説明 |
---|---|---|---|---|
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
ターゲットと用語集のデータの定義。
主なパラメーター | Type | 必須 | 要求パラメーター | 説明 |
---|---|---|---|---|
inputs.targets | array |
True | • targetUrl (文字列) • category (文字列) • language (文字列) • glossaries (配列) • storageSource (文字列) |
翻訳対象ドキュメントのターゲットと用語集のデータ。 |
inputs.targets.targetUrl | string |
True | • 文字列 | 翻訳対象ドキュメントのコンテナーの場所。 |
inputs.targets.category | string |
False | • 文字列 | 翻訳要求の分類またはカテゴリ。 例: general。 |
inputs.targets.language | string |
True | • 文字列 | ターゲット言語コード。 例: "fr"。 |
inputs.targets.glossaries | array |
False | • glossaryUrl (文字列) • format (文字列) • version (文字列) • storageSource (文字列) |
参照 用語集を作成して使用する |
inputs.targets.glossaries.glossaryUrl | string |
True (用語集を使用する場合) | • 文字列 | 用語集の場所。 format パラメーターが指定されていない場合は、ファイル拡張子を使用して書式設定を抽出します。 翻訳言語のペアが用語集に存在しない場合は、適用されません。 |
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 | • 文字列 | targets.defaults のストレージ ソースは _AzureBlob_ 。 |
inputs.storageType
入力ドキュメントのストレージ エンティティの定義。
主なパラメーター | Type | 必須 | 要求パラメーター | 説明 |
---|---|---|---|---|
inputs.storageType | string |
False | •Folder • File |
入力ドキュメントのソース文字列のストレージ型です。 有効な値は "Folder" または "File" のみです。 |
[オプション]
入力バッチの翻訳要求に関する定義。
主なパラメーター | Type | 必須 | 要求パラメーター | 説明 |
---|---|---|---|---|
options | object |
False | 入力ドキュメントのソース情報。 | |
options.experimental | boolean |
False | •true • false |
要求に実験用機能が含まれているかどうかを示します (該当する場合)。 有効な値はブール値 true または false のみです。 |
要求の例
バッチ要求の例を下に示します。
注意
次の例では、Shared Access Signature (SAS) トークンを使用して、Azure Storage コンテナーのコンテンツに制限付きアクセスが許可されています。
コンテナー内のすべてのドキュメントを翻訳する
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
"language": "fr"
}
]
}
]
}
コンテナー内のすべてのドキュメントを翻訳して用語集を適用する
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
"language": "fr",
"glossaries": [
{
"glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
"format": "xliff",
"version": "1.2"
}
]
}
]
}
]
}
コンテナー内の特定のフォルダーを翻訳する
フィルターでは、フォルダー名 (大文字と小文字が区別されます) をプレフィックスとして指定してください。
{
"inputs": [
{
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
"filter": {
"prefix": "MyFolder/"
}
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
"language": "fr"
}
]
}
]
}
コンテナー内の特定のドキュメントを翻訳する
- "storageType":
File
を指定します。 - 特定の BLOB/ドキュメントのソース URL と SAS トークンを作成します。
- ターゲット URL の一部としてターゲット ファイル名を指定します (ただし、SAS トークンはコンテナー用のままです)。
このサンプル要求は、2 つのターゲット言語に翻訳された 1 つのドキュメントを示しています。
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
},
"targets": [
{
"targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
"language": "es"
},
{
"targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
"language": "de"
}
]
}
]
}
ヒント
このメソッドは、get-translation-status、get-documents-status、get-document-status、および cancel-translation 要求クエリ文字列のジョブ 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=2024-05-01get-translations-status 要求を使用して、翻訳ジョブとその
id
の一覧を取得することもできます。
応答状態コード
要求によって返される可能性のある HTTP 状態コードを次に示します。
状態コード | 説明 |
---|---|
202 | 受理されました。 要求が成功し、バッチ要求が作成されます。 ヘッダー Operation-Location は、ID.HeadersOperation-Location: string という操作の状態 URL を示します |
400 | 正しくない要求。 無効な要求です。 入力パラメーターを確認してください。 |
401 | 権限がありません。 資格情報を確認してください。 |
429 | 要求レートが高すぎます。 |
500 | 内部サーバー エラー。 |
503 | 現在サービスが使用できません。 後でもう一度やり直してください。 |
その他の状態コード | • 要求が多すぎます。 サーバーが一時的に使用できない |
エラー応答
主なパラメーター | 型 | 説明 |
---|---|---|
code | string |
高レベルのエラー コードを含む列挙型。 使用可能な値:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • Unauthorized |
メッセージ | string |
高レベルのエラー メッセージを取得します。 |
innerError | InnerTranslationError | Azure AI サービス API のガイドラインに準拠した新しい内部エラー形式。 このエラー メッセージには、ErrorCode、message、および省略可能なプロパティ ターゲット、details(キー値ペア)、および内部エラー (入れ子にできる) の必須プロパティが含まれています。 |
inner.Errorcode | string |
コード エラー文字列を取得します。 |
innerError.message | string |
高レベルのエラー メッセージを取得します。 |
innerError.target | string |
エラーのソースを取得します。 たとえば、ドキュメントが無効な場合には documents または document id になります。 |
エラー応答の例
{
"error": {
"code": "ServiceUnavailable",
"message": "Service is temporary unavailable",
"innerError": {
"code": "ServiceTemporaryUnavailable",
"message": "Service is currently unavailable. Please try again later"
}
}
}
次のステップ
クイックスタートに従って、ドキュメント翻訳とクライアント ライブラリの使用について学習します。