Translator v3.0

新機能

Translator のバージョン 3.0 は、最新の JSON ベースの Web API が用意されています。 既存の機能をより少ない操作に統合することによって、使いやすさとパフォーマンスが向上しています。また、新機能が用意されています。

• ある言語のテキストを、ある書記体系から別の書記体系に変換する音訳。
• 1 つの要求での複数言語への翻訳。
• 1 つの要求での言語の検出、翻訳、および音訳。
• 用語の翻訳候補を検索し、逆翻訳やコンテキスト内で使用されている用語を示す例を見つけるための辞書。
• 多くの情報が得られる言語検出結果。

ベース URL

Translator への要求は、ほとんどの場合、その要求の送信元に最も近いデータセンターによって処理されます。 グローバル エンドポイントを使用するときにデータセンターで障害が発生した場合、要求は地理的な場所の外部にルーティングされる可能性があります。

特定の地域内で要求を強制的に処理するには、目的の地理的エンドポイントを使用します。 すべての要求は、地域内のデータセンター間で処理されます。

✔️ 特徴: Translator Text

サービス エンドポイント	要求処理データ センター
グローバル (推奨): api.cognitive.microsofttranslator.com	最も近い利用可能なデータセンター。
南北アメリカ: api-nam.cognitive.microsofttranslator.com	米国東部 2 • 米国西部 2
アジア太平洋: api-apc.cognitive.microsofttranslator.com	東日本 • 東南アジア
ヨーロッパ (スイスを除く): api-eur.cognitive.microsofttranslator.com	フランス中部 • 西ヨーロッパ
スイス: 詳細については、「スイスのサービス エンドポイント」を "参照してください"。	スイス北部 • スイス西部

スイスのサービス エンドポイント

スイス北部またはスイス西部にあるリソースを使用しているお客様は、Text API 要求が確実にスイス内で処理されるようにすることができます。 要求がスイス内で処理されるようにするには、Translator リソースを Resource region Switzerland North または Switzerland West 内に作成した後、API 要求内でそのリソースのカスタム エンドポイントを使用します。

たとえば、Azure portal で [Resource region] を [Switzerland North] として Translator リソースを作成し、リソース名が my-swiss-n である場合、カスタム エンドポイントは "https​://my-swiss-n.cognitiveservices.azure.com" となります。 翻訳する要求の例を次に示します。

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

カスタム翻訳ツールは、現在スイスでは使用できません。

認証

Azure AI サービス の Translator または マルチサービス をサブスクライブし、(Azure portal で入手できる) お客様のキーを使用して認証します。

お客様のサブスクリプションの認証に使用できるヘッダーは 3 つあります。 次の表は、それぞれの使用方法を示しています。

ヘッダー	説明
Ocp-Apim-Subscription-Key	秘密鍵を渡そうとしている場合は、Azure AI サービス サブスクリプションで使用します。 値は、Translator に対するユーザーのサブスクリプションの Azure 秘密鍵です。
承認	認証トークンを渡す場合は、Azure AI サービス サブスクリプションで使用します。 値はベアラー トークンで、Bearer <token> となります。
Ocp-Apim-Subscription-Region	マルチサービスとリージョン トランスレータ― リソースと共に使用します。 値は、マルチサービスまたはリージョン トランスレーター リソースのリージョンです。 グローバル トランスレーター リソースを使用する場合、この値は省略可能です。

秘密鍵

1 つ目の方法は、Ocp-Apim-Subscription-Key ヘッダーを使用した認証です。 Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> ヘッダーをお客様の要求に追加します。

グローバル リソースを使用した認証

グローバル トランスレーター リソースを使用する場合は、Translator を呼び出すために 1 つのヘッダーを含める必要があります。

ヘッダー	説明
Ocp-Apim-Subscription-Key	値は、Translator に対するユーザーのサブスクリプションの Azure 秘密鍵です。

グローバル トランスレーター リソースを使用する Translator を呼び出す要求の例を次に示します。

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

リージョン リソースを使用した認証

リージョンのトランスレーター リソースを使用するとき、2 つのヘッダーで Translator を呼び出す必要があります。

ヘッダー	説明
Ocp-Apim-Subscription-Key	値は、Translator に対するユーザーのサブスクリプションの Azure 秘密鍵です。
Ocp-Apim-Subscription-Region	値は、トランスレータ― リソースのリージョンです。

リージョン トランスレーター リソースを使用する Translator を呼び出す要求の例を次に示します。

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

マルチサービス リソースを使用した認証

マルチ サービス リソースを使用すると、単一の API キーを使用して、複数のサービスに対する要求を認証できます。

マルチサービスの秘密鍵を使用するときは、2 つの認証ヘッダーをお客様の要求に含める必要があります。 Translator を呼び出すために必要なヘッダーが 2 つあります。

ヘッダー	説明
Ocp-Apim-Subscription-Key	値は、マルチサービス リソースの Azure 秘密鍵です。
Ocp-Apim-Subscription-Region	値は、マルチサービス リソースのリージョンです。

マルチサービスの Text API サブスクリプションではリージョンが必須です。 選択したリージョンが、マルチサービスのキーを使用する際にテキスト翻訳に使用できる唯一のリージョンとなります。 Azure portal でマルチサービスのサブスクリプションへのサインアップ時に選択したリージョンと同じにする必要があります。

クエリ文字列のパラメーター Subscription-Key で秘密鍵を渡す場合、クエリ パラメーター Subscription-Region でリージョンを指定する必要があります。

アクセス トークンを使用した認証

または、お客様の秘密鍵をアクセス トークンと交換する方法もあります。 このトークンをそれぞれの要求に Authorization ヘッダーとして含めます。 承認トークンを取得するには、次の URL に POST 要求を送信します。

リソースの種類	承認サービスの URL
グローバル	https://api.cognitive.microsoft.com/sts/v1.0/issueToken
リージョンまたはマルチサービス	https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

グローバル リソースの秘密鍵が指定されたトークンを取得する要求の例を次に示します。

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

次に、米国中部にあるリージョン リソースの秘密鍵が指定されたトークンを取得する要求の例を示します。

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

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

要求が成功すると、応答本文内にプレーン テキストとしてエンコードされたアクセス トークンが返されます。 有効なトークンは、Authorization 内のベアラー トークンとして Translator サービスに渡されます。

Authorization: Bearer <Base64-access_token>

認証トークンは 10 分間有効です。 Translator に対して複数の呼び出しを行う場合は、このトークンを再利用する必要があります。 ただし、プログラムで、長時間にわたって Translator に要求を行う場合は、一定間隔 (たとえば、8 分ごと) でプログラムから新しいアクセス トークンを要求する必要があります。

Microsoft Entra ID を使った認証

Translator v3.0 では、Microsoft のクラウドベースの ID およびアクセス管理ソリューションである Microsoft Entra 認証がサポートされています。 Authorization ヘッダーにより、Translator サービスは、要求元のクライアントがリソースを使用することと要求を完了することを許可されているかどうかを検証できます。

前提条件

• Microsoft Entra ID を使用して認証する方法についての大まかな理解。

• マネージド ID へのアクセスを認証する方法についての大まかな理解。

ヘッダー

ヘッダー	値
承認	値は、Azure AD によって生成されるアクセス ベアラー トークンです。 ベアラー トークンは、認証の証明を提供し、リソースを使用するためのクライアントの承認を検証します。 認証トークンは 10 分間有効であり、Translator を複数回呼び出す場合に再利用する必要があります。 要求の例: 2 を参照してください。トークンを取得する
Ocp-Apim-Subscription-Region	値は、Translator リソースのリージョンです。 リソースがグローバルの場合、この値は省略可能です。
Ocp-Apim-ResourceId	値は、Translator リソース インスタンスのリソース ID です。 リソース ID は、Azure portal の Translator リソース → [プロパティ] で確認できます。 リソース ID の形式: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/

Translator のプロパティ ページ - Azure portal

重要

Cognitive Services ユーザー ロールをサービス プリンシパルに割り当てます。 このロールを割り当てることで、Translator リソースへのアクセス権をサービス プリンシパルに付与します。

使用例

グローバル エンドポイントを使用する

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

カスタム エンドポイントを使用する

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

マネージド ID を使用する例

Translator v3.0 では、マネージド ID へのアクセスの承認もサポートされています。 マネージド ID が Translator リソースに対して有効になっている場合は、マネージド ID によって生成されたベアラー トークンを要求ヘッダーで渡すことができます。

グローバル エンドポイントを使用する

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

カスタム エンドポイントを使用する

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

仮想ネットワークのサポート

翻訳サービスは、Azure パブリック クラウドのすべてのリージョンの Virtual Network (VNET) 機能で使用できるようになりました。 仮想ネットワークを有効にするには、「Azure AI サービス仮想ネットワークの構成」を参照してください。

この機能を有効にした後、カスタム エンドポイントを使用して Translator を呼び出す必要があります。 グローバル トランスレーター エンドポイント ("api.cognitive.microsofttranslator.com") は使用できず、アクセス トークンで認証することはできません。

トランスレーター リソースを作成し、選択したネットワークとプライベート エンドポイントからのアクセスを許可すると、カスタム エンドポイントを見つけることができます。

1. Azure portal で、Translator リソースに移動します。

2. [リソース管理] セクションで [ネットワーク] を選択します。

3. [ファイアウォールと仮想ネットワーク] タブで、[選択したネットワークとプライベート エンドポイント] を選択します。

   

4. [保存] を選択して変更を保存します。

5. [リソース管理] セクションで、[キーとエンドポイント] を選択します。

6. [仮想ネットワーク] タブを選択します。

7. テキスト翻訳とドキュメント翻訳のエンドポイントが一覧表示されています。

   

ヘッダー	説明
Ocp-Apim-Subscription-Key	値は、Translator に対するユーザーのサブスクリプションの Azure 秘密鍵です。
Ocp-Apim-Subscription-Region	値は、トランスレータ― リソースのリージョンです。 リソースが global の場合、この値は省略可能です。

カスタム エンドポイントを使用する Translator を呼び出す要求の例を次に示します。

// Pass secret key and region using headers
curl -X POST "https://<your-custom-domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

エラー

標準的なエラー応答は、error という名前の名前/値ペアを含む JSON オブジェクトです。 値は、以下のプロパティを含む JSON オブジェクトでもあります。

• code:サーバー定義のエラー コード。
• message:エラーを人間が読み取ることができる表現にした文字列。

たとえば、無料試用版のサブスクリプションを使用したユーザーは、無料クォータがなくなると、次のエラーを受け取ります。

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

このエラーコードは 3 桁の HTTP ステータス コードの後に､エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です｡ 一般的なエラー コード:

コード	説明
400000	無効な要求入力があります｡
400001	"scope" パラメーターが無効です｡
400002	"category" パラメーターが無効です｡
400003	言語指定子が見つからないか無効です。
400004	ターゲット スクリプト指定子 ("To script") が見つからないか無効です｡
400005	入力テキストが見つからないか無効です｡
400006	言語とスクリプトの組み合わせが無効です｡
400018	ソース スクリプト指定子 ("From script") が見つからないか無効です｡
400019	サポートされていない言語の 1 つが指定されています｡
400020	一連の入力テキストに無効な要素があります｡
400021	API バージョン パラメーターが見つからないか無効です｡
400023	無効な言語ペアが指定されています｡
400035	ソース言語 ("From" フィールド) が無効です｡
400036	ターゲット言語 ("To" フィールド) が見つからないか無効です｡
400042	無効なオプション ("Options" フィールド) が指定されています｡
400043	クライアント トレース ID (ClientTraceId フィールドまたは X-ClientTraceId ヘッダー) が見つからないか、無効です。
400050	入力テキストが長すぎます。 「要求の制限」を参照してください。
400064	"translation" パラメーターが見つからないか無効です｡
400070	ターゲット スクリプト (ToScript パラメーター) の個数がターゲット言語 (To パラメーター) の個数と一致しません｡
400071	TextType に対する値が無効です。
400072	一連の入力テストの要素数が多すぎます｡
400073	スクリプト パラメーターが無効です｡
400074	要求の本体が有効な JSON ではありません｡
400075	言語ペアとカテゴリの組み合わせが無効です｡
400077	要求の最大サイズを超えています。 「要求の制限」を参照してください。
400079	from 言語と to 言語間の翻訳に要求されたカスタム システムは存在しません｡
400080	音訳は言語またはスクリプトに対してサポートされていません。
401000	資格情報が見つからないか無効なため、要求は許可されません｡
401015	｢指定された資格情報は Speech API に対するものです｡ この要求には､Text API に対する資格情報が必要です｡ Translator にサブスクリプションを使用してください。」
403000	操作は許可されていません。
403001	サブスクリプションが無料クォータを超えているため､この操作は許可されていません｡
405000	要求リソースに対してこの要求メソッドを使用することはできません｡
408001	要求された翻訳システムを準備しています。 少し待ってから再試行してください。
408002	受信ストリームの待機中に要求がタイムアウトになりました。 サーバーが待機するように設定された時間以内に、クライアントは要求を生成しませんでした。 クライアントは、それ以降いつでも変更せずに要求を繰り返すことができます。
415000	Content-Type Content-type ヘッダーが見つからないか無効です。
429000､429001､429002	クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。
500000	予期しないエラーが発生しました。 エラーが解決しない場合は、エラーの発生日時と応答ヘッダーの要求識別子 X-RequestID、要求ヘッダーのクライアント識別子 X-ClientTraceID を添えてその旨をご報告ください。
503000	サービスが一時的に利用できません。 再試行してください。 エラーが解決しない場合は、エラーの発生日時と応答ヘッダーの要求識別子 X-RequestID、要求ヘッダーのクライアント識別子 X-ClientTraceID を添えてその旨をご報告ください。

メトリック

メトリックを使用すると、次のスクリーンショットに示すように、Azure portal の [メトリック] セクションで、トランスレーターの使用状況と可用性の情報を表示できます。 詳細については、データとプラットフォームのメトリックに関するページを参照してください。

次の表に、使用可能なメトリックと、それらを翻訳の API 呼び出しの監視に使用する方法についての説明を示します。

メトリック	説明
TotalCalls	API 呼び出しの合計数
TotalTokenCalls	認証トークンを使用した、トークン サービスを介した API 呼び出しの合計数。
SuccessfulCalls	成功した呼び出しの数。
TotalErrors	エラー応答を含む呼び出しの数。
BlockedCalls	レートまたはクォータの制限を超えた呼び出しの回数。
ServerErrors	サーバー内部エラー (5XX) が発生した呼び出しの数。
ClientErrors	クライアント側エラー (4XX) が発生した呼び出しの数。
Latency	要求を完了するまでの時間 (ミリ秒単位)。
CharactersTranslated	受信テキスト要求の合計文字数。