次の方法で共有


バッチ翻訳を開始する

リファレンス
機能: 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/jsontext/jsonapplication/*+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-statusget-documents-statusget-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の一覧を取得することもできます。

応答状態コード

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

次のステップ

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