Translator v3.0

[アーティクル]
04/29/2024

新機能

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

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

ベース URL

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

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

✔️ 機能: 翻訳テキスト

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

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

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

たとえば、Azure portal Resource regionSwitzerland North でリソース名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

スクリーンショット: Azure portal の 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) 機能で使用できるようになりました。 Virtual Network を有効にするには、Azure AI サービス仮想ネットワークを構成する方法に関するページを参照してください。

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

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

Azure portal で、Translator リソースに移動します。
[リソース管理] セクションで [ネットワーク] を選択します。
[ファイアウォールと仮想ネットワーク] タブで、[選択したネットワークとプライベートエンドポイント] を選択します。
[保存] を選択して変更を保存します。
[リソース管理] セクションで、[キーとエンドポイント] を選択します。
[仮想ネットワーク] タブを選択します。
テキスト翻訳とドキュメント翻訳のエンドポイントが一覧表示されています。

ヘッダー	説明
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-ClientTranceId ヘッダー) が見つからないか無効です｡
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	受信テキスト要求の合計文字数。

Translator v3.0

新機能

ベース URL

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

認証

秘密鍵

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

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

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

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

Microsoft Entra ID を使った認証

前提条件

ヘッダー

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

使用例

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

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

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

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

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

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

エラー

メトリック

その他のリソース

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

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

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

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

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

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

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

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

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

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