翻訳の開始
この API を使用して、Document Translation サービスで翻訳要求を開始します。 各要求には複数のドキュメントを含めることができ、各ドキュメントのソースと宛先のコンテナーが含まれている必要があります。
フォルダーをフィルター処理するには、プレフィックスとサフィックスのフィルター (指定された場合) を使用します。 プレフィックスは、コンテナー名の後のサブパスに適用されます。
用語集および翻訳メモリは、要求に含めることができ、ドキュメントが翻訳されるときにサービスによって適用されます。
翻訳中に用語集が無効であったり、到達できなかったりした場合は、ドキュメントの状態にエラーが表示されます。 同じ名前のファイルが宛先に既に存在する場合、ジョブは失敗します。 各ターゲット言語の targetUrl は一意でなければなりません。
要求 URL
POST 要求の送信先は次のとおりです。
POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches
カスタム ドメイン名を見つける方法について説明します。
重要
- ドキュメント翻訳サービスへのすべての API 要求には、カスタム ドメイン エンドポイントが必要です。
- ドキュメント翻訳への HTTP 要求を行うために、Azure portal リソースの [キーとエンドポイント] ページで見つかるエンドポイントも、グローバル Translator エンドポイント
api.cognitive.microsofttranslator.comも使用することはできません。
要求ヘッダー
要求ヘッダーを次に示します。
| ヘッダー | 説明 |
|---|---|
| Ocp-Apim-Subscription-Key | 必要な要求ヘッダー |
要求本文: バッチ送信要求
| 名前 | Type | 説明 |
|---|---|---|
| inputs | BatchRequest[] | 下に示される BatchRequest。 ドキュメントまたはドキュメントを含むフォルダーの入力リストです。 メディアの種類: "application/json"、"text/json"、"application/*+json"。 |
入力
入力バッチの翻訳要求に関する定義。
| 名前 | Type | 必須 | 説明 |
|---|---|---|---|
| source | SourceInput[] | はい | 下に示される inputs.source。 入力ドキュメントのソースです。 |
| storageType | StorageInputType[] | False | 下に示される inputs.storageType。 入力ドキュメントのソース文字列のストレージ型です。 1 つのドキュメントを翻訳する場合にのみ必要です。 |
| ターゲット | TargetInput[] | はい | 下に示される inputs.target。 出力先の場所です。 |
inputs.source
入力ドキュメントのソースです。
| 名前 | Type | 必須 | 説明 |
|---|---|---|---|
| filter | DocumentFilter[] | いいえ | 下に示される DocumentFilter[]。 |
| filter.prefix | string | いいえ | 翻訳対象のソースパス内のドキュメントをフィルター処理するための、大文字と小文字を区別するプレフィックス文字列。 たとえば、Azure ストレージ BLOB の URI を使用する場合は、プレフィックスを使用して、翻訳対象のサブフォルダーを制限します。 |
| filter.suffix | string | いいえ | 翻訳対象のソースパス内のドキュメントをフィルター処理するための、大文字と小文字を区別するサフィックス文字列。 これは、ファイル拡張子に対して最もよく使用されます。 |
| language | string | いいえ | 言語コードが指定されていない場合は、ドキュメントに対して自動検出を実行します。 |
| sourceUrl | string | True | ドキュメントを含むフォルダーまたはコンテナーあるいは単一ファイルの場所。 |
| storageSource | StorageSource | いいえ | 下に示される StorageSource。 |
| storageSource.AzureBlob | string | いいえ |
inputs.storageType
入力ドキュメントのソース文字列のストレージ型です。
| 名前 | Type |
|---|---|
| file | string |
| folder | string |
inputs.target
完成した翻訳済みドキュメントの宛先。
| 名前 | Type | 必須 | 説明 |
|---|---|---|---|
| category | string | いいえ | 翻訳要求のカテゴリまたはカスタム システム。 |
| 用語集 | Glossary[] | いいえ | 下に示される用語集。 用語集の一覧。 |
| glossaries.format | string | いいえ | フォーマットします。 |
| glossaries.glossaryUrl | string | True (用語集を使用する場合) | 用語集の場所。 format パラメーターが指定されていない場合は、ファイル拡張子を使用して書式設定を抽出します。 翻訳言語のペアが用語集に存在しない場合は、適用されません。 |
| glossaries.storageSource | StorageSource | いいえ | 上に示される StorageSource。 |
| glossaries.version | string | いいえ | バージョン (省略可能)。 指定しない場合は、既定値が使用されます。 |
| targetUrl | string | True | ドキュメントを含むフォルダーまたはコンテナーの場所。 |
| language | string | True | 2 文字のターゲット言語コード。 言語コードの一覧に関するページを参照してください。 |
| storageSource | StorageSource [] | いいえ | 上に示される StorageSource []。 |
要求の例
バッチ要求の例を下に示します。
注意
次の例では、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 トークンはコンテナー用のままです)。
下のサンプル要求では、1 つのドキュメントが 2 つのターゲット言語に翻訳されています
{
"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 | 現在サービスが使用できません。 後でもう一度やり直してください。 |
| その他の状態コード |
|
エラー応答
| 名前 | Type | 説明 |
|---|---|---|
| code | string | 高レベルのエラー コードを含む列挙型。 指定できる値
|
| message | string | 高レベルのエラー メッセージを取得します。 |
| innerError | InnerTranslationError | Cognitive Services API のガイドラインに準拠した新しい内部エラー形式。 必須プロパティとして ErrorCode、message、省略可能プロパティとして target、details (キーと値のペア)、inner error (入れ子が可能) が含まれています。 |
| 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.0/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"
}
}
}
次のステップ
クイックスタートに従って、ドキュメント翻訳とクライアント ライブラリの使用について学習します。