クイック スタート:Translator Text API を使用してテキストを翻訳するQuickstart: Use the Translator Text API to translate text

このクイックスタートでは、Translator Text REST API を使用して、テキスト文字列を英語からドイツ語、イタリア語、日本語、およびタイ語に変換する方法について説明します。In this quickstart, you'll learn how to translate a text string from English to German, Italian, Japanese, and Thai using the Translator Text REST API.

このクイック スタートでは、Azure Cognitive Services アカウントと Translator Text リソースが必要になります。This quickstart requires an Azure Cognitive Services account with a Translator Text resource. アカウントを持っていない場合は、無料試用版を使用してサブスクリプション キーを取得できます。If you don't have an account, you can use the free trial to get a subscription key.

前提条件Prerequisites

このクイック スタートでは以下が必要です。This quickstart requires:

セットアップSet up

Translator Text リソースを作成するCreate a Translator Text resource

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用して、ローカル コンピューター上に Translator Text のリソースを作成します。Create a resource for Translator Text using the Azure portal or Azure CLI on your local machine. さらに、以下を実行できます。You can also:

  • 7 日間有効な試用版のキーを無料で入手する。Get a trial key valid for 7 days for free. これは、サインアップ後に Azure Web サイトで入手できます。After signing up, it will be available on the Azure website.
  • Azure portal で既存のリソースを表示する。View an existing resource in the Azure portal.

試用版のサブスクリプションまたはリソースからキーを取得した後、環境変数を 2 つ作成します。After you get a key from your trial subscription or resource, create two environment variables:

  • TRANSLATOR_TEXT_SUBSCRIPTION_KEY - Translator Text リソースのサブスクリプション キー。TRANSLATOR_TEXT_SUBSCRIPTION_KEY - The subscription key for your Translator Text resource.
  • TRANSLATOR_TEXT_ENDPOINT - Translator Text のグローバル エンドポイント。TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. https://api.cognitive.microsofttranslator.com/を使用します。Use https://api.cognitive.microsofttranslator.com/.

.NET Core プロジェクトを作成するCreate a .NET Core project

新しいコマンド プロンプト (またはターミナル セッション) を開き、次のコマンドを実行します。Open a new command prompt (or terminal session) and run these commands:

dotnet new console -o translate-sample
cd translate-sample

最初のコマンドでは、2 つのことを行っています。The first command does two things. 新しい .NET コンソール アプリケーションを作成し、translate-sample という名前のディレクトリを作成します。It creates a new .NET console application, and creates a directory named translate-sample. 2 つ目のコマンドでは、目的のプロジェクトのディレクトリに変更しています。The second command changes to the directory for your project.

次に、Json.Net をインストールする必要があります。Next, you'll need to install Json.Net. プロジェクトのディレクトリから、次を実行します。From your project's directory, run:

dotnet add package Newtonsoft.Json --version 11.0.2

C# 言語のバージョンを選択するSelect the C# language version

このクイック スタートでは、C# 7.1 以降が必要です。This quickstart requires C# 7.1 or later. プロジェクトに使用する C# のバージョンは、いくつかの方法で変更できます。There are a few ways to change the C# version for your project. このガイドでは、translate-sample.csproj ファイルを調整する方法について説明します。In this guide, we'll show you how to adjust the translate-sample.csproj file. Visual Studio で言語を変更するなど、選択可能なすべての方法については、「C# 言語のバージョンの選択」を参照してください。For all available options, such as changing the language in Visual Studio, see Select the C# language version.

対象のプロジェクトを開いて、translate-sample.csproj を開きます。Open your project, then open translate-sample.csproj. LangVersion は必ず 7.1 以降に設定してください。Make sure that LangVersion is set to 7.1 or later. 該当する言語バージョンのプロパティ グループが存在しない場合は、次の行を追加します。If there isn't a property group for the language version, add these lines:

<PropertyGroup>
   <LangVersion>7.1</LangVersion>
</PropertyGroup>

必要な名前空間をプロジェクトに追加するAdd required namespaces to your project

先ほど実行した dotnet new console コマンドによって、プロジェクトが作成されています。これには Program.cs が含まれています。The dotnet new console command that you ran earlier created a project, including Program.cs. このファイルに、アプリケーション コードを記述することになります。This file is where you'll put your application code. Program.cs を開いて、既存の using ステートメントを置き換えます。Open Program.cs, and replace the existing using statements. これらのステートメントによって、サンプル アプリのビルドと実行に必要なすべての型に確実にアクセスすることができます。These statements ensure that you have access to all the types required to build and run the sample app.

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
// Install Newtonsoft.Json with NuGet
using Newtonsoft.Json;

JSON 応答用のクラスを作成するCreate classes for the JSON response

次は、Translator Text API から返された JSON 応答を逆シリアル化するときに使用される一連のクラスを作成します。Next, we're going to create a set of classes that are used when deserializing the JSON response returned by the Translator Text API.

/// <summary>
/// The C# classes that represents the JSON returned by the Translator Text API.
/// </summary>
public class TranslationResult
{
    public DetectedLanguage DetectedLanguage { get; set; }
    public TextResult SourceText { get; set; }
    public Translation[] Translations { get; set; }
}

public class DetectedLanguage
{
    public string Language { get; set; }
    public float Score { get; set; }
}

public class TextResult
{
    public string Text { get; set; }
    public string Script { get; set; }
}

public class Translation
{
    public string Text { get; set; }
    public TextResult Transliteration { get; set; }
    public string To { get; set; }
    public Alignment Alignment { get; set; }
    public SentenceLength SentLen { get; set; }
}

public class Alignment
{
    public string Proj { get; set; }
}

public class SentenceLength
{
    public int[] SrcSentLen { get; set; }
    public int[] TransSentLen { get; set; }
}

環境変数からサブスクリプション情報を取得するGet subscription information from environment variables

以下の行を Program クラスに追加します。Add the following lines to the Program class. これらの行で、環境変数からサブスクリプション キーとエンドポイントを読み取り、問題が発生した場合はエラーをスローします。These lines read your subscription key and endpoint from environment variables, and throws an error if you run into any issues.

private const string key_var = "TRANSLATOR_TEXT_SUBSCRIPTION_KEY";
private static readonly string subscriptionKey = Environment.GetEnvironmentVariable(key_var);

private const string endpoint_var = "TRANSLATOR_TEXT_ENDPOINT";
private static readonly string endpoint = Environment.GetEnvironmentVariable(endpoint_var);

static Program()
{
    if (null == subscriptionKey)
    {
        throw new Exception("Please set/export the environment variable: " + key_var);
    }
    if (null == endpoint)
    {
        throw new Exception("Please set/export the environment variable: " + endpoint_var);
    }
}
// The code in the next section goes here.

テキストを翻訳するための関数を作成するCreate a function to translate text

Program クラスに、TranslateTextRequest() という非同期関数を作成します。In the Program class, create an asynchronous function called TranslateTextRequest(). この関数は、subscriptionKeyhostroute、および inputText という 4 つの引数を受け取ります。This function takes four arguments: subscriptionKey, host, route, and inputText.

// This sample requires C# 7.1 or later for async/await.
// Async call to the Translator Text API
static public async Task TranslateTextRequest(string subscriptionKey, string endpoint, string route, string inputText)
{
  /*
   * The code for your call to the translation service will be added to this
   * function in the next few sections.
   */
}

変換要求をシリアル化するSerialize the translation request

次に、翻訳対象のテキストを含む JSON オブジェクトを作成してシリアル化する必要があります。Next, we need to create and serialize the JSON object that includes the text you want to translate. body には複数のオブジェクトを渡すことができる点に注目してください。Keep in mind, you can pass more than one object in the body.

object[] body = new object[] { new { Text = inputText } };
var requestBody = JsonConvert.SerializeObject(body);

クライアントをインスタンス化して要求を行うInstantiate the client and make a request

次の行によって HttpClientHttpRequestMessage がインスタンス化されます。These lines instantiate the HttpClient and the HttpRequestMessage:

using (var client = new HttpClient())
using (var request = new HttpRequestMessage())
{
  // In the next few sections you'll add code to construct the request.
}

要求を構成して応答を出力するConstruct the request and print the response

HttpRequestMessage 内で次のことを行います。Inside the HttpRequestMessage you'll:

  • HTTP メソッドを宣言するDeclare the HTTP method
  • 要求 URI を構成するConstruct the request URI
  • 要求本文 (シリアル化した JSON オブジェクト) を挿入するInsert the request body (serialized JSON object)
  • 必要なヘッダーを追加するAdd required headers
  • 非同期要求を実行するMake an asynchronous request
  • 以前に作成したクラスを使用して応答を出力するPrint the response using the classes you created earlier

次のコードを HttpRequestMessage に追加します。Add this code to the HttpRequestMessage:

// Build the request.
// Set the method to Post.
request.Method = HttpMethod.Post;
// Construct the URI and add headers.
request.RequestUri = new Uri(endpoint + route);
request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json");
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

// 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();
// Deserialize the response using the classes created earlier.
TranslationResult[] deserializedOutput = JsonConvert.DeserializeObject<TranslationResult[]>(result);
// Iterate over the deserialized results.
foreach (TranslationResult o in deserializedOutput)
{
    // Print the detected input language and confidence score.
    Console.WriteLine("Detected input language: {0}\nConfidence score: {1}\n", o.DetectedLanguage.Language, o.DetectedLanguage.Score);
    // Iterate over the results and print each translation.
    foreach (Translation t in o.Translations)
    {
        Console.WriteLine("Translated to {0}: {1}", t.To, t.Text);
    }
}

Cognitive Services のマルチサービス サブスクリプションを使用している場合は、要求のパラメーターに Ocp-Apim-Subscription-Region も含める必要があります。If you are using a Cognitive Services multi-service subscription, you must also include the Ocp-Apim-Subscription-Region in your request parameters. マルチサービス サブスクリプションを使用した認証の詳細を参照してくださいLearn more about authenticating with the multi-service subscription.

すべてをまとめた配置Put it all together

最後の手順は、Main 関数での TranslateTextRequest() の呼び出しです。The last step is to call TranslateTextRequest() in the Main function. このサンプルでは、ドイツ語 (de)、イタリア語 (it)、日本語 (ja)、およびタイ語 (th) に翻訳しています。In this sample, we're translating to German (de), Italian (it), Japanese (ja), and Thai (th). static void Main(string[] args) を探してこのコードに置き換えます。Locate static void Main(string[] args) and replace it with this code:

static async Task Main(string[] args)
{
    // This is our main function.
    // Output languages are defined in the route.
    // For a complete list of options, see API reference.
    // https://docs.microsoft.com/azure/cognitive-services/translator/reference/v3-0-translate
    string route = "/translate?api-version=3.0&to=de&to=it&to=ja&to=th";
    // Prompts you for text to translate. If you'd prefer, you can
    // provide a string as textToTranslate.
    Console.Write("Type the phrase you'd like to translate? ");
    string textToTranslate = Console.ReadLine();
    await TranslateTextRequest(subscriptionKey, endpoint, route, textToTranslate);
    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
}

Main では、subscriptionKeyendpoint、および route を宣言されていることがわかります。You'll notice that in Main, you're declaring subscriptionKey, endpoint, and route. さらに、Console.Readline() を使用してユーザーに入力を求め、その値を textToTranslate に割り当てています。Additionally, you're prompting the user for input with Console.Readline() and assigning the value to textToTranslate.

サンプル アプリを実行するRun the sample app

以上で、サンプル アプリを実行する準備が整いました。That's it, you're ready to run your sample app. コマンド ライン (またはターミナル セッション) から、プロジェクト ディレクトリに移動して次のコマンドを実行します。From the command line (or terminal session), navigate to your project directory and run:

dotnet run

応答のサンプルSample response

サンプルを実行すると、次のようにターミナルに出力されます。After you run the sample, you should see the following printed to terminal:

Detected input language: en
Confidence score: 1

Translated to de: Hallo Welt!
Translated to it: Salve, mondo!
Translated to ja: ハローワールド!
Translated to th: หวัดดีชาวโลก!

このメッセージは、次のように生の JSON からビルドされます。This message is built from the raw JSON, which will look like this:

[
  {
    "detectedLanguage": {
      "language": "en",
      "score": 1.0
    },
    "translations": [
      {
        "text": "Hallo Welt!",
        "to": "de"
      },
      {
        "text": "Salve, mondo!",
        "to": "it"
      },
      {
        "text": "ハローワールド!",
        "to": "ja"
      },
      {
        "text": "หวัดดีชาวโลก!",
        "to": "th"
      }
    ]
  }
]

リソースのクリーンアップClean up resources

サブスクリプション キーなどの秘密情報は、サンプル アプリのソース コードからすべて確実に削除してください。Make sure to remove any confidential information from your sample app's source code, like subscription keys.

次の手順Next steps

API のリファレンスを見て、Translator Text API でできるすべてのことを理解してください。Take a look at the API reference to understand everything you can do with the Translator Text API.

前提条件Prerequisites

このクイック スタートでは以下が必要です。This quickstart requires:

セットアップSet up

Translator Text リソースを作成するCreate a Translator Text resource

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用して、ローカル コンピューター上に Translator Text のリソースを作成します。Create a resource for Translator Text using the Azure portal or Azure CLI on your local machine. さらに、以下を実行できます。You can also:

  • 7 日間有効な試用版のキーを無料で入手する。Get a trial key valid for 7 days for free. これは、サインアップ後に Azure Web サイトで入手できます。After signing up, it will be available on the Azure website.
  • Azure portal で既存のリソースを表示する。View an existing resource in the Azure portal.

試用版のサブスクリプションまたはリソースからキーを取得した後、環境変数を 2 つ作成します。After you get a key from your trial subscription or resource, create two environment variables:

  • TRANSLATOR_TEXT_SUBSCRIPTION_KEY - Translator Text リソースのサブスクリプション キー。TRANSLATOR_TEXT_SUBSCRIPTION_KEY - The subscription key for your Translator Text resource.
  • TRANSLATOR_TEXT_ENDPOINT - Translator Text のグローバル エンドポイント。TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. https://api.cognitive.microsofttranslator.com/を使用します。Use https://api.cognitive.microsofttranslator.com/.

Gradle を使用してプロジェクトを初期化するInitialize a project with Gradle

まずは、このプロジェクトの作業ディレクトリを作成しましょう。Let's start by creating a working directory for this project. コマンド ライン (またはターミナル) から、次のコマンドを実行します。From the command line (or terminal), run this command:

mkdir translator-sample
cd translator-sample

次に、Gradle プロジェクトを初期化します。Next, you're going to initialize a Gradle project. 次のコマンドを実行すると、Gradle の重要なビルド ファイルが作成されます。特に重要なのは build.gradle.kts です。これは、アプリケーションを作成して構成するために、実行時に使用されます。This command will create essential build files for Gradle, most importantly, the build.gradle.kts, which is used at runtime to create and configure your application. 作業ディレクトリから次のコマンドを実行します。Run this command from your working directory:

gradle init --type basic

DSL を選択するよう求められたら、Kotlin を選択します。When prompted to choose a DSL, select Kotlin.

ビルド ファイルを構成するConfigure the build file

build.gradle.kts の場所を特定し、好みの IDE またはテキスト エディターで開きます。Locate build.gradle.kts and open it with your favorite IDE or text editor. その後、次のビルド構成をコピーします。Then copy in this build configuration:

plugins {
    java
    application
}
application {
    mainClassName = "Translate"
}
repositories {
    mavenCentral()
}
dependencies {
    compile("com.squareup.okhttp:okhttp:2.5.0")
    compile("com.google.code.gson:gson:2.8.5")
}

このサンプルでは、HTTP 要求の処理に OkHttp を使用し、JSON の処理と解析に Gson を使用していることに注意してください。Take note that this sample has dependencies on OkHttp for HTTP requests, and Gson to handle and parse JSON. ビルド構成について詳しくは、「Creating New Gradle Builds」(新しい Gradle ビルドの作成) をご覧ください。If you'd like to learn more about build configurations, see Creating New Gradle Builds.

Java ファイルを作成するCreate a Java file

サンプル アプリ用のフォルダーを作成しましょう。Let's create a folder for your sample app. 作業ディレクトリから、次のコマンドを実行します。From your working directory, run:

mkdir -p src/main/java

次に、このフォルダー内に Translate.java というファイルを作成します。Next, in this folder, create a file named Translate.java.

必要なライブラリをインポートするImport required libraries

Translate.java を開き、次のインポート ステートメントを追加します。Open Translate.java and add these import statements:

import java.io.*;
import java.net.*;
import java.util.*;
import com.google.gson.*;
import com.squareup.okhttp.*;

変数の定義Define variables

まず、プロジェクトのパブリック クラスを作成する必要があります。First, you'll need to create a public class for your project:

public class Translate {
  // All project code goes here...
}

次の行を Translate クラスに追加します。Add these lines to the Translate class. まず、サブスクリプション キーとエンドポイントが環境変数から読み取られます。First, the subscription key and endpoint are being read from environment variables. url には、api-version と共に別途 2 つのパラメーターが追加されていることがわかります。Then, you'll notice that along with the api-version, two additional parameters have been appended to the url. 翻訳の出力は、これらのパラメーターを使用して設定します。These parameters are used to set the translation outputs. このサンプルでは、ドイツ語 (de) とイタリア語 (it) に設定しています。In this sample, it's set to German (de) and Italian (it).

private static String subscriptionKey = System.getenv("TRANSLATOR_TEXT_SUBSCRIPTION_KEY");
private static String endpoint = System.getenv("TRANSLATOR_TEXT_ENDPOINT");
String url = endpoint + "/translate?api-version=3.0&to=de,it";

Cognitive Services のマルチサービス サブスクリプションを使用している場合は、要求のパラメーターに Ocp-Apim-Subscription-Region も含める必要があります。If you are using a Cognitive Services multi-service subscription, you must also include the Ocp-Apim-Subscription-Region in your request parameters. マルチサービス サブスクリプションを使用した認証の詳細を参照してくださいLearn more about authenticating with the multi-service subscription.

クライアントを作成して要求をビルドするCreate a client and build a request

次の行を Translate クラスに追加して、OkHttpClient をインスタンス化します。Add this line to the Translate class to instantiate the OkHttpClient:

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

次に、POST 要求をビルドしましょう。Next, let's build the POST request. 翻訳するテキストは変更してかまいません。Feel free to change the text for translation. テキストはエスケープする必要があります。The text must be escaped.

// This function performs a POST request.
public String Post() throws IOException {
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType,
            "[{\n\t\"Text\": \"Welcome to Microsoft Translator. Guess how many languages I speak!\"\n}]");
    Request request = new Request.Builder()
            .url(url).post(body)
            .addHeader("Ocp-Apim-Subscription-Key", subscriptionKey)
            .addHeader("Content-type", "application/json").build();
    Response response = client.newCall(request).execute();
    return response.body().string();
}

応答を解析するための関数を作成するCreate a function to parse the response

このシンプルな関数は、Translator Text サービスからの JSON 応答を解析し、整形するものです。This simple function parses and prettifies the JSON response from the Translator Text service.

// 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);
}

すべてをまとめた配置Put it all together

最後に、要求を実行して応答を取得します。The last step is to make a request and get a response. 次の行をプロジェクトに追加します。Add these lines to your project:

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

サンプル アプリを実行するRun the sample app

以上で、サンプル アプリを実行する準備が整いました。That's it, you're ready to run your sample app. コマンド ライン (またはターミナル セッション) で作業ディレクトリのルートに移動して、次のコマンドを実行します。From the command line (or terminal session), navigate to the root of your working directory and run:

gradle build

ビルドが完了したら、次のコマンドを実行します。When the build completes, run:

gradle run

応答のサンプルSample response

[
  {
    "detectedLanguage": {
      "language": "en",
      "score": 1.0
    },
    "translations": [
      {
        "text": "Willkommen bei Microsoft Translator. Erraten Sie, wie viele Sprachen ich spreche!",
        "to": "de"
      },
      {
        "text": "Benvenuti a Microsoft Translator. Indovinate quante lingue parlo!",
        "to": "it"
      }
    ]
  }
]

次の手順Next steps

API のリファレンスを見て、Translator Text API でできるすべてのことを理解してください。Take a look at the API reference to understand everything you can do with the Translator Text API.

前提条件Prerequisites

このクイック スタートでは以下が必要です。This quickstart requires:

セットアップSet up

Translator Text リソースを作成するCreate a Translator Text resource

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用して、ローカル コンピューター上に Translator Text のリソースを作成します。Create a resource for Translator Text using the Azure portal or Azure CLI on your local machine. さらに、以下を実行できます。You can also:

  • 7 日間有効な試用版のキーを無料で入手する。Get a trial key valid for 7 days for free. これは、サインアップ後に Azure Web サイトで入手できます。After signing up, it will be available on the Azure website.
  • Azure portal で既存のリソースを表示する。View an existing resource in the Azure portal.

試用版のサブスクリプションまたはリソースからキーを取得した後、環境変数を 2 つ作成します。After you get a key from your trial subscription or resource, create two environment variables:

  • TRANSLATOR_TEXT_SUBSCRIPTION_KEY - Translator Text リソースのサブスクリプション キー。TRANSLATOR_TEXT_SUBSCRIPTION_KEY - The subscription key for your Translator Text resource.
  • TRANSLATOR_TEXT_ENDPOINT - Translator Text のグローバル エンドポイント。TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. https://api.cognitive.microsofttranslator.com/を使用します。Use https://api.cognitive.microsofttranslator.com/.

プロジェクトの作成と必要なモジュールのインポートCreate a project and import required modules

普段使用している IDE またはエディターで、新しい Python プロジェクトを作成します。Create a new Python project using your favorite IDE or editor. 次に、このコード スニペットをプロジェクトの translate-text.py という名前のファイルにコピーします。Then copy this code snippet into your project in a file named translate-text.py. ライブラリが認識されるように、IDE のインタープリターが正しいバージョンの Python を参照していることを確認してください。Be sure your IDE's interpreter references the correct version of Python to avoid libraries not being recognized.

# -*- coding: utf-8 -*-
import os, requests, uuid, json

注意

これらのモジュールを使用していない場合は、プログラムを実行する前にこれらをインストールする必要があります。If you haven't used these modules you'll need to install them before running your program. これらのパッケージをインストールするには、pip install requests uuid を実行します。To install these packages, run: pip install requests uuid.

最初のコメントでは、UTF-8 エンコードを使用するように Python インタープリターに指示しています。The first comment tells your Python interpreter to use UTF-8 encoding. 次に、必要なモジュールをインポートして、環境変数からのサブスクリプション キーの読み取り、HTTP 要求の作成、一意識別子の作成、Translator Text API から返された JSON 応答の処理を行っています。Then required modules are imported to read your subscription key from an environment variable, construct the http request, create a unique identifier, and handle the JSON response returned by the Translator Text API.

サブスクリプション キー、エンドポイント、パスの設定Set the subscription key, endpoint, and path

このサンプルでは、Translator Text のサブスクリプション キーとエンドポイントを環境変数 TRANSLATOR_TEXT_KEY および TRANSLATOR_TEXT_ENDPOINT から読み取ることを試みます。This sample will try to read your Translator Text subscription key and endpoint from the environment variables: TRANSLATOR_TEXT_KEY and TRANSLATOR_TEXT_ENDPOINT. 環境変数を使い慣れていない場合は、subscription_key および endpoint を文字列として設定し、条件ステートメントをコメント アウトすることができます。If you're not familiar with environment variables, you can set subscription_key and endpoint as a strings and comment out the conditional statements.

このコードをプロジェクトにコピーします。Copy this code into your project:

key_var_name = 'TRANSLATOR_TEXT_SUBSCRIPTION_KEY'
if not key_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(key_var_name))
subscription_key = os.environ[key_var_name]

endpoint_var_name = 'TRANSLATOR_TEXT_ENDPOINT'
if not endpoint_var_name in os.environ:
    raise Exception('Please set/export the environment variable: {}'.format(endpoint_var_name))
endpoint = os.environ[endpoint_var_name]

Translator Text のグローバル エンドポイントは、endpoint として設定されます。The Translator Text global endpoint is set as the endpoint. path によって、translate ルートが設定され、API のバージョン 3 を使用することが識別されます。path sets the translate route and identifies that we want to hit version 3 of the API.

params は、出力言語を設定するために使用されます。The params are used to set the output languages. このサンプルでは、英語からイタリア語とドイツ語 (itde) に翻訳しています。In this sample we're translating from English to Italian and German: it and de.

注意

エンドポイント、ルート、および要求パラメーターの詳細については、「Translator Text API 3.0: Translate」をご覧ください。For more information about endpoints, routes, and request parameters, see Translator Text API 3.0: Translate.

path = '/translate?api-version=3.0'
params = '&to=de&to=it'
constructed_url = endpoint + path + params

ヘッダーの追加Add headers

要求を認証する最も簡単な方法は、このサンプルで使用している Ocp-Apim-Subscription-Key ヘッダーとしてサブスクリプション キーを渡すことです。The easiest way to authenticate a request is to pass in your subscription key as an Ocp-Apim-Subscription-Key header, which is what we use in this sample. または、アクセス トークンのサブスクリプション キーを交換し、アクセス トークンを一緒に Authorization ヘッダーとして渡して要求を検証することもできます。As an alternative, you can exchange your subscription key for an access token, and pass the access token along as an Authorization header to validate your request. 詳細については、認証に関するページをご覧ください。For more information, see Authentication.

このコード スニペットをプロジェクトにコピーします。Copy this code snippet into your project:

headers = {
    'Ocp-Apim-Subscription-Key': subscription_key,
    'Content-type': 'application/json',
    'X-ClientTraceId': str(uuid.uuid4())
}

Cognitive Services のマルチサービス サブスクリプションを使用している場合は、要求のパラメーターに Ocp-Apim-Subscription-Region も含める必要があります。If you are using a Cognitive Services multi-service subscription, you must also include the Ocp-Apim-Subscription-Region in your request parameters. マルチサービス サブスクリプションを使用した認証の詳細を参照してくださいLearn more about authenticating with the multi-service subscription.

テキストを翻訳する要求の作成Create a request to translate text

翻訳したい 1 つまたは複数の文字列を定義します。Define the string (or strings) that you want to translate:

body = [{
    'text': 'Hello World!'
}]

次に、requests モジュールを使用して POST 要求を作成します。Next, we'll create a POST request using the requests module. これは、連結された URL、要求ヘッダー、および要求本文の 3 つの引数を受け取ります。It takes three arguments: the concatenated URL, the request headers, and the request body:

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

最後の手順では、結果を出力します。The last step is to print the results. このコード スニペットでは、キーを並べ替え、インデントを設定し、項目とキーの区切りを宣言することによって、結果を整形します。This code snippet prettifies the results by sorting the keys, setting indentation, and declaring item and key separators.

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

すべてをまとめた配置Put it all together

これで、Translator Text API を呼び出して JSON 応答を返す簡単なプログラムが完成しました。That's it, you've put together a simple program that will call the Translator Text API and return a JSON response. ここで、プログラムを実行してみましょう。Now it's time to run your program:

python translate-text.py

作成したコードをサンプル コードと比較したい場合は、完全なサンプルを GitHub から入手できます。If you'd like to compare your code against ours, the complete sample is available on GitHub.

応答のサンプルSample response

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "Hallo Welt!",
                "to": "de"
            },
            {
                "text": "Salve, mondo!",
                "to": "it"
            }
        ]
    }
]

リソースのクリーンアップClean up resources

サブスクリプション キーをプログラムにハードコーディングしている場合は、このクイック スタートを終了するときにサブスクリプション キーを必ず削除してください。If you've hardcoded your subscription key into your program, make sure to remove the subscription key when you're finished with this quickstart.

次の手順Next steps

API のリファレンスを見て、Translator Text API でできるすべてのことを理解してください。Take a look at the API reference to understand everything you can do with the Translator Text API.

前提条件Prerequisites

このクイック スタートでは以下が必要です。This quickstart requires:

セットアップSet up

Translator Text リソースを作成するCreate a Translator Text resource

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用して、ローカル コンピューター上に Translator Text のリソースを作成します。Create a resource for Translator Text using the Azure portal or Azure CLI on your local machine. さらに、以下を実行できます。You can also:

  • 7 日間有効な試用版のキーを無料で入手する。Get a trial key valid for 7 days for free. これは、サインアップ後に Azure Web サイトで入手できます。After signing up, it will be available on the Azure website.
  • Azure portal で既存のリソースを表示する。View an existing resource in the Azure portal.

試用版のサブスクリプションまたはリソースからキーを取得した後、環境変数を 2 つ作成します。After you get a key from your trial subscription or resource, create two environment variables:

  • TRANSLATOR_TEXT_SUBSCRIPTION_KEY - Translator Text リソースのサブスクリプション キー。TRANSLATOR_TEXT_SUBSCRIPTION_KEY - The subscription key for your Translator Text resource.
  • TRANSLATOR_TEXT_ENDPOINT - Translator Text のグローバル エンドポイント。TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. https://api.cognitive.microsofttranslator.com/を使用します。Use https://api.cognitive.microsofttranslator.com/.

プロジェクトの作成と必要なモジュールのインポートCreate a project and import required modules

任意の IDE またはエディターを使用して新しいプロジェクトを作成するか、translate-text.js という名前のファイルが含まれる新しいフォルダーをデスクトップ上に作成します。Create a new project using your favorite IDE or editor, or a new folder with a file named translate-text.js on your desktop. 次に、このコード スニペットをプロジェクト/ファイル内にコピーします。Then copy this code snippet into your project/file:

const request = require('request');
const uuidv4 = require('uuid/v4');

注意

これらのモジュールを使用していない場合は、プログラムを実行する前にこれらをインストールする必要があります。If you haven't used these modules you'll need to install them before running your program. これらのパッケージをインストールするには、npm install request uuidv4 を実行します。To install these packages, run: npm install request uuidv4.

これらのモジュールは、HTTP 要求を作成したり、'X-ClientTraceId' ヘッダーの一意識別子を作成したりする際に必要となります。These modules are required to construct the HTTP request, and create a unique identifier for the 'X-ClientTraceId' header.

サブスクリプション キーとエンドポイントの設定Set the subscription key and endpoint

このサンプルは、Translator Text のサブスクリプション キーとエンドポイントを環境変数 TRANSLATOR_TEXT_SUBSCRIPTION_KEY および TRANSLATOR_TEXT_ENDPOINT から読み取ることを試みます。This sample will try to read your Translator Text subscription key and endpoint from these environment variables: TRANSLATOR_TEXT_SUBSCRIPTION_KEY and TRANSLATOR_TEXT_ENDPOINT. 環境変数を使い慣れていない場合は、subscriptionKeyendpoint を文字列として設定し、条件ステートメントをコメント アウトすることができます。If you're not familiar with environment variables, you can set subscriptionKey and endpoint as strings and comment out the conditional statements.

このコードをプロジェクトにコピーします。Copy this code into your project:

var key_var = 'TRANSLATOR_TEXT_SUBSCRIPTION_KEY';
if (!process.env[key_var]) {
    throw new Error('Please set/export the following environment variable: ' + key_var);
}
var subscriptionKey = process.env[key_var];
var endpoint_var = 'TRANSLATOR_TEXT_ENDPOINT';
if (!process.env[endpoint_var]) {
    throw new Error('Please set/export the following environment variable: ' + endpoint_var);
}
var endpoint = process.env[endpoint_var];

要求の構成Configure the request

要求モジュールに用意されている request() メソッドには、HTTP メソッド、URL、要求パラメーター、ヘッダー、JSON 本文を options オブジェクトとして渡すことができます。The request() method, made available through the request module, allows us to pass the HTTP method, URL, request params, headers, and the JSON body as an options object. このコード スニペットで、実際の要求を構成してみましょう。In this code snippet, we'll configure the request:

注意

エンドポイント、ルート、および要求パラメーターの詳細については、「Translator Text API 3.0: Translate」をご覧ください。For more information about endpoints, routes, and request parameters, see Translator Text API 3.0: Translate.

let options = {
    method: 'POST',
    baseUrl: endpoint,
    url: 'translate',
    qs: {
      'api-version': '3.0',
      'to': ['de', 'it']
    },
    headers: {
      'Ocp-Apim-Subscription-Key': subscriptionKey,
      'Content-type': 'application/json',
      'X-ClientTraceId': uuidv4().toString()
    },
    body: [{
          'text': 'Hello World!'
    }],
    json: true,
};

要求を認証する最も簡単な方法は、このサンプルで使用している Ocp-Apim-Subscription-Key ヘッダーとしてサブスクリプション キーを渡すことです。The easiest way to authenticate a request is to pass in your subscription key as an Ocp-Apim-Subscription-Key header, which is what we use in this sample. または、アクセス トークンのサブスクリプション キーを交換し、アクセス トークンを一緒に Authorization ヘッダーとして渡して要求を検証することもできます。As an alternative, you can exchange your subscription key for an access token, and pass the access token along as an Authorization header to validate your request.

Cognitive Services のマルチサービス サブスクリプションを使用している場合は、要求のヘッダーに Ocp-Apim-Subscription-Region も含める必要があります。If you are using a Cognitive Services multi-service subscription, you must also include the Ocp-Apim-Subscription-Region in your request headers.

詳細については、認証に関するページをご覧ください。For more information, see Authentication.

要求の実行と応答の出力Make the request and print the response

次に、request() メソッドを使用して要求を作成します。Next, we'll create the request using the request() method. 前のセクションで作成した options オブジェクトを第 1 引数として渡すと、修飾された JSON 応答が出力されます。It takes the options object that we created in the previous section as the first argument, then prints the prettified JSON response.

request(options, function(err, res, body){
    console.log(JSON.stringify(body, null, 4));
});

注意

このサンプルでは、options オブジェクト内で HTTP 要求を定義しています。In this sample, we're defining the HTTP request in the options object. 一方、要求モジュールでは、.post.get などの便利なメソッドもサポートされています。However, the request module also supports convenience methods, like .post and .get. 詳細については、便利なメソッドに関するセクションを参照してください。For more information, see convenience methods.

すべてをまとめた配置Put it all together

これで、Translator Text API を呼び出して JSON 応答を返す簡単なプログラムが完成しました。That's it, you've put together a simple program that will call the Translator Text API and return a JSON response. ここで、プログラムを実行してみましょう。Now it's time to run your program:

node translate-text.js

作成したコードをサンプル コードと比較したい場合は、完全なサンプルを GitHub から入手できます。If you'd like to compare your code against ours, the complete sample is available on GitHub.

応答のサンプルSample response

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "translations": [
            {
                "text": "Hallo Welt!",
                "to": "de"
            },
            {
                "text": "Salve, mondo!",
                "to": "it"
            }
        ]
    }
]

リソースのクリーンアップClean up resources

サブスクリプション キーをプログラムにハードコーディングしている場合は、このクイック スタートを終了するときにサブスクリプション キーを必ず削除してください。If you've hardcoded your subscription key into your program, make sure to remove the subscription key when you're finished with this quickstart.

次の手順Next steps

API のリファレンスを見て、Translator Text API でできるすべてのことを理解してください。Take a look at the API reference to understand everything you can do with the Translator Text API.

前提条件Prerequisites

このクイック スタートでは以下が必要です。This quickstart requires:

セットアップSet up

Translator Text リソースを作成するCreate a Translator Text resource

Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用して、ローカル コンピューター上に Translator Text のリソースを作成します。Create a resource for Translator Text using the Azure portal or Azure CLI on your local machine. さらに、以下を実行できます。You can also:

  • 7 日間有効な試用版のキーを無料で入手する。Get a trial key valid for 7 days for free. これは、サインアップ後に Azure Web サイトで入手できます。After signing up, it will be available on the Azure website.
  • Azure portal で既存のリソースを表示する。View an existing resource in the Azure portal.

試用版のサブスクリプションまたはリソースからキーを取得した後、環境変数を 2 つ作成します。After you get a key from your trial subscription or resource, create two environment variables:

  • TRANSLATOR_TEXT_SUBSCRIPTION_KEY - Translator Text リソースのサブスクリプション キー。TRANSLATOR_TEXT_SUBSCRIPTION_KEY - The subscription key for your Translator Text resource.
  • TRANSLATOR_TEXT_ENDPOINT - Translator Text のグローバル エンドポイント。TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. https://api.cognitive.microsofttranslator.com/を使用します。Use https://api.cognitive.microsofttranslator.com/.

プロジェクトの作成と必要なモジュールのインポートCreate a project and import required modules

普段使用している IDE またはエディターで、新しい Go プロジェクトを作成します。Create a new Go project using your favorite IDE or editor. 次に、このコード スニペットをプロジェクトの translate-text.go という名前のファイルにコピーします。Then copy this code snippet into your project in a file named translate-text.go.

package main

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

main 関数を作成するCreate the main function

このサンプルは、Translator Text のサブスクリプション キーとエンドポイントを環境変数 TRANSLATOR_TEXT_SUBSCRIPTION_KEY および TRANSLATOR_TEXT_ENDPOINT から読み取ることを試みます。This sample will try to read your Translator Text subscription key and endpoint from these environment variables: TRANSLATOR_TEXT_SUBSCRIPTION_KEY and TRANSLATOR_TEXT_ENDPOINT. 環境変数を使い慣れていない場合は、subscriptionKeyendpoint を文字列として設定し、条件ステートメントをコメント アウトすることができます。If you're not familiar with environment variables, you can set subscriptionKey and endpoint as strings and comment out the conditional statements.

このコードをプロジェクトにコピーします。Copy this code into your project:

func main() {
    /*
    * Read your subscription key from an env variable.
    * Please note: You can replace this code block with
    * var subscriptionKey = "YOUR_SUBSCRIPTION_KEY" if you don't
    * want to use env variables. If so, be sure to delete the "os" import.
    */
    if "" == os.Getenv("TRANSLATOR_TEXT_SUBSCRIPTION_KEY") {
      log.Fatal("Please set/export the environment variable TRANSLATOR_TEXT_SUBSCRIPTION_KEY.")
    }
    subscriptionKey := os.Getenv("TRANSLATOR_TEXT_SUBSCRIPTION_KEY")
    if "" == os.Getenv("TRANSLATOR_TEXT_ENDPOINT") {
      log.Fatal("Please set/export the environment variable TRANSLATOR_TEXT_ENDPOINT.")
    }
    endpoint := os.Getenv("TRANSLATOR_TEXT_ENDPOINT")
    uri := endpoint + "/translate?api-version=3.0"
    /*
     * This calls our breakSentence function, which we'll
     * create in the next section. It takes a single argument,
     * the subscription key.
     */
    translate(subscriptionKey, uri)
}

テキストを翻訳するための関数を作成するCreate a function to translate text

テキストを翻訳する関数を作成しましょう。Let's create a function to translate text. この関数では、単一の引数である Translator Text サブスクリプション キーを使用します。This function will take a single argument, your Translator Text subscription key.

func translate(subscriptionKey string, uri string) {
    /*  
     * In the next few sections, we'll add code to this
     * function to make a request and handle the response.
     */
}

次に、URL を構築しましょう。Next, let's construct the URL. URL は、Parse() メソッドと Query() メソッドを使用して構築されます。The URL is built using the Parse() and Query() methods. Add() メソッドによってパラメーターが追加されることに気付くでしょう。You'll notice that parameters are added with the Add() method. このサンプルでは、英語からイタリア語とドイツ語 (deit) に翻訳しています。In this sample, you're translating from English to German and Italian: de and it.

このコードを translate 関数内にコピーします。Copy this code into the translate function.

// Build the request URL. See: https://golang.org/pkg/net/url/#example_URL_Parse
u, _ := url.Parse(uri)
q := u.Query()
q.Add("to", "de")
q.Add("to", "it")
u.RawQuery = q.Encode()

注意

エンドポイント、ルート、および要求パラメーターの詳細については、「Translator Text API 3.0: Translate」をご覧ください。For more information about endpoints, routes, and request parameters, see Translator Text API 3.0: Translate.

要求本文の構造体を作成するCreate a struct for your request body

次に、要求本文の匿名の構造体を作成し、json.Marshal() を使用して JSON としてエンコードします。Next, create an anonymous structure for the request body and encode it as JSON with json.Marshal(). そのコードを translate 関数に追加します。Add this code to the translate function.

// Create an anonymous struct for your request body and encode it to JSON
body := []struct {
    Text string
}{
    {Text: "Hello, world!"},
}
b, _ := json.Marshal(body)

要求を作成するBuild the request

要求本文を JSON としてエンコードしたので、ご自分の POST 要求を作成し、Translator Text API を呼び出すことができます。Now that you've encoded the request body as JSON, you can build your POST request, and call the Translator Text API.

// 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", subscriptionKey)
req.Header.Add("Content-Type", "application/json")

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

Cognitive Services のマルチサービス サブスクリプションを使用している場合は、要求のパラメーターに Ocp-Apim-Subscription-Region も含める必要があります。If you are using a Cognitive Services multi-service subscription, you must also include the Ocp-Apim-Subscription-Region in your request parameters. マルチサービス サブスクリプションを使用した認証の詳細を参照してくださいLearn more about authenticating with the multi-service subscription.

応答を処理して出力するHandle and print the response

次のコードを translate 関数に追加して、JSON 応答をデコードした後、結果を書式設定して出力します。Add this code to the translate function to decode the JSON response, and then format and print the result.

// 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)

すべてをまとめた配置Put it all together

これで、Translator Text API を呼び出して JSON 応答を返す簡単なプログラムが完成しました。That's it, you've put together a simple program that will call the Translator Text API and return a JSON response. ここで、プログラムを実行してみましょう。Now it's time to run your program:

go run translate-text.go

作成したコードをサンプル コードと比較したい場合は、完全なサンプルを GitHub から入手できます。If you'd like to compare your code against ours, the complete sample is available on GitHub.

応答のサンプルSample response

成功した応答は、次の例に示すように JSON で返されます。A successful response is returned in JSON as shown in the following example:

[
  {
    "detectedLanguage": {
      "language": "en",
      "score": 1.0
    },
    "translations": [
      {
        "text": "Hallo Welt!",
        "to": "de"
      },
      {
        "text": "Salve, mondo!",
        "to": "it"
      }
    ]
  }
]

次の手順Next steps

API のリファレンスを見て、Translator Text API でできるすべてのことを理解してください。Take a look at the API reference to understand everything you can do with the Translator Text API.

参照See also