クイックスタート: Azure Cognitive Services Translator

このクイックスタートでは、Translator サービスを使用して、選択したプログラミング言語と REST API でテキストを翻訳します。

Note

  • このクイックスタートには、Translator Text の単一サービス グローバル リソースを使用することをお勧めします。
  • 単一サービス グローバル リソースでは、REST API 要求に 1 つの承認ヘッダー (Ocp-Apim-Subscription-key) を含めます。 Ocp-Apim-Subscription-key の値は、Translator Text サブスクリプションの Azure 秘密鍵です。
  • マルチサービスの Cognitive Services またはリージョンの Translator リソースを使用する場合は、2 つの認証ヘッダー (Ocp-Api-Subscription-KeyOcp-Apim-Subscription-Region) が必要です。 Ocp-Apim-Subscription-Region の値は、サブスクリプションに関連付けられているリージョンです。
  • Ocp-Apim-Subscription-Region ヘッダーの使用方法の詳細については、Text Translator REST API ヘッダーに関する記事を参照してください。

前提条件

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

  • Azure サブスクリプションを入手したら、Azure portal で Translator リソースを作成します。

  • リソースがデプロイされたら、[リソースに移動] を選択してキーとエンドポイントを取得します。

    • 自分のアプリケーションを Translator サービスに接続するには、リソースのキーとエンドポイントが必要です。 このクイックスタートで後に示すコードに、自分のキーとエンドポイントを貼り付けます。 これらの値は Azure portal の [キーとエンドポイント] ページで確認できます。

      スクリーンショット: Azure portal の [キーとエンドポイント] ページ。

  • Free 価格レベル (F0) を使ってサービスを試用し、後から運用環境用の有料レベルにアップグレードします。

ヘッダー

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

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

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

重要

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

テキストを翻訳する

Translator サービスの主要な操作は、テキストの翻訳です。 このクイックスタートでは、1 つのソース (from) を受け取り 2 つの出力 (to) を提供する要求を、選択したプログラミング言語を使用して作成します。 次に、要求と応答の両方を調整するために使用できるいくつかのパラメーターを確認します。

Visual Studio プロジェクトをセットアップする

  1. 現在のバージョンの Visual Studio IDE があることを確認します。

    ヒント

    Visual Studio を初めて使う場合は、「Visual Studio の概要」Learn モジュールを試してください。

  2. Visual Studio を開きます。

  3. スタート ページで、[新しいプロジェクトの作成] を選択します。

    スクリーンショット: Visual Studio のスタート ウィンドウ。

  4. [新しいプロジェクトの作成] ページで、検索ボックスに「コンソール」と入力します。 [コンソール アプリケーション] テンプレートを選択し、 [次へ] を選択します。

    スクリーンショット: Visual Studio の [新しいプロジェクトの作成] ページ。

  5. [新しいプロジェクトの構成] ダイアログ ウィンドウの [プロジェクト名] ボックスに「translator_quickstart」と入力します。 [ソリューションとプロジェクトを同じディレクトリに配置する] チェック ボックスをオフのままにして、[次へ] を選択します。

    スクリーンショット: Visual Studio の [新しいプロジェクトの構成] ダイアログ ウィンドウ。

  6. [追加情報] ダイアログ ウィンドウで、[.NET 6.0 (長期的なサポート)] が選択されていることを確認します。 [最上位レベルのステートメントを使用しない] チェック ボックスをオフのままにし、[作成] を選択します。

    スクリーンショット: Visual Studio の [追加情報] ダイアログ ウィンドウ。

NuGet を使用して Newtonsoft.json パッケージをインストールする

  1. translator_quickstart プロジェクトを右クリックし、[NuGet パッケージの管理...] を選択します。

    NuGet パッケージの検索ボックスのスクリーンショット。

  2. [参照] タブを選択し、「Newtonsoft.json」と入力します。

    NuGet パッケージのインストール ウィンドウのスクリーンショット。

  3. 適切なパッケージ マネージャー ウィンドウから [インストール] を選択して、プロジェクトにパッケージを追加します。

    NuGet パッケージのインストール ボタンのスクリーンショット。

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

注意

  • .NET 6 以降では、console テンプレートを使用する新しいプロジェクトによって、以前のバージョンとは異なる新しいプログラム スタイルが生成されます。
  • この新しい出力では、記述する必要があるコードを簡素化できる最新の C# 機能が使用されています。
  • 新しいバージョンで使用する場合、記述する必要があるのは、`Main` メソッドの本体のみです。 最上位レベルのステートメント、グローバル using ディレクティブ、または暗黙的な using ディレクティブを含める必要はありません。
  • 詳細については、「新しい C# テンプレートで、最上位レベルのステートメントが生成される」を "参照" してください。
  1. Program.cs ファイルを開きます。

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

次のステップ

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

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