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

發行項
09/26/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。

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# 應用程式

設定您的 Go 環境

建置您的 Go 應用程式

執行您的 Go 應用程式

設定您的 Java 環境

建立新的 Gradle 專案

建立您的 Java 應用程式

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

設定您的 Node.js Express 專案

建置您的 JavaScript 應用程式

執行您的 JavaScript 應用程式

設定您的 Python 專案

建置您的 Python 應用程式

執行 Python 應用程式

下一步

意見反應

其他資源