Microsoft Translator API

Bing TranslatorのAPIである、Microsoft Translator APIについて解説します。このAPIには、

の3つの利用方法があります。

AJAX インターフェイス

実行例

 

※アプリケーションIDのトークンをページ表示時に取得しているため、一定時間が経過すると翻訳できなくなります。そのときはページを再読み込みしてください。

アプリケーションIDの取得

リクエスト

アプリケーションIDのトークンを取得します。

GET http://api.microsofttranslator.com/V2/Ajax.svc/GetAppIdToken
GetAppIdToken Method | MSDN
パラメータ 説明 必須
appId アプリケーションID ○
minRatigRead 翻訳結果として取得可能な翻訳ランクの最小値  
maxRatingWrite ユーザーが登録可能な翻訳ランクの最大値  
expireSeconds トークンの有効期間。単位は秒数

範囲は1から86400 (1日) まで

 ○
oncomplete レスポンスを受け取るコールバック関数  

レスポンス

MIME Typeはapplication/x-javascriptで、トークンがダブルクォートで囲まれた形式で返されます。

Translate()メソッド

テキストを翻訳します。

リクエスト

GET http://api.microsofttranslator.com/V2/Ajax.svc/Translate
Translate Method | MSDN
パラメータ 説明 必須
appId アプリケーションIDまたはアプリケーションIDのトークン ○
text 翻訳するテキスト ○
from 翻訳するテキストの言語コード (ISO 639-1)  
to 翻訳結果のテキストの言語コード (ISO 639-1) ○
contentType 翻訳するテキストの書式
  • text/plain
  • text/html
のいずれか。 		 
category 翻訳するテキストのカテゴリ

サポートされるのは'general'のみ

  
oncomplete レスポンスを受け取るコールバック関数  

レスポンス

翻訳結果のテキストを引数として、コールバック関数が呼び出されます。

有効期限の切れたトークンを使用したときは、

ArgumentException: The token has expired
Parameter name: appId : ID=0934.V2_Json.Translate.00000000

のようにテキスト形式で結果が返されます。このときコールバック関数は呼び出されません。

Speak()メソッド

指定のテキストを音声で読み上げるストリームのURLを返します。

GET http://api.microsofttranslator.com/V2/Ajax.svc/Speak
Speak Method | MSDN
パラメータ 説明 必須
appId アプリケーションIDまたはアプリケーションIDのトークン ○
text 読み上げるテキスト ○
language 読み上げるテキストの言語 (ISO 639-1) ○
format 音声のフォーマット
  • audio/wav (既定値)
  • audio/mp3
  
options 音声データの品質
  • MaxQuality
  • MinSize (既定値)
  
oncomplete レスポンスを受け取るコールバック関数  

対応言語

対応言語のコードはGetLanguagesForSpeakメソッドで調べられます。またその言語コードの言語名はGetLanguageNamesメソッドで取得できます。Translator Language Codes | MSDN

言語コード 言語名
ca カタロニア語
ca-es カタロニア語 (スペイン)
da デンマーク語
da-dk デンマーク語 (デンマーク)
de ドイツ語
de-de ドイツ語 (ドイツ)
en 英語
en-au 英語 (オーストラリア)
en-ca 英語 (カナダ)
en-gb 英語 (英国)
en-in 英語 (インド)
en-us 英語 (米国)
es スペイン語
es-es スペイン語 (スペイン)
es-mx スペイン語 (メキシコ)
fi フィンランド語
fi-fi フィンランド語 (フィンランド)
fr フランス語
fr-ca フランス語 (カナダ)
fr-fr フランス語 (フランス)
it イタリア語
it-it イタリア語 (イタリア)
ja 日本語
ja-jp 日本語 (日本)
ko 韓国語
ko-kr 韓国語 (韓国)
nb-no ノルウェー語 (ノルウェー)
nl オランダ語
nl-nl オランダ語 (オランダ)
no ノルウェー語
pl ポーランド語
pl-pl ポーランド語 (ポーランド)
pt ポルトガル語
pt-br ポルトガル語 (ブラジル)
pt-pt ポルトガル語 (ポルトガル)
ru ロシア語
ru-ru ロシア語 (ロシア)
sv スウェーデン語
sv-se スウェーデン語 (スウェーデン)
zh-chs 簡体字中国語
zh-cht 繁体字中国語
zh-cn 簡体字中国語 (中華人民共和国)
zh-hk 繁体字中国語 (香港)
zh-tw 繁体字中国語 (台湾)
※2012/03現在の対応状況

参考

≫Web Speech APIによる音声合成

参考

SOAP インターフェイス

≫SOAP

参考

HTTP インターフェイス

アクセストークンの取得

Translator APIはBingのアプリケーションIDで利用できますが、これはすでに非推奨とされています。その代替として、今後はWindows Azure MarketplaceのIDからアクセストークンを取得するものとされています。Translate Method | MSDN

このWindows Azure Marketplaceからの利用には制限があり、翻訳できる文字数が1月あたり200万文字 (2012/12現在) となっています。それを超えた利用には、文字数に応じて費用が発生します。

アクセストークンを取得するには、下表に示す顧客IDと顧客の秘密が必要となります。

用語解説
用語 意味 別名
顧客ID Windows Azure Marketの登録ID
  • クライアントID
  • Client ID
顧客の秘密 Windows Azure Marketに登録された
アプリケーションのID
  • Client Secret
  • Client Secret Value
  • Client Secret Key

顧客IDと顧客の秘密の取得

顧客IDと顧客の秘密を取得するには、次のようにします。

  1. Windows Liveへサインインし、Windows Live IDを取得する。
  2. Windows Azure Marketplaceへサインインし、顧客IDを取得する。
  3. 開発者でアプリケーションを登録し、顧客の秘密を取得する。
  4. Microsoft Translator | Windows Azure MarketplaceでMicrosoft Translatorの使用権を取得する。

アクセストークンの取得

顧客IDと顧客の秘密を利用して、アクセストークンを取得します。

アクセストークンの有効期間は10分間です。その後は再びアクセストークンを取得し直す必要があります。

参考

翻訳

リクエスト

http://api.microsofttranslator.com/V2/Http.svc/Translate

1回のリクエストに含められる文字は、スペースやマークアップを含めて1000文字までです。

レスポンス

<string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">こんにちは</string>

サンプルコード

  1. 顧客IDと顧客の秘密をパラメータに含め、認証URLへリクエストする。そしてアクセストークンを取得する。
  2. アクセストークンをHTTPヘッダに含め、APIのURLへリクエストする。そして翻訳結果を取得する。
define( 'CLIENT_ID', 'xx' );      // 顧客ID
define( 'CLIENT_SECRET', 'yy' );  // 顧客の秘密

define( 'GRANT_TYPE', 'client_credentials' );
define( 'SCOPE_URL', 'http://api.microsofttranslator.com' );
define( 'AUTH_URL', 'https://datamarket.accesscontrol.windows.net/v2/OAuth2-13/' );


$text = 'hello'; // 翻訳するテキスト
$from = 'en';    // 翻訳するテキストの言語コード
$to = 'ja';      // 翻訳結果のテキストの言語コード

try
{
    $accessToken = GetAccessTokens( GRANT_TYPE, SCOPE_URL, CLIENT_ID, CLIENT_SECRET, AUTH_URL );
    $authHeader = 'Authorization: Bearer '.$accessToken;

    $url = 'http://api.microsofttranslator.com/V2/Http.svc/Translate?'
        .http_build_query( compact( 'text', 'from', 'to' ) );

    $response = Request( $url, $authHeader );
    echo $response;
}
catch( Exception $e )
{
    echo $e->getMessage();
}

function GetAccessTokens( $grant_type, $scope, $client_id, $client_secret, $auth_url )
{
    $params = http_build_query(
        compact( 'grant_type', 'scope', 'client_id, 'client_secret' ) );

    $ch = curl_init();
    curl_setopt( $ch, CURLOPT_URL, $auth_url );
    curl_setopt( $ch, CURLOPT_POST, TRUE );
    curl_setopt( $ch, CURLOPT_POSTFIELDS, $params );
    curl_setopt( $ch, CURLOPT_RETURNTRANSFER, TRUE );
    curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );

    $response = curl_exec( $ch );
    if( curl_errno( $ch ) )
    {
        throw new Exception( curl_error( $ch ) );
    }
    curl_close( $ch );

    $json = json_decode( $response );
    if( isset( $json->error ) )
    {
        throw new Exception( $json->error_description );
    }

    return $json->access_token;
}

function Request( $url, $authHeader )
{
    $ch = curl_init();
    curl_setopt( $ch, CURLOPT_URL, $url );
    curl_setopt( $ch, CURLOPT_HTTPHEADER, array( $authHeader, 'Content-Type: text/xml' ) );
    curl_setopt( $ch, CURLOPT_RETURNTRANSFER, TRUE );
    curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, FALSE );

    $response = curl_exec( $ch );
    if( curl_errno( $ch ) )
    {
        throw new Exception( curl_error( $ch ) );
    }
    curl_close( $ch );

    return $response;
}

エラーコード

認証に失敗した場合に返されるエラーコードの一覧は、ACS (Windows Azure Access Control Service) Error Codesにあります。

まれにエラーコードもなく、次のようなレスポンスが返されることがあります。

<html>
  <body>
    <h1>Argument Exception</h1>
    <p>Method: Translate()</p>
    <p>Parameter: </p>
    <p>Message: Signature verification of the incoming token failed.</p>
    <code></code>
    <p>message id=3817.V2_Rest.Translate.00000000</p>
  </body>
</html>

これはサービス側の問題のようです。Problem with Microsoft translator API | MSDN

参考

参考

関連ページ

複数の技術系サイトから、まとめて検索