開始批次翻譯

發行項
06/01/2024

參考
功能：Azure AI 翻譯工具 → 檔翻譯
API 版本：2024-05-01
HTTP 方法：POST

Start Translation使用方法來執行異步批次轉譯要求。
此方法需要具有來源和翻譯檔的記憶體容器的 Azure Blob 記憶體帳戶。

提示

這個方法會傳回 get-translation-status、get-documents-status 、get-document-status 和 cancel-translation 要求查詢字符串的作業id參數。

您可以在 POST start-batch-translation 方法回應標頭 Operation-Location URL 值中找到作業id。參數後面的 /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

重要

檔翻譯功能的所有 API 要求都需要位於 Azure 入口網站 中資源概觀頁面上的自定義網域端點。

  curl -i -X POST "{document-translation-endpoint}/translator/document/batches?api-version={date}"

要求標頭

要求標頭如下：

標題	描述	條件
Ocp-Apim-Subscription-Key	來自 Azure 入口網站的翻譯工具服務 API 金鑰。	必要
Ocp-Apim-Subscription-Region	資源建立的所在區域。	• 使用美國西部等區域（地理）資源時需要。 & 項目符號。
Content-Type	承載的內容類型。接受的值為 application/json 或 charset=UTF-8。	• 必要

BatchRequest （body）

每個要求都可以包含多個檔，而且必須包含每個檔的來源和目標容器。來源媒體類型： 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
  }
}

輸入

輸入批次轉譯要求的定義。

索引鍵參數	類型	必要	要求參數	描述
輸入	`array`	True	• source （object）• targets （array） • storageType （string）	輸入源數據。

inputs.source

源數據的定義。

索引鍵參數	類型	必要	要求參數	描述
inputs.source	`object`	True	• sourceUrl （string）• filter （object） • language （string） • storageSource （string）	輸入檔的源數據。
inputs.source.sourceUrl	`string`	True	•字串	來源檔案或資料夾的容器位置。
inputs.source.filter	`object`	False	• 前置詞（字串） • 後綴（string）	區分大小寫的字串，可篩選來源路徑中的檔。
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

目標與詞彙數據的定義。

索引鍵參數	類型	必要	要求參數	描述
inputs.targets	`array`	True	• targetUrl （string）• 類別（字串串） • 語言（字串） • 詞彙（陣列） • storageSource （string）	翻譯檔的目標和詞彙數據。
inputs.targets.targetUrl	`string`	True	•字串	已翻譯檔的容器位置位置。
inputs.targets.category	`string`	False	•字串	翻譯要求的分類或類別。範例：一般。
inputs.targets.language	`string`	True	•字串	目標語言代碼。範例：“fr”。
inputs.targets.glossaries	`array`	False	• 詞彙Url （string） • 格式（字串） • 版本（字符串） • storageSource （string）	請參閱建立和使用詞彙
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

輸入檔的記憶體實體定義。

索引鍵參數	類型	必要	要求參數	描述
inputs.storageType	`string`	False	•`Folder` • `File`	儲存體輸入檔來源字串的類型。只有「Folder」或「File」是有效的值。

選項。

輸入批次轉譯要求的定義。

索引鍵參數	類型	必要	要求參數	描述
options	`object`	False	輸入檔的來源資訊。
options.experimental	`boolean`	False	•`true` • `false`	指出要求是否包含實驗性功能（如果適用）。只有布爾值 `true` 或 `false` 是有效的值。

範例要求

以下是批次要求的範例。

注意

在下列範例中，已使用共用存取簽章（SAS）令牌，將有限的存取權授與 Azure 儲存體容器的內容。

翻譯容器中的所有檔

{
    "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 令牌仍適用於容器。

此範例要求顯示翻譯成兩種目標語言的單一檔。

{
    "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"
                }
            ]
        }
    ]
}

回應狀態代碼

以下是要求傳回的可能 HTTP 狀態碼。

狀態碼	描述
202	接受。要求成功，已建立批次要求。標頭 Operation-Location 以作業識別碼表示狀態 URL。標頭 HeadersOperation-Location：字串
400	不正確的要求。要求無效。檢查輸入參數。
401	未經授權。檢查您的認證。
429	要求率太高。
500	內部伺服器錯誤。
503	服務目前無法使用。請稍後再試一次。
其他狀態碼	• 要求太多。伺服器暫時無法使用

回覆錯誤

索引鍵參數	類型	描述
code	`string`	包含高階錯誤碼的列舉。可能的值：</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • 未經授權
message	`string`	取得高階錯誤訊息。
innerError	InnerTranslationError	符合 Azure AI 服務 API 指導方針的新內部錯誤格式。此錯誤訊息包含必要屬性：ErrorCode、訊息和選擇性屬性目標、詳細數據（索引鍵值組），以及內部錯誤（可以是巢狀）。
內。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"
    }
  }
}

下一步

請遵循我們的快速入門，深入瞭解如何使用文件翻譯和客戶端連結庫。

開始使用文件翻譯

共用方式為