バッチ翻訳を開始する

[アーティクル]
09/26/2024

リファレンス
機能: 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.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

入力

入力バッチの翻訳要求に関する定義。

主なパラメーター	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 は、POST start-batch-translation メソッドの応答ヘッダー Operation-Location の URL 値で確認します。 /document/ パラメーターの後に続く英数字の文字列は、操作のジョブ id です。

応答ヘッダー 応答 URL

Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
get-translations-status 要求を使用して、翻訳ジョブとそのidの一覧を取得することもできます。

応答ヘッダー	応答 URL
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`?api-version=2024-05-01

応答状態コード

要求によって返される可能性のある 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"
    }
  }
}

次のステップ

クイックスタートに従って、ドキュメント翻訳とクライアントライブラリの使用について学習します。

ドキュメント変換を使ってみる

次の方法で共有