以程式設計方式使用 REST API
文件翻譯是 Azure 翻譯工具服務的雲端式功能。 您可以使用文件翻譯 API，使用支援的語言和各種檔案格式以非同步方式翻譯整份文件，同時保留來源文件結構和文字格式。 在本操作指南中，您將了解如何使用文件翻譯 API 搭配您選擇的程式設計語言和 HTTP REST API。
必要條件
注意
一般來說，在 Azure 入口網站中建立 Azure AI 資源時，您可選擇建立多服務金鑰或單一服務金鑰。 不過，文件翻譯目前僅受翻譯工具 (單一服務) 資源支援，但不包含在 Azure AI 服務 (多服務) 資源中。
文件翻譯可在 S1 標準服務方案 (隨用隨付) 和 C2、C3、C4 及 D3 大量折扣方案中受到支援。 請參閱Azure AI 服務定價—翻譯工具。
若要開始，您需要：
Azure Blob 儲存體帳戶。 您也必須在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器：
- 來源容器。 可會在此容器中上傳要翻譯的檔案 (必要)。
- 目標容器。 此容器是翻譯的檔案所將儲存之處 (必要)。
單一服務翻譯工具資源 (不是多服務 Azure AI 服務資源)：
完成翻譯工具專案和執行個體詳細資料欄位，如下所示：
訂用帳戶。 選取您可用的一個 Azure 訂用帳戶。
資源群組。 您可以建立新的資源群組，或將資源新增至共用相同生命週期、權限和原則的預先存在資源群組。
資源區域。 除非您的業務或應用程式需要特定區域，否則請選擇 [全域]。 如果您打算使用系統指派的受控識別 進行驗證，請選擇地理區域，例如美國西部。
名稱. 輸入您為資源選擇的名稱。 您所選擇的名稱在 Azure 中必須是唯一的。
注意
文件翻譯需要自訂網域端點。 您在名稱欄位中輸入的值將做為端點的自訂網域名稱參數。
定價層。 免費服務層級不支援文件翻譯。 若要嘗試服務，請選取 [標準 S1]。
選取 [檢閱 + 建立] 。
檢閱服務條款，然後選取 [建立] 以部署資源。
成功部署資源之後，請選取 [移至資源] 以擷取金鑰與端點。
擷取金鑰和自訂網域端點
- 對翻譯工具服務的要求需要唯讀金鑰和自訂端點，才能驗證存取權。 自訂網域端點是以您的資源名稱、主機名稱和翻譯工具子目錄格式化的 URL，可在 Azure 入口網站取得。
如果您已建立新的資源，在部署之後，請選取 [前往資源]。 如果您有現有的文件翻譯資源，請直接瀏覽至您的資源頁面。
在左側滑軌中，於 [資源管理] 下選取 [金鑰和端點]。
複製您的
key和document translation endpoint並貼入方便的位置，例如 Microsoft 記事本。 呼叫 API 只需一把金鑰。將您的
key和document translation endpoint貼到程式碼範例中，以驗證文件翻譯服務的要求。
取得金鑰
翻譯工具服務的要求需要唯讀金鑰才能驗證存取權。
- 如果您已建立新的資源，在部署之後，請選取 [前往資源]。 如果您有現有的文件翻譯資源，請直接瀏覽至您的資源頁面。
- 在左側滑軌中，於 [資源管理] 下選取 [金鑰和端點]。
- 複製金鑰並貼入方便的位置，例如 Microsoft 記事本。
- 您會將其貼到程式碼範例中，以驗證文件翻譯服務的要求。
建立 Azure Blob 儲存體容器
您必須在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器。
- 來源容器。 可會在此容器中上傳要翻譯的檔案 (必要)。
- 目標容器。 此容器是翻譯的檔案所將儲存之處 (必要)。
注意
文件翻譯支援以字彙作為目標容器 (而非個別字彙容器) 中的 Blob。 若要包含自訂字彙，請將其新增至目標容器，並包含 glossaryUrl 與要求。 如果字彙中沒有翻譯語言配對，則不會套用。 請參閱使用自訂字彙翻譯文件
建立文件翻譯的 SAS 存取權杖
sourceUrl、targetUrl 和選擇性 glossaryUrl 必須包含共用存取簽章 (SAS) 權杖，並附加為查詢字串。 權杖可以指派給您的容器或特定 Blob。 請參閱建立文件翻譯程序的 SAS 權杖。
- 您的來源容器或 Blob 必須具有指定的讀取和列出存取權。
- 您的目標容器或 Blob 必須具有指定的寫入和列出存取權。
- 您的字彙 Blob 必須具有指定的讀取和列出存取權。
提示
- 如果您要在單一作業中翻譯多個檔案 (Blob)，請在容器層級委派 SAS 存取權。
- 如果您要在一個作業中翻譯單一檔案 (Blob)，請在 Blob 層級委派 SAS 存取權。
- 作為 SAS 權杖的替代方案，您可以使用系統指派的受控識別來進行驗證。
HTTP 要求
非同步批次翻譯要求會透過 POST 要求提交至您的翻譯工具服務端點。 如果成功，POST 方法會傳回 202 Accepted 回應碼，且服務會建立批次要求。 翻譯的文件會列在您的目標容器中。
如需有關 Azure AI 翻譯工具服務要求限制的詳細資訊，請參閱文件翻譯要求限制。
HTTP 標頭
每個文件翻譯 API 要求都會包含下列標頭：
| HTTP 標頭 | 描述 |
|---|---|
| Ocp-Apim-Subscription-Key | 必要：此值是翻譯工具或 Azure AI 服務資源的 Azure 金鑰。 |
| 內容-類型 | 必要：指定承載的內容類型。 接受的值為 application/json 或 charset=UTF-8。 |
POST 要求本文屬性
- POST 要求 URL 為 POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches。 - POST 要求本文是名為
inputs的 JSON 物件。 inputs物件包含來源和目標語言配對的sourceURL和targetURL容器位址。prefix和suffix要區分大小寫字串，用來篩選來源路徑中要翻譯的文件。prefix欄位通常用來分隔要翻譯的子資料夾。suffix欄位最常用於副檔名。- 在翻譯文件時，會套用
glossaries欄位 (選擇性) 的值。 - 每個目標語言的
targetUrl都必須是唯一的。
注意
如果目的地中已存在相同名稱的檔案，則工作會失敗。
翻譯容器中的所有文件
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
翻譯容器中的特定文件
- 指定
"storageType": "File"。 - 如果您未使用系統指派的受控識別進行驗證，請確定您已針對特定 Blob/文件 (而不是針對容器) 建立來源 URL 與 SAS 權杖。
- 確定您已在目標 URL 中指定目標檔案名稱；不過 SAS 權杖仍適用於容器。
- 此要求範例會傳回翻譯成兩種目標語言的單一文件。
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
使用自訂字彙翻譯文件
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
使用程式碼來提交文件翻譯要求
設定您的編碼平台
- 建立新的 專案。
- 以 C# 程式碼範例取代 Program.cs。
- 在 Program.cs 中設定您的端點、金鑰和容器 URL 值。
- 使用 .NET CLI 新增 Newtonsoft.Json 套件來處理 JSON 資料。
- 從專案目錄執行程式。
重要
在程式碼範例中，您會在指示的位置中為共用存取簽章 (SAS) URL 進行硬式編碼。 請記得在完成時請從程式碼中移除金鑰，且切勿公開發佈 SAS URL。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure 受控識別。 如需詳細資訊，請參閱 Azure 儲存體安全性。
您可能需要更新下列欄位，視作業而定：
endpointbasePathkeysourceURLtargetURLglossaryURLid(作業識別碼)
尋找 id 值
- 您會在 POST
start-batch-translation方法回應標頭Operation-LocationURL 值中找到作業id。/document/參數後面的英數位元字串是作業的id作業：
| 回應標頭 | 回應 URL |
|---|---|
| Operation-Location | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version={date} |
- 您也可以使用 get-translations-status 要求來擷取翻譯作業及其
id的清單。
啟動非同步批次翻譯
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
取得支援的檔案格式
擷取支援的檔案格式清單。 如果成功，這個方法會傳回 200 OK 回應碼。
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
取得翻譯作業的狀態
取得單一作業的目前狀態，以及文件翻譯要求中所有作業的摘要。 如果成功，這個方法會傳回 200 OK 回應碼。
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
}
取得特定文件的狀態
簡要概觀
擷取文件翻譯要求中特定文件的狀態。 如果成功，這個方法會傳回 200 OK 回應碼。
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
刪除作業
簡要概觀
取消目前正在處理或已排入佇列的作業。 只有未開始翻譯的文件才會取消。
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
常見的 HTTP 狀態碼
| HTTP 狀態碼 | 描述 | 可能的原因 |
|---|---|---|
| 200 | 確定 | 要求成功。 |
| 400 | 不正確的要求 | 必要的參數遺失、為空白或 Null。 或者，傳遞至必要或選用參數的值無效。 常見的問題是標頭太長。 |
| 401 | 未經授權 | 要求未獲授權。 請檢查以確定您的金鑰或權杖有效，並且位於正確的區域。 在 Azure 入口網站管理您的訂閱時，確認您使用的是翻譯工具單一服務資源，而「不是」Azure AI 服務的多服務資源。 |
| 429 | 過多要求 | 您已超出訂用帳戶允許的配額或要求率。 |
| 502 | 錯誤的閘道 | 網路或伺服器端問題。 也可能表示標頭無效。 |