Translator Text API v3.0Translator Text API v3.0

新機能What's new?

Translator Text API のバージョン 3 には、最新の JSON ベースの Web API が用意されています。Version 3 of the Translator Text API provides a modern JSON-based Web API. 既存の機能をより少ない操作に統合することによって、使いやすさとパフォーマンスが向上しています。また、新機能が用意されています。It improves usability and performance by consolidating existing features into fewer operations and it provides new features.

  • ある言語のテキストを、ある書記体系から別の書記体系に変換する音訳。Transliteration to convert text in one language from one script to another script.
  • 1 つの要求での複数言語への翻訳。Translation to multiple languages in one request.
  • 1 つの要求での言語の検出、翻訳、および音訳。Language detection, translation, and transliteration in one request.
  • 用語の翻訳候補を検索し、逆翻訳やコンテキスト内で使用されている用語を示す例を見つけるための辞書。Dictionary to lookup alternative translations of a term, to find back-translations and examples showing terms used in context.
  • 多くの情報が得られる言語検出結果。More informative language detection results.

ベース URLBase URLs

Microsoft Translator のサービスは、複数のデータセンター拠点から提供されます。Microsoft Translator is served out of multiple datacenter locations. 現在、それらの拠点は、6 つの Azure リージョンに存在します。Currently they are located in 6 Azure regions:

  • アメリカ合衆国: 米国西部 2 および米国中西部Americas: West US 2 and West Central US
  • アジア太平洋: 東南アジアおよび韓国南部Asia Pacific: Southeast Asia and Korea South
  • ヨーロッパ: 北ヨーロッパおよび西ヨーロッパEurope: North Europe and West Europe

Microsoft Translator Text API への要求は、ほとんどの場合、その要求の送信元に最も近いデータセンターによって処理されます。Requests to the Microsoft Translator Text API are in most cases handled by the datacenter that is closest to where the request originated. データセンターに障害が発生している場合は、そのリージョン以外に要求がルーティングされます。In case of a datacenter failure, the request may be routed outside of the region.

要求を特定のデータセンターに強制的に処理させるには、API 要求内のグローバル エンドポイントを目的のリージョンのエンドポイントに変更します。To force the request to be handled by a specific datacenter, change the Global endpoint in the API request to the desired regional endpoint:

説明Description リージョンRegion ベース URLBase URL
AzureAzure グローバルGlobal api.cognitive.microsofttranslator.comapi.cognitive.microsofttranslator.com
AzureAzure 北米North America api-nam.cognitive.microsofttranslator.comapi-nam.cognitive.microsofttranslator.com
AzureAzure ヨーロッパEurope api-eur.cognitive.microsofttranslator.comapi-eur.cognitive.microsofttranslator.com
AzureAzure アジア太平洋Asia Pacific api-apc.cognitive.microsofttranslator.comapi-apc.cognitive.microsofttranslator.com

AuthenticationAuthentication

Microsoft Cognitive Services の Translator Text API または Cognitive Services マルチサービスをサブスクライブし、(Azure portal で入手できる) お客様のサブスクリプション キーを使用して認証します。Subscribe to Translator Text API or Cognitive Services multi-service in Microsoft Cognitive Services, and use your subscription key (available in the Azure portal) to authenticate.

お客様のサブスクリプションの認証に使用できるヘッダーは 3 つあります。There are three headers that you can use to authenticate your subscription. 次の表で、それぞれの使用方法を説明します。This table provides describes how each is used:

headersHeaders 説明Description
Ocp-Apim-Subscription-KeyOcp-Apim-Subscription-Key 秘密鍵を渡そうとしている場合は、Cognitive Services サブスクリプションで使用しますUse with Cognitive Services subscription if you are passing your secret key.
値は、Translator Text API に対するユーザーのサブスクリプションの Azure 秘密鍵です。The value is the Azure secret key for your subscription to Translator Text API.
AuthorizationAuthorization 認証トークンを渡そうとしている場合は、Cognitive Services サブスクリプションで使用します。Use with Cognitive Services subscription if you are passing an authentication token.
値はベアラー トークンで、Bearer <token> となります。The value is the Bearer token: Bearer <token>.
Ocp-Apim-Subscription-RegionOcp-Apim-Subscription-Region "Cognitive Services マルチサービス サブスクリプションで、マルチサービスの秘密鍵を渡す場合に使用します"。Use with Cognitive Services multi-service subscription if you are passing an multi-service secret key.
値は、マルチサービス サブスクリプションのリージョンです。The value is the region of the multi-service subscription. マルチサービス サブスクリプションを使用しない場合、この値は省略できます。This value is optional when not using an multi-service subscription.

秘密鍵Secret key

1 つ目の方法は、Ocp-Apim-Subscription-Key ヘッダーを使用した認証です。The first option is to authenticate using the Ocp-Apim-Subscription-Key header. 単に、Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> ヘッダーをお客様の要求に追加します。Simply add the Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> header to your request.

承認トークンAuthorization token

または、お客様の秘密鍵をアクセス トークンと交換する方法もあります。Alternatively, you can exchange your secret key for an access token. このトークンをそれぞれの要求に Authorization ヘッダーとして含めます。This token is included with each request as the Authorization header. 承認トークンを取得するには、次の URL に POST 要求を送信します。To obtain an authorization token, make a POST request to the following URL:

環境Environment 承認サービスの URLAuthentication service URL
AzureAzure https://api.cognitive.microsoft.com/sts/v1.0/issueToken

指定の秘密鍵でトークンを取得する要求の例を次に示します。Here are example requests to obtain a token given a secret key:

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-key>' --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken'

// Pass secret key using query string parameter
curl --data "" 'https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>'

要求が成功すると、応答本文内にプレーン テキストとしてエンコードされたアクセス トークンが返されます。A successful request returns the encoded access token as plain text in the response body. 有効なトークンは、Authorization 内のベアラー トークンとして Translator サービスに渡されます。The valid token is passed to the Translator service as a bearer token in the Authorization.

Authorization: Bearer <Base64-access_token>

認証トークンは 10 分間有効です。An authentication token is valid for 10 minutes. Translator API に対して複数の呼び出しを行う場合は、このトークンを再利用する必要があります。The token should be re-used when making multiple calls to the Translator APIs. ただし、プログラムで、長時間にわたって Translator API に要求を行う場合は、一定間隔 (例: 8 分ごと) でプログラムから新しいアクセス トークンを要求する必要があります。However, if your program makes requests to the Translator API over an extended period of time, then your program must request a new access token at regular intervals (e.g. every 8 minutes).

マルチサービスのサブスクリプションMulti-service subscription

最後の認証オプションは、Cognitive Services のマルチサービス サブスクリプションを使用する方法です。The last authentication option is to use a Cognitive Service’s multi-service subscription. この場合、単一の秘密鍵を使用して複数のサービスの要求を認証することができます。This allows you to use a single secret key to authenticate requests for multiple services.

マルチサービスの秘密鍵を使用するときは、2 つの認証ヘッダーをお客様の要求に含める必要があります。When you use a multi-service secret key, you must include two authentication headers with your request. 1 つ目で秘密鍵を渡し、2 つ目でお客様のサブスクリプションに関連付けられているリージョンを指定します。The first passes the secret key, the second specifies the region associated with your subscription.

  • Ocp-Apim-Subscription-Key
  • Ocp-Apim-Subscription-Region

マルチサービスの Text API サブスクリプションではリージョンが必須です。Region is required for the multi-service Text API subscription. マルチサービスのサブスクリプション キーを使用する場合、選択したリージョンでのみテキスト翻訳を使用でき、Azure portal を通してマルチサービスのサブスクリプションにサインアップしたときに選択したリージョンと同じにする必要があります。The region you select is the only region that you can use for text translation when using the multi-service subscription key, and must be the same region you selected when you signed up for your multi-service subscription through the Azure portal.

利用可能なリージョンは australiaeastbrazilsouthcanadacentralcentralindiacentraluseuapeastasiaeastuseastus2japaneastnortheuropesouthcentralussoutheastasiauksouthwestcentraluswesteuropewestuswestus2 です。Available regions are australiaeast, brazilsouth, canadacentral, centralindia, centraluseuap, eastasia, eastus, eastus2, japaneast, northeurope, southcentralus, southeastasia, uksouth, westcentralus, westeurope, westus, and westus2.

クエリ文字列のパラメーター Subscription-Key で秘密鍵を渡す場合、クエリ パラメーター Subscription-Region でリージョンを指定する必要があります。If you pass the secret key in the query string with the parameter Subscription-Key, then you must specify the region with query parameter Subscription-Region.

ベアラー トークンを使用する場合は、リージョンのエンドポイント (https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken) からトークンを取得する必要があります。If you use a bearer token, you must obtain the token from the region endpoint: https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken.

ErrorsErrors

標準的なエラー応答は、error という名前の名前/値ペアを含む JSON オブジェクトです。A standard error response is a JSON object with name/value pair named error. 値は、以下のプロパティを含む JSON オブジェクトでもあります。The value is also a JSON object with properties:

  • code:サーバー定義のエラー コード。code: A server-defined error code.

  • message:エラーを人間が読み取ることができる表現にした文字列。message: A string giving a human-readable representation of the error.

たとえば、無料試用版のサブスクリプションを使用したユーザーは、無料クォータがなくなると、次のエラーを受け取ります。For example, a customer with a free trial subscription would receive the following error once the free quota is exhausted:

{
  "error": {
    "code":403001,
    "message":"The operation is not allowed because the subscription has exceeded its free quota."
    }
}

このエラーコードは 3 桁の HTTP ステータス コードの後に、エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です。The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. 一般的なエラー コード:Common error codes are:

コードCode 説明Description
400000400000 無効な要求入力があります。One of the request inputs is not valid.
400001400001 "scope" パラメーターが無効です。The "scope" parameter is invalid.
400002400002 "category" パラメーターが無効です。The "category" parameter is invalid.
400003400003 言語指定子が見つからないか無効です。A language specifier is missing or invalid.
400004400004 ターゲット スクリプト指定子 ("To script") が見つからないか無効です。A target script specifier ("To script") is missing or invalid.
400005400005 入力テキストが見つからないか無効です。An input text is missing or invalid.
400006400006 言語とスクリプトの組み合わせが無効です。The combination of language and script is not valid.
400018400018 ソース スクリプト指定子 ("From script") が見つからないか無効です。A source script specifier ("From script") is missing or invalid.
400019400019 サポートされていない言語が指定されています。One of the specified language is not supported.
400020400020 一連の入力テキストに無効な要素があります。One of the elements in the array of input text is not valid.
400021400021 API バージョン パラメーターが見つからないか無効です。The API version parameter is missing or invalid.
400023400023 無効な言語ペアが指定されています。One of the specified language pair is not valid.
400035400035 ソース言語 ("From" フィールド) が無効です。The source language ("From" field) is not valid.
400036400036 ターゲット言語 ("To" フィールド) が見つからないか無効です。The target language ("To" field) is missing or invalid.
400042400042 無効なオプション ("Options" フィールド) が指定されています。One of the options specified ("Options" field) is not valid.
400043400043 クライアント トレース ID (ClientTraceId フィールドか X-ClientTranceId ヘッダー) が見つからないか無効です。The client trace ID (ClientTraceId field or X-ClientTranceId header) is missing or invalid.
400050400050 入力テキストが長すぎます。The input text is too long.
400064400064 "translation" パラメーターが見つからないか無効です。The "translation" parameter is missing or invalid.
400070400070 ターゲット スクリプトの個数 (ToScript パラメーター) がターゲット言語 (To パラメーター) の個数と一致しません。The number of target scripts (ToScript parameter) does not match the number of target languages (To parameter).
400071400071 TextType に対する値が無効です。The value is not valid for TextType.
400072400072 一連の入力テストの要素数が多すぎます。The array of input text has too many elements.
400073400073 スクリプト パラメーターが無効です。The script parameter is not valid.
400074400074 要求の本体が有効な JSON ではありません。The body of the request is not valid JSON.
400075400075 言語ペアとカテゴリの組み合わせが無効です。The language pair and category combination is not valid.
400077400077 要求の最大サイズを超えています。The maximum request size has been exceeded.
400079400079 from 言語と to 言語間の翻訳に要求されたカスタム システムは存在しません。The custom system requested for translation between from and to language does not exist.
401000401000 資格情報が見つからないか無効なため、要求は許可されません。The request is not authorized because credentials are missing or invalid.
401015401015 「指定された資格情報は Speech API に対するものです。"The credentials provided are for the Speech API. この要求には、Text API に対する資格情報が必要です。This request requires credentials for the Text API. Translator Text API のサブスクリプションを使用してください。」Please use a subscription to Translator Text API."
403000403000 この操作は許可されていません。The operation is not allowed.
403001403001 サブスクリプションが無料クォータを超えているため、この操作は許可されていません。The operation is not allowed because the subscription has exceeded its free quota.
405000405000 要求リソースに対してこの要求メソッドを使用することはできません。The request method is not supported for the requested resource.
408001408001 要求されたカスタムの翻訳システムはまだ使用できません。The custom translation system requested is not yet available. 少し待ってからもう一度お試しください。Please retry in a few minutes.
415000415000 Content-Type Content-type ヘッダーが見つからないか無効です。The Content-Type header is missing or invalid.
429000、429001、429002429000, 429001, 429002 クライアントから送信されている要求が多すぎるため、サーバーによって要求が拒否されました。The server rejected the request because the client is sending too many requests. スロットリングを回避するため、要求の頻度を減らしてください。Reduce the frequency of requests to avoid throttling.
500000500000 予期しないエラーが発生しました。An unexpected error occurred. エラーが解決しない場合は、エラーの発生日時と応答ヘッダーの要求識別子 X-RequestID、要求ヘッダーのクライアント識別子 X-ClientTraceID を添えてその旨をご報告ください。If the error persists, report it with date/time of error, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503000503000 サービスが一時的に利用できません。Service is temporarily unavailable. もう一度試してください。Please retry. エラーが解決しない場合は、エラーの発生日時と応答ヘッダーの要求識別子 X-RequestID、要求ヘッダーのクライアント識別子 X-ClientTraceID を添えてその旨をご報告ください。If the error persists, report it with date/time of error, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.