翻訳の開始

[アーティクル]
02/12/2024

リファレンス
サービス: Azure AI ドキュメント翻訳
API バージョン: v1.1

この API を使用して、Document Translation サービスで翻訳要求を開始します。各要求には複数のドキュメントを含めることができ、各ドキュメントのソースと宛先のコンテナーが含まれている必要があります。

フォルダーをフィルター処理するには、プレフィックスとサフィックスのフィルター (指定された場合) を使用します。プレフィックスは、コンテナー名の後のサブパスに適用されます。

用語集および翻訳メモリは、要求に含めることができ、ドキュメントが翻訳されるときにサービスによって適用されます。

翻訳中に用語集が無効であったり、到達できなかったりした場合は、ドキュメントの状態にエラーが表示されます。同じ名前のファイルが宛先に既に存在する場合、ジョブは失敗します。各ターゲット言語の targetUrl は一意でなければなりません。

要求 URL

POST 要求の送信先は次のとおりです。

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

カスタムドメイン名を見つける方法について説明します。

重要

ドキュメント翻訳サービスへのすべての API 要求には、カスタムドメインエンドポイントが必要です。
ドキュメント翻訳への HTTP 要求を行うために、Azure portal リソースの [キーとエンドポイント] ページで見つかるエンドポイントも、グローバル Translator エンドポイント api.cognitive.microsofttranslator.com も使用することはできません。

要求ヘッダー

要求ヘッダーを次に示します。

ヘッダー	説明
Ocp-Apim-Subscription-Key	必要な要求ヘッダー

BatchRequest (本文)

入力バッチの翻訳要求に関する定義。各要求には複数のドキュメントを含めることができ、各ドキュメントのソースとターゲットのコンテナーが含まれている必要があります。ソースメディアの種類: application/json、text/json、application/*+json。


{
  "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	• 文字列	ターゲットのストレージソース。既定値は `_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?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

コンテナー内のすべてのドキュメントを翻訳して用語集を適用する

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

コンテナー内の特定のフォルダーを翻訳する

フィルターでは、フォルダー名 (大文字と小文字が区別されます) をプレフィックスとして指定してください。

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "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?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

応答状態コード

要求によって返される可能性のある HTTP 状態コードを次に示します。

状態コード	説明
202	受理されました。要求が成功し、バッチ要求が作成されます。ヘッダー Operation-Location は、ID.HeadersOperation-Location: string という操作の状態 URL を示します
400	正しくない要求。無効な要求です。入力パラメーターを確認してください。
401	権限がありません。資格情報を確認してください。
429	要求レートが高すぎます。
500	内部サーバーエラー。
503	現在サービスが使用できません。後でもう一度やり直してください。
その他の状態コード	• 要求が多すぎます • サーバーの一時的な利用不可

エラー応答

主なパラメーター	型	説明
code	`string`	高レベルのエラーコードを含む列挙型。指定できる値 InternalServerError InvalidArgument InvalidRequest RequestRateTooHigh ResourceNotFound ServiceUnavailable 権限がありません
メッセージ	`string`	高レベルのエラーメッセージを取得します。
innerError	InnerTranslationError	Azure AI サービス API のガイドラインに準拠した新しい内部エラー形式。このエラーメッセージには、ErrorCode、message、および省略可能なプロパティターゲット、details(キー値ペア)、および内部エラー (入れ子にできる) の必須プロパティが含まれています。
inner.Errorcode	`string`	コードエラー文字列を取得します。
innerError.message	`string`	高レベルのエラーメッセージを取得します。
innerError.target	`string`	エラーのソースを取得します。たとえば、ドキュメントが無効な場合には `documents` または `document id` になります。

例

成功した応答の例

成功した応答では、次の情報が返されます。

ジョブ ID は、POST メソッドの応答ヘッダー Operation-Location URL 値で確認できます。 URL の最後のパラメーターは、操作のジョブ ID ("/operation/" に続く文字列) です。

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

エラー応答の例

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

次のステップ

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

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