快速入門：Azure AI 翻譯工具 REST API

發行項
04/12/2024

試用最新版的 Azure AI 翻譯工具。在本快速入門中，您將開始使用翻譯工具服務，以您選擇的程式設計語言和 REST API 翻譯文字。針對此專案，在您同時學習技術時，建議您使用免費定價層 (F0)，並稍後再升級至生產環境的付費層。

必要條件

您需要作用中的 Azure 訂用帳戶。若還沒有 Azure 訂閱，您可以建立免費帳戶。

擁有 Azure 訂閱之後，請在 Azure 入口網站中建立翻譯工具資源。
部署資源之後，請選取 [前往資源] 擷取金鑰與端點。
- 您將需要來自資源的金鑰和端點，以將應用程式連線至翻譯工具服務。您稍後會在快速入門中將金鑰和端點貼到程式碼中。您可以在 Azure 入口網站的 [金鑰和端點] 頁面上找到這些值：
  注意
  - 本快速入門建議使用翻譯工具文字單一服務全域資源。
  - 使用單一服務全域資源，您可在 REST API 要求中包含一個授權標頭 (Ocp-Apim-Subscription-key)。 Ocp-Apim-Subscription-key 的值是翻譯工具文字訂閱的 Azure 祕密金鑰。
  - 如果您選擇使用 Azure AI 多服務或區域翻譯工具資源，則需要兩個驗證標頭 (Ocp-Api-Subscription-Key 和 Ocp-Apim-Subscription-Region)。 Ocp-Apim-Subscription-Region 的值是與您訂閱相關聯的區域。
  - 如需如何使用 Ocp-Apim-Subscription-Region 標頭的詳細資訊，請參閱文字翻譯 REST API 標頭。

標頭

若要透過 REST API 呼叫翻譯工具服務，您必須在每個要求中都包含下列標頭。別擔心，我們會為您在每個程式設計語言的範例程式碼中包含標頭。

如需翻譯工具驗證選項的詳細資訊，「請參閱」翻譯工具 v3 參考指南。

頁首	值	Condition
Ocp-Apim-Subscription-Key	來自 Azure 入口網站的翻譯工具服務金鑰。	• 必要
Ocp-Apim-Subscription-Region	資源建立的所在區域。	•使用 Azure AI 多服務或區域 (地理) 資源 (例如美國西部) 時，為必要項目。 •使用單一服務全域翻譯工具資源時，則為選擇性。
Content-Type	承載的內容類型。接受的值為 application/json 或 charset=UTF-8。	• 必要
Content-Length	要求本文的長度。	• 選擇性

重要

完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。如需詳細資訊，請參閱 Azure AI 服務安全性一文。

翻譯文字

翻譯工具服務的核心作業是翻譯文字。在本快速入門中，您要使用您選擇的程式設計語言來建置要求，該語言會採用單一來源 (from) 並提供兩個輸出 (to)。然後，我們將探討一些可用來同時調整要求和回應的參數。

如需有關 Azure AI 翻譯工具服務要求限制的詳細資訊，請參閱文字翻譯要求限制。

設定 Visual Studio 專案

請確定您已安裝最新版的 Visual Studio IDE。

提示

如果您尚不熟悉 Visual Studio，可以參考 Visual Studio 簡介 Learn 課程模組。
開啟 Visual Studio。
在開始頁面中，請選擇 [建立新專案]。
在 [建立新的專案] 頁面的搜尋方塊中，輸入主控台。選擇 [主控台應用程式] 範本，然後選擇 [下一步]。
在 [設定新專案] 對話方塊視窗中，於 [專案名稱] 方塊中輸入 translator_quickstart。 取消核取 [將解決方案和專案置於相同目錄中] 核取方塊，然後選取 [下一步]。
在 [其他資訊] 對話視窗中，請確定已選取 [.NET 6.0 (長期支援)]。 取消核取 [不要使用最上層陳述式] 核取方塊，並選取 [建立]。

使用 NuGet 安裝 Newtonsoft.json 套件

在您的 translator_quickstart 專案上按一下滑鼠右鍵，然後選取 [管理 NuGet 套件]。
選取 [瀏覽] 索引標籤並鍵入 Newtonsoft.json。
若要將套件新增至您的專案中，請從右側的套件管理員視窗中選取 [安裝]。

建置您的 C# 應用程式

注意

從 .NET 6 開始，使用 console 範本的新專案會產生與舊版不同的新程式樣式。
新輸出會使用最新的 C# 功能，以簡化您需要撰寫的程式碼。
當您使用較新版本時，只需要撰寫 Main 方法的本文。您不需要包含最上層陳述式、全域 Using 指示詞或隱含 Using 指示詞。
如需詳細資訊，請參閱新的 C# 範本產生最上層語句。

開啟 Program.cs 檔案。
刪除預先存在的程式碼，包含此行 Console.WriteLine("Hello World!")。將範例程式碼複製並貼入您的應用程式 Program.cs 檔案。請務必使用 Azure 入口網站翻譯工具執行個體的值來更新索引鍵變數：

using System.Text;
using Newtonsoft.Json;

class Program
{
    private static readonly string key = "<your-translator-key>";
    private static readonly string endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static readonly string location = "<YOUR-RESOURCE-LOCATION>";

    static async Task Main(string[] args)
    {
        // Input and output languages are defined as parameters.
        string route = "/translate?api-version=3.0&from=en&to=fr&to=zu";
        string textToTranslate = "I would really like to drive your car around the block a few times!";
        object[] body = new object[] { new { Text = textToTranslate } };
        var requestBody = JsonConvert.SerializeObject(body);

        using (var client = new HttpClient())
        using (var request = new HttpRequestMessage())
        {
            // Build the request.
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(endpoint + route);
            request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
            request.Headers.Add("Ocp-Apim-Subscription-Key", key);
            // location required if you're using a multi-service or regional (not global) resource.
            request.Headers.Add("Ocp-Apim-Subscription-Region", location);

            // Send the request and get response.
            HttpResponseMessage response = await client.SendAsync(request).ConfigureAwait(false);
            // Read response as a string.
            string result = await response.Content.ReadAsStringAsync();
            Console.WriteLine(result);
        }
    }
}

執行您的 C# 應用程式

將程式碼範例新增至應用程式之後，請選擇 formRecognizer_quickstart 旁的綠色 [開始] 按鈕來建置和執行程式，或按 F5。

Screenshot of the run program button in Visual Studio.

翻譯輸出：

呼叫成功後，您應該會看見下列回應：

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

設定您的 Go 環境

您可以使用任何文字編輯器來撰寫 Go 應用程式。建議使用最新版本的 Visual Studio Code 和 Go 延伸模組。

提示

如果您尚不熟悉 Go，可以參考開始使用 Go Learn 課程模組。

確定已安裝最新版本的 Go：
- 為您的作業系統下載 Go 版本。
- 下載完成後執行安裝程式。
- 開啟命令提示字元，並輸入下列命令確認已安裝 Go：
```
  go version
```

建置您的 Go 應用程式

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立一個名為 translator-app 的新目錄，並瀏覽至該目錄。
從 translator-app 目錄建立名為 translation.go 的新 GO 檔案。
將提供的程式碼範例複製並貼入您的 translation.go 檔案。請務必使用 Azure 入口網站翻譯工具執行個體的值來更新索引鍵變數：

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "net/url"
)

func main() {
    key := "<YOUR-TRANSLATOR-KEY>"
    endpoint := "https://api.cognitive.microsofttranslator.com/"
    uri := endpoint + "/translate?api-version=3.0"

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    location := "<YOUR-RESOURCE-LOCATION>"

    // Build the request URL. See: https://go.dev/pkg/net/url/#example_URL_Parse
    u, _ := url.Parse(uri)
    q := u.Query()
    q.Add("from", "en")
    q.Add("to", "fr")
    q.Add("to", "zu")
    u.RawQuery = q.Encode()

    // Create an anonymous struct for your request body and encode it to JSON
    body := []struct {
        Text string
    }{
        {Text: "I would really like to drive your car around the block a few times."},
    }
    b, _ := json.Marshal(body)

    // Build the HTTP POST request
    req, err := http.NewRequest("POST", u.String(), bytes.NewBuffer(b))
    if err != nil {
        log.Fatal(err)
    }
    // Add required headers to the request
    req.Header.Add("Ocp-Apim-Subscription-Key", key)
    // location required if you're using a multi-service or regional (not global) resource.
    req.Header.Add("Ocp-Apim-Subscription-Region", location)
    req.Header.Add("Content-Type", "application/json")

    // Call the Translator API
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatal(err)
    }

    // Decode the JSON response
    var result interface{}
    if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
        log.Fatal(err)
    }
    // Format and print the response to terminal
    prettyJSON, _ := json.MarshalIndent(result, "", "  ")
    fmt.Printf("%s\n", prettyJSON)
}

執行您的 Go 應用程式

將範例程式碼新增至應用程式後，即可在命令或終端機提示字元中執行 Go 程式。請確定提示路徑已設定為 translator-app 資料夾並使用下列命令：

 go run translation.go

翻譯輸出：

呼叫成功後，您應該會看見下列回應：

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

設定您的 Java 環境

應準備好最新的 Visual Studio Code 版本或您慣用的 IDE。請參閱 Visual Studio Code 中的 Java。
提示
- Visual Studio Code 為 Windows 和 macOS 提供 Java 編碼套件。編碼套件是 VS Code、JAVA 開發套件 (JDK) 以及 Microsoft 建議延伸模組的集合。編碼套件也可以用於修正現有的開發環境。
- 如果您使用適用於 JAVA 的 VS Code 和 JAVA 開發套件，請安裝適用於 JAVA 的 Gradle 延伸模組。
如果您未使用 Visual Studio Code，請確保在開發環境中安裝下列項目：
- Java 開發套件 (OpenJDK) 8 版或更新版本。
- Gradle，6.8 版或更新版本。

建立新的 Gradle 專案

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立一個名為 translator-text-app 的新目錄，並瀏覽至該目錄。
```
mkdir translator-text-app && translator-text-app
```
```
 mkdir translator-text-app; cd translator-text-app
```
從 translator-text-app 目錄執行 gradle init 命令。此命令會建立 Gradle 的基本組建檔案，包括 build.gradle.kts，將在執行階段使用 build.gradle.kts，來建立及設定應用程式。
```
gradle init --type basic
```
出現選擇 DSL 的提示時，請選取 [Kotlin]。
請選取 [退回] 或 [輸入] 以接受 translator-text-app 的預設專案名稱。
以下列程式碼來更新 build.gradle.kts：

plugins {
  java
  application
}
application {
  mainClass.set("TranslatorText")
}
repositories {
  mavenCentral()
}
dependencies {
  implementation("com.squareup.okhttp3:okhttp:4.10.0")
  implementation("com.google.code.gson:gson:2.9.0")
}

建立您的 Java 應用程式

從 translator-text-app 目錄執行下列命令：
```
mkdir -p src/main/java
```
您會建立下列目錄結構：
瀏覽至 java 目錄並建立名為 TranslatorText.java 的檔案。
提示
- 您可以使用 PowerShell 建立新檔案。
- 按住 Shift 鍵並在資料夾上以滑鼠右鍵按一下，以開啟專案目錄中的 PowerShell 視窗。
- 鍵入下列命令 New-Item TranslatorText.java。
- 您也可以在 IDE 中建立名為 TranslatorText.java 的新檔案，並將其儲存至 java 目錄。
在您的 IDE 中開啟 TranslatorText.java 檔案，然後將下列程式碼範例複製貼入您的應用程式。 請務必使用 Azure 入口網站翻譯工具執行個體的其中一個索引碼值，來更新索引鍵：

import java.io.IOException;

import com.google.gson.*;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

public class TranslatorText {
    private static String key = "<your-translator-key";

    // location, also known as region.
   // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    private static String location = "<YOUR-RESOURCE-LOCATION>";


    // Instantiates the OkHttpClient.
    OkHttpClient client = new OkHttpClient();

    // This function performs a POST request.
    public String Post() throws IOException {
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType,
                "[{\"Text\": \"I would really like to drive your car around the block a few times!\"}]");
        Request request = new Request.Builder()
                .url("https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=fr&to=zu")
                .post(body)
                .addHeader("Ocp-Apim-Subscription-Key", key)
                // location required if you're using a multi-service or regional (not global) resource.
                .addHeader("Ocp-Apim-Subscription-Region", location)
                .addHeader("Content-type", "application/json")
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
    }

    // This function prettifies the json response.
    public static String prettify(String json_text) {
        JsonParser parser = new JsonParser();
        JsonElement json = parser.parse(json_text);
        Gson gson = new GsonBuilder().setPrettyPrinting().create();
        return gson.toJson(json);
    }

    public static void main(String[] args) {
        try {
            TranslatorText translateRequest = new TranslatorText();
            String response = translateRequest.Post();
            System.out.println(prettify(response));
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

建置和執行您的 Java 應用程式

將範例程式碼新增至應用程式後，請瀏覽回您的主要專案目錄：translator-text-app，開啟主控台視窗並輸入下列命令：

使用 build 命令組建您的應用程式：
```
gradle build
```
使用 run 命令執行您的應用程式：
```
gradle run
```

翻譯輸出：

呼叫成功後，您應該會看見下列回應：

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

設定您的 Node.js Express 專案

確定已安裝最新版本的 Node.js。節點套件管理員 (npm) 包含在 Node.js 安裝程式中。

提示

若您不熟悉 Node.js，可以參考 Node.js 簡介 Learn 課程模組。
在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立名為 translator-app 的新目錄，並瀏覽至該目錄。
```
    mkdir translator-app && cd translator-app
```
```
  mkdir translator-app; cd translator-app
```
執行 npm init 命令來初始化應用程式，並建構您的專案。
```
   npm init
```
使用終端機中顯示的提示來指定專案的屬性。
- 名稱、版本號碼和進入點是最重要的屬性。
- 建議為進入點名稱保留 index.js。描述、測試命令、GitHub 存放庫、關鍵字、作者和授權資訊皆為選擇性屬性，在此專案中可以跳過。
- 選取 [退回] 或 [輸入]，接受括弧中的建議。
- 完成提示後，將會在 translator-app 目錄中建立 package.json 檔案。
請開啟主控台視窗並使用 npm 安裝 axios HTTP 程式庫和 uuid 套件：
```
   npm install axios uuid
```
在應用程式目錄中建立 index.js 檔案。
提示
- 您可以使用 PowerShell 建立新檔案。
- 按住 Shift 鍵並在資料夾上以滑鼠右鍵按一下，以開啟專案目錄中的 PowerShell 視窗。
- 輸入下列命令 New-Item index.js。
- 您也可以在 IDE 中建立名為 index.js 的新檔案，並將其儲存至 translator-app 目錄。

建置您的 JavaScript 應用程式

將下列範例程式碼新增至您的 index.js 檔案。 請務必使用 Azure 入口網站翻譯工具執行個體的值來更新索引鍵變數：

    const axios = require('axios').default;
    const { v4: uuidv4 } = require('uuid');

    let key = "<your-translator-key>";
    let endpoint = "https://api.cognitive.microsofttranslator.com";

    // location, also known as region.
    // required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
    let location = "<YOUR-RESOURCE-LOCATION>";

    axios({
        baseURL: endpoint,
        url: '/translate',
        method: 'post',
        headers: {
            'Ocp-Apim-Subscription-Key': key,
             // location required if you're using a multi-service or regional (not global) resource.
            'Ocp-Apim-Subscription-Region': location,
            'Content-type': 'application/json',
            'X-ClientTraceId': uuidv4().toString()
        },
        params: {
            'api-version': '3.0',
            'from': 'en',
            'to': 'fr,zu'
        },
        data: [{
            'text': 'I would really like to drive your car around the block a few times!'
        }],
        responseType: 'json'
    }).then(function(response){
        console.log(JSON.stringify(response.data, null, 4));
    })

執行您的 JavaScript 應用程式

將範例程式碼新增至應用程式後，請執行應用程式：

請瀏覽至您的應用程式目錄 (translator-app)。
在您的終端機中輸入下列命令：
```
node index.js
```

翻譯輸出：

呼叫成功後，您應該會看見下列回應：

[
    {
        "translations": [
            {
                "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
                "to": "fr"
            },
            {
                "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
                "to": "zu"
            }
        ]
    }
]

設定您的 Python 專案

確定已安裝最新版本的 Python 3.x。 Python 安裝程式套件 (pip) 包含在 Python 安裝程式中。

提示

如果您尚不熟悉 Python，可以參考 Python 簡介 Learn 課程模組。
請開啟終端機視窗並使用 pip 安裝要求程式庫和 uuid0 套件：
```
   pip install requests uuid
```
注意

我們也會使用稱為 json 的 Python 內建封裝，這也會用來處理 JSON 資料。

建置您的 Python 應用程式

在您偏好的編輯器或 IDE 中建立名為 translator-app.py 的新 Python 檔案。
將下列範例程式碼新增至您的 translator-app.py 檔案。 更新索引鍵時，請務必使用來自 Azure 入口網站翻譯工具執行個體其中一個值。

import requests, uuid, json

# Add your key and endpoint
key = "<your-translator-key>"
endpoint = "https://api.cognitive.microsofttranslator.com"

# location, also known as region.
# required if you're using a multi-service or regional (not global) resource. It can be found in the Azure portal on the Keys and Endpoint page.
location = "<YOUR-RESOURCE-LOCATION>"

path = '/translate'
constructed_url = endpoint + path

params = {
    'api-version': '3.0',
    'from': 'en',
    'to': ['fr', 'zu']
}

headers = {
    'Ocp-Apim-Subscription-Key': key,
    # location required if you're using a multi-service or regional (not global) resource.
    'Ocp-Apim-Subscription-Region': location,
    'Content-type': 'application/json',
    'X-ClientTraceId': str(uuid.uuid4())
}

# You can pass more than one object in body.
body = [{
    'text': 'I would really like to drive your car around the block a few times!'
}]

request = requests.post(constructed_url, params=params, headers=headers, json=body)
response = request.json()

print(json.dumps(response, sort_keys=True, ensure_ascii=False, indent=4, separators=(',', ': ')))

執行 Python 應用程式

將程式碼範例新增至應用程式之後，請建置並執行應用程式：

瀏覽至您的 translator-app.py 檔案。
在您的主控台中鍵入下列命令：
```
python translator-app.py
```

翻譯輸出：

呼叫成功後，您應該會看見下列回應：

[
  {
    "translations": [
      {
        "text": "J'aimerais vraiment conduire votre voiture autour du pâté de maisons plusieurs fois!",
        "to": "fr"
      },
      {
        "text": "Ngingathanda ngempela ukushayela imoto yakho endaweni evimbelayo izikhathi ezimbalwa!",
        "to": "zu"
      }
    ]
  }
]

下一步

沒錯，恭喜！您剛剛學會了使用翻譯工具服務來翻譯文字。

探索我們的操作說明文件，並深入探討翻譯服務功能：

快速入門：Azure AI 翻譯工具 REST API

必要條件

標頭

翻譯文字

設定 Visual Studio 專案

使用 NuGet 安裝 Newtonsoft.json 套件

建置您的 C# 應用程式

執行您的 C# 應用程式

下一步

其他資源