共用方式為


以程式設計方式使用 REST API

文件翻譯是 Azure 翻譯工具服務的雲端式功能。 您可以使用文件翻譯 API,使用支援的語言和各種檔案格式以非同步方式翻譯整份文件,同時保留來源文件結構和文字格式。 在本操作指南中,您將了解如何使用文件翻譯 API 搭配您選擇的程式設計語言和 HTTP REST API。

必要條件

注意

  • 一般來說,在 Azure 入口網站中建立 Azure AI 資源時,您可選擇建立多服務金鑰或單一服務金鑰。 不過,文件翻譯目前僅受翻譯工具 (單一服務) 資源支援,但包含在 Azure AI 服務 (多服務) 資源中。

  • 文件翻譯可在 S1 標準服務方案 (隨用隨付) 和 C2、C3、C4 及 D3 大量折扣方案中受到支援。 請參閱Azure AI 服務定價—翻譯工具

若要開始,您需要:

  • 作用中的 Azure 帳戶。 如果您沒有帳戶,您可以建立免費帳戶

  • Azure Blob 儲存體帳戶。 您也必須在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器

    • 來源容器。 可會在此容器中上傳要翻譯的檔案 (必要)。
    • 目標容器。 此容器是翻譯的檔案所將儲存之處 (必要)。
  • 單一服務翻譯工具資源 (不是多服務 Azure AI 服務資源):

    完成翻譯工具專案和執行個體詳細資料欄位,如下所示:

    1. 訂用帳戶。 選取您可用的一個 Azure 訂用帳戶。

    2. 資源群組。 您可以建立新的資源群組,或將資源新增至共用相同生命週期、權限和原則的預先存在資源群組。

    3. 資源區域。 除非您的業務或應用程式需要特定區域,否則請選擇 [全域]。 如果您打算使用系統指派的受控識別 進行驗證,請選擇地理區域,例如美國西部

    4. 名稱. 輸入您為資源選擇的名稱。 您所選擇的名稱在 Azure 中必須是唯一的。

      注意

      文件翻譯需要自訂網域端點。 您在名稱欄位中輸入的值將做為端點的自訂網域名稱參數。

    5. 定價層。 免費服務層級不支援文件翻譯。 若要嘗試服務,請選取 [標準 S1]。

    6. 選取 [檢閱 + 建立] 。

    7. 檢閱服務條款,然後選取 [建立] 以部署資源。

    8. 成功部署資源之後,請選取 [移至資源]擷取金鑰與端點

擷取金鑰和自訂網域端點

  • 對翻譯工具服務的要求需要唯讀金鑰和自訂端點,才能驗證存取權。 自訂網域端點是以您的資源名稱、主機名稱和翻譯工具子目錄格式化的 URL,可在 Azure 入口網站取得。
  1. 如果您已建立新的資源,在部署之後,請選取 [前往資源]。 如果您有現有的文件翻譯資源,請直接瀏覽至您的資源頁面。

  2. 在左側滑軌中,於 [資源管理] 下選取 [金鑰和端點]

  3. 複製您的keydocument translation endpoint並貼入方便的位置,例如 Microsoft 記事本。 呼叫 API 只需一把金鑰。

  4. 將您的 keydocument translation endpoint 貼到程式碼範例中,以驗證文件翻譯服務的要求。

    Azure 入口網站中取得金鑰欄位的螢幕擷取畫面。

取得金鑰

翻譯工具服務的要求需要唯讀金鑰才能驗證存取權。

  1. 如果您已建立新的資源,在部署之後,請選取 [前往資源]。 如果您有現有的文件翻譯資源,請直接瀏覽至您的資源頁面。
  2. 在左側滑軌中,於 [資源管理] 下選取 [金鑰和端點]
  3. 複製金鑰並貼入方便的位置,例如 Microsoft 記事本
  4. 您會將其貼到程式碼範例中,以驗證文件翻譯服務的要求。

在 Azure 入口網站中取得金鑰的影像。

建立 Azure Blob 儲存體容器

您必須在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器

  • 來源容器。 可會在此容器中上傳要翻譯的檔案 (必要)。
  • 目標容器。 此容器是翻譯的檔案所將儲存之處 (必要)。

注意

文件翻譯支援以字彙作為目標容器 (而非個別字彙容器) 中的 Blob。 若要包含自訂字彙,請將其新增至目標容器,並包含 glossaryUrl 與要求。 如果字彙中沒有翻譯語言配對,則不會套用。 請參閱使用自訂字彙翻譯文件

建立文件翻譯的 SAS 存取權杖

sourceUrltargetUrl 和選擇性 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 物件包含來源和目標語言配對的 sourceURLtargetURL 容器位址。
  • prefixsuffix 要區分大小寫字串,用來篩選來源路徑中要翻譯的文件。 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 儲存體安全性

您可能需要更新下列欄位,視作業而定:

  • endpoint
  • basePath
  • key
  • sourceURL
  • targetURL
  • glossaryURL
  • id (作業識別碼)

尋找 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={date}

啟動非同步批次翻譯


    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 錯誤的閘道 網路或伺服器端問題。 也可能表示標頭無效。

深入了解

下一步