クイックスタート: Azure AI 翻訳 REST API

[アーティクル]
09/26/2024

最新バージョンの Azure AI 翻訳をお試しください。このクイックスタートでは、Translator サービスを使用して、選択したプログラミング言語または REST API でテキストを翻訳します。このプロジェクトでは、テクノロジを学習している間は無料価格レベル (F0) を使用し、後で運用環境向けの有料レベルにアップグレードすることをお勧めします。

前提条件

アクティブな Azure サブスクリプションが必要です。 Azure サブスクリプションがない場合は、無料で作成することができます。

Azure サブスクリプションを入手したら、Azure portal で Translator リソースを作成します。
リソースがデプロイされたら、[リソースに移動] を選択してキーとエンドポイントを取得します。
- 自分のアプリケーションを Translator サービスに接続するには、リソースのキーとエンドポイントが必要です。このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。これらの値は Azure portal の [キーとエンドポイント] ページで確認できます。
  Note
  - このクイックスタートには、Translator Text の単一サービスグローバルリソースを使用することをお勧めします。
  - 単一サービスグローバルリソースでは、REST API 要求に 1 つの承認ヘッダー (Ocp-Apim-Subscription-key) を含めます。 Ocp-Apim-Subscription-key の値は、Translator Text サブスクリプションの Azure 秘密鍵です。
  - Azure AI マルチサービスまたはリージョン Translator リソースを使用する場合は、2 つの認証ヘッダー (Ocp-Api-Subscription-Key と Ocp-Apim-Subscription-Region) が必要です。 Ocp-Apim-Subscription-Region の値は、サブスクリプションに関連付けられているリージョンです。
  - Ocp-Apim-Subscription-Region ヘッダーの使用方法の詳細については、「Text Translation REST API ヘッダー」を参照してください。

ヘッダー

REST API を介して Translator サービスを呼び出すには、各要求に次のヘッダーを含める必要があります。各プログラミング言語のサンプルコードへのヘッダーの挿入は Microsoft が行うため、心配ありません。

Translator 認証オプションの詳細については、Translator v3 リファレンス ガイドを参照してください。

ヘッダー	値	条件
Ocp-Apim-Subscription-Key	Azure portal からの Translator サービスキー。	• 必須
Ocp-Apim-Subscription-Region	リソースが作成されたリージョン。	• Azure AI マルチサービスまたはリージョン (地理的) リソース (米国西部など) を使用する場合は必須です。 • 単一サービスのグローバル Translator リソースを使用する場合は省略可能です。
Content-Type	ペイロードのコンテンツタイプ。許容される値は application/json または charset=UTF-8 です。	• 必須
Content-Length	要求本文の長さ。	• "省略可能"

重要

終わったらコードからキーを削除し、公開しないよう注意してください。運用環境では、Azure Key Vault などの資格情報を格納してアクセスする安全な方法を使用します。詳しくは、Azure AI サービスのセキュリティに関する記事を参照してください。

テキストを翻訳する

Translator サービスの主要な操作は、テキストの翻訳です。このクイックスタートでは、1 つのソース (from) を受け取り 2 つの出力 (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 portal の Translator インスタンスの値で更新するようにしてください。

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 portal の Translator インスタンスの値で更新するようにしてください。

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 Development Kit (JDK)、および Microsoft が推奨する拡張機能のコレクションのバンドルです。コーディングパックを使用して、既存の開発環境を修正できます。
- VS Code と Java 用のコーディングパックを使用している場合は、Java 用 Gradle 拡張機能をインストールします。
Visual Studio Code を使用していない場合、開発環境に次のものがインストールされていることを確認してください。
- Java Development Kit (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 などです。
```
gradle init --type basic
```
DSL を選択するよう求められたら、Kotlin を選択します。
Return または Enter キーを選択して、既定のプロジェクト名 (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 portal の Translator インスタンスからのいずれかのキー値で更新してください。

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 がインストールされていることを確認します。 Node.js のインストールには、ノードパッケージマネージャー (npm) が含まれます。

ヒント

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 リポジトリ、キーワード、作成者、ライセンス情報はオプションの属性であり、このプロジェクトでは省略可能です。
- [戻る] または Enter キーを押して、かっこで囲んだ候補を受け入れます。
- 画面の指示に従って入力すると、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 portal の Translator インスタンスからの値で更新してください。

    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 のインストールには、Python インストーラーパッケージ (pip) が含まれます。

ヒント

Python を初めて使う場合は、「Python の概要」Learn モジュールを試してください。
ターミナルウィンドウを開き、pip を使用して Requests ライブラリと uuid0 パッケージをインストールします。
```
   pip install requests uuid
```
Note

json という名前の Python 組み込みパッケージも使用します。これは JSON データの操作に使用されます。

Python アプリケーションをビルドする

任意のエディターまたは IDE で、translator-app.py という名前の新しい Python ファイルを作成します。
次のコードサンプルを translator-app.py ファイルに追加します。 キーは、Azure portal の Translator インスタンスからのいずれかの値で更新してください。

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

次のステップ

以上です。お疲れさまでした。ここでは、Translator サービスを使ってテキストを翻訳する方法を学習しました。

Microsoft のハウツードキュメントを確認し、翻訳サービスの機能について詳しく調べます。

次の方法で共有

クイックスタート: 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 アプリケーションを実行する

次のステップ

フィードバック

その他のリソース